docs(blog): add audit trail API logs companion post

content/blog/2026-04-20-chrome-devtools-mcp/index.mdx

@@ -0,0 +1,241 @@
+---
+title: How to Add MCP Browser Automation to AI Agents
+description: Connect Google's Chrome DevTools MCP server to Molecule AI — and govern which agents get browser access, what they can do, and who's accountable. Tutorial + code sample.
+publishedAt: 2026-04-20
+---
+
+Google shipped a Chrome DevTools MCP server in early 2026 — and with it, the ability to give any MCP-compatible AI agent full programmatic control of a Chrome browser instance. Screenshots, DOM inspection, network interception, JavaScript execution: all exposed as tools through a standards-based interface. The browser, finally, is a first-class MCP resource.
+
+That's also exactly the problem. Raw CDP access is all-or-nothing: either your agent can do everything Chrome can do, or it can't. For prototypes, that's fine. For production deployments — especially ones that touch customer-facing workflows or authenticated sessions — you need something between "no browser" and "full admin." You need a governance layer.
+
+Every AI agent platform can give an agent access to Chrome DevTools. **Molecule AI gives you the governance layer** to decide which agents get it, what they can do with it, and how to revoke it — before you put it in front of customers. This guide walks through the setup, the code, and the controls.
+
+## What is the Chrome DevTools MCP Server?
+
+The [Chrome DevTools MCP server](https://github.com/google/chrome-devtools-mcp) is Google's official Model Context Protocol implementation for Chrome's CDP (Chrome DevTools Protocol). Once connected to an MCP client, it exposes a structured set of browser-automation tools:
+
+- **`navigate`** — load a URL in a headless or headed Chrome instance
+- **`screenshot`** — capture the current DOM as a PNG
+- **`get_document`** — read the full DOM tree
+- **`evaluate`** — execute JavaScript in the page context
+- **`storage`** — read/write cookies, localStorage, IndexedDB
+- **Network interception** — observe and modify HTTP requests and responses
+
+Because these are MCP tools, they integrate with any MCP-compatible agent platform — including Molecule AI — without custom CDP wrappers or browser-driver installation.
+
+## MCP Browser Automation: Platform vs. Raw Tool Access
+
+Before writing code, it's worth understanding what you're choosing between. Not all MCP integrations are equivalent when it comes to governance.
+
+| Capability | Raw CDP / Puppeteer | MCP-Ready Platform (Molecule AI) |
+|---|---|---|
+| Agent gets browser tools | ✅ | ✅ |
+| Per-agent permission scoping | ❌ | ✅ |
+| Revoke access without restart | ❌ | ✅ |
+| Audit trail on browser actions | ❌ | ✅ |
+| Org-level access control | ❌ | ✅ |
+| Multi-agent browser session coordination | Manual | Built-in |
+
+The **MCP governance layer** is the difference column. Molecule AI's MCP integration doesn't just wire Chrome DevTools to your agents — it layers org-level access control, per-agent permission scoping, and an audit trail onto every browser action your agents take. You don't have to build that yourself.
+
+## How to Connect Chrome DevTools MCP to Molecule AI
+
+The setup has two parts: configuring Chrome DevTools MCP in your workspace, and verifying the connection works end-to-end.
+
+### Prerequisites
+
+- A running Molecule AI deployment (self-hosted or SaaS)
+- Chrome or Chromium installed (or a remote debugging port open)
+- A workspace with the `browser-automation` plugin enabled (or admin access to install it)
+
+### Step 1: Enable the MCP server
+
+Molecule AI uses its own [MCP server as the platform connector](/docs/guides/mcp-server-setup). To add Chrome DevTools MCP, install it alongside the Molecule MCP server in your workspace's MCP config:
+
+```json
+// .mcp.json in your workspace config directory
+{
+  "mcpServers": {
+    "molecule": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@molecule-ai/mcp-server@latest"],
+      "env": {
+        "MOLECULE_URL": "${MOLECULE_URL}"
+      }
+    },
+    "chrome-devtools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-chrome-devtools"]
+    }
+  }
+}
+```
+
+On self-hosted Molecule AI, restart the workspace after editing the config. On SaaS, save the config and the workspace will hot-reload.
+
+### Step 2: Verify with a Python test
+
+```python
+"""
+Chrome DevTools MCP — connection verification script.
+Run this from a Molecule AI workspace terminal, or locally
+with the chrome-devtools MCP server installed.
+Requires: npx, Chrome/Chromium
+"""
+
+import subprocess
+import json
+import time
+
+# Step 1: Start Chrome in remote-debugging mode
+chrome = subprocess.Popen(
+    ["google-chrome", "--remote-debugging-port=9222"],
+    stdout=subprocess.DEVNULL,
+    stderr=subprocess.DEVNULL,
+)
+time.sleep(2)
+
+# Step 2: Initialize the Chrome DevTools MCP server
+init_result = subprocess.run(
+    ["npx", "@modelcontextprotocol/server-chrome-devtools"],
+    input=json.dumps({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "test-client", "version": "1.0.0"}
+        }
+    }).encode(),
+    capture_output=True,
+)
+print("Init:", init_result.stdout.decode()[:200])
+
+# Step 3: Navigate to a page
+navigate_req = json.dumps({
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/call",
+    "params": {
+        "name": "navigate",
+        "arguments": {"url": "https://example.com", "debuggingPort": 9222}
+    }
+}).encode()
+
+nav_result = subprocess.run(
+    ["npx", "@modelcontextprotocol/server-chrome-devtools"],
+    input=navigate_req,
+    capture_output=True,
+)
+print("Navigate:", nav_result.stdout.decode()[:300])
+
+chrome.terminate()
+print("✅ Chrome DevTools MCP connected successfully")
+```
+
+This script confirms Chrome DevTools MCP tools are reachable from your workspace before you wire them into an agent prompt.
+
+## AI Agent Browser Control: Governance in Practice
+
+Having browser tools is one thing. Controlling who uses them, how, and when is where Molecule AI's MCP governance layer earns its keep.
+
+### Scoping browser access per agent
+
+In Molecule AI, each workspace has its own MCP configuration. You can restrict Chrome DevTools MCP to only the agents that need it:
+
+```yaml
+# org.yaml — role-level MCP scoping
+roles:
+  researcher:
+    mcp_servers: ["chrome-devtools", "molecule"]
+  # Report agents get the Molecule platform tools but NOT browser access
+  report_writer:
+    mcp_servers: ["molecule"]
+```
+
+Agents assigned the `researcher` role can use screenshot, evaluate, and navigate. Agents assigned `report_writer` cannot — the `chrome-devtools` MCP server is never loaded for their workspace.
+
+### Revoking browser access
+
+When an agent's task is done, or when you need to revoke access immediately:
+
+```bash
+# Revoke by removing the MCP server from the workspace config
+curl -X PATCH https://your-deployment.moleculesai.app/workspaces/ws_abc123/config \
+  -H "Authorization: Bearer $ORG_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "mcp_servers": ["molecule"]
+  }'
+```
+
+No restart required — the workspace hot-reloads the MCP config. The next agent heartbeat picks up the new tool list.
+
+### Audit trail: who used the browser, when
+
+Browser actions are logged in the standard [Molecule AI activity log](/docs/guides/org-api-keys), tied to the org API key used to call the platform. When a workspace agent makes a screenshot tool call via the Chrome DevTools MCP integration, the audit entry captures:
+
+- **Workspace ID** — which agent took the action
+- **Org API key prefix** — which integration token authenticated the call
+- **Tool name** — `chrome-devtools:screenshot`, `chrome-devtools:navigate`, etc.
+- **Timestamp and duration** — for SLA and latency tracking
+
+```
+2026-04-20T14:23:01Z  tool_call  ws_pm_01  mole_a1b2...  chrome-devtools:screenshot  312ms
+2026-04-20T14:23:09Z  tool_call  ws_pm_01  mole_a1b2...  chrome-devtools:evaluate   89ms
+```
+
+This matters for compliance: when a customer asks "who accessed my session data via the browser agent," the answer is in your org API key audit log — not buried in a raw CDP trace you had to set up separately.
+
+## Use Cases: Where Browser Automation Fits in AI Agent Workflows
+
+### Automated Lighthouse audits
+
+Run Google Lighthouse on any URL as part of a CI/CD pipeline agent task:
+
+```
+Agent: "Run a performance audit on https://app.example.com"
+Tool: chrome-devtools:navigate + chrome-devtools:evaluate
+       → injects Lighthouse JS → captures scores
+       → writes to shared memory → PM agent notified of regressions
+```
+
+### Screenshot-based visual regression
+
+Agents can capture before/after screenshots as part of a review workflow — no need for separate screenshot infrastructure:
+
+```
+Agent: "Compare the checkout flow before and after the update"
+Tool: chrome-devtools:screenshot (url=https://app.example.com/checkout)
+       → saves to workspace files → next agent reviews diff
+```
+
+### Authenticated session scraping
+
+For agents that need to operate behind a login — filling forms, extracting protected data, testing authenticated flows — Chrome DevTools MCP handles session cookies natively via the `storage` tool:
+
+```javascript
+// Set auth cookies before navigating to a protected page
+{
+  "name": "storage",
+  "arguments": {
+    "action": "setCookies",
+    "cookies": [{"name": "session_token", "value": "..."}],
+    "debuggingPort": 9222
+  }
+}
+```
+
+## Conclusion
+
+Chrome DevTools MCP makes browser automation a first-class MCP tool — which means it's now a first-class part of your AI agent's capability surface. The hard part isn't connecting it. The hard part is deciding which agents should have it, what they can do with it, and whether you can see who did what after the fact.
+
+Molecule AI's MCP governance layer is purpose-built for that second part. Per-agent scoping, immediate revocation, org API key audit attribution — the controls you need before browser automation goes into a customer-facing workflow.
+
+Get started:
+- [MCP server setup guide](/docs/guides/mcp-server-setup) — platform MCP connector
+- [Org API keys](/docs/guides/org-api-keys) — audit trail and access attribution
+- [chrome-devtools-mcp on GitHub](https://github.com/google/chrome-devtools-mcp) — Google's official server

content/blog/2026-04-20-org-api-keys/index.mdx

@@ -0,0 +1,119 @@
+---
+title: Org-Scoped API Keys: Enterprise Key Management for Multi-Agent Teams
+description: Molecule AI ships org-scoped API keys — named, revocable, audit-trail-enabled tokens at the org level. Rotate without downtime. Attribute every call. Revoke instantly.
+publishedAt: 2026-04-20
+---
+
+When your engineering team scales from two agents to twenty, the last thing you want is a single `ADMIN_TOKEN` hardcoded in your environment. It's a single point of failure, impossible to rotate without downtime, and impossible to audit. Today's launch changes that.
+
+Molecule AI is rolling out **org-scoped API keys** — named, revocable, audit-trail-enabled tokens that live at the organization level and can reach any workspace in your org without breaking the security model.
+
+## What Are Org-Scoped API Keys?
+
+Org-scoped API keys are long-lived credentials minted at the organization level via the Canvas UI or the `POST /org/tokens` endpoint. Each key has:
+
+- A **display name** you choose at creation time (e.g., `ci-deploy-bot`, `devops-rev-proxy`)
+- A **sha256 hash** stored server-side — the plaintext is shown once and never again
+- A **prefix** (first 8 characters) visible in listings so you can identify keys without exposing secrets
+- A **created-by** field that tracks provenance in the audit trail
+- **Immediate revocation** — drop a key and it stops being accepted on the very next request
+
+The keys work across all workspaces in your org — not just admin-surface endpoints, but also per-workspace sub-routes like `/workspaces/:id/channels` and `/workspaces/:id/tokens`.
+
+## Why Enterprise Teams Need Org-Level Key Management
+
+### The `ADMIN_TOKEN` problem
+
+A single env-var token works for prototypes. For production multi-agent systems it creates three compounding risks:
+
+1. **Rotation requires downtime.** You can't rotate a token used by ten agents simultaneously. You rotate, or you don't — and both choices are bad.
+2. **No attribution.** When something calls your API, you have no idea which agent or integration is responsible.
+3. **No compartmentalization.** One compromised token compromises everything.
+
+### What org-scoped keys give you
+
+| Capability | `ADMIN_TOKEN` | Org-Scoped Keys |
+|---|---|---|
+| Rotate without downtime | ❌ | ✅ (one key revokes, another takes over) |
+| Identify caller per request | ❌ | ✅ (audit prefix in every log line) |
+| Revoke a single integration | ❌ | ✅ (per-key revocation) |
+| Assign to workspace subroutes | ❌ | ✅ |
+| Audit trail with attribution | Partial | ✅ (`created_by` + prefix in logs) |
+
+## Audit Trail and Rate-Limit Controls
+
+Every request authenticated with an org API key carries the key's prefix in the audit log, making it straightforward to trace calls back to a specific integration. When combined with the `created_by` field stored at mint time, you get full provenance: *which admin created this key, when, and what it's been calling.*
+
+The token hierarchy, from most to least trusted:
+
+- **Lazy bootstrap** (Tier 0) — only active when there are zero org tokens and no `ADMIN_TOKEN` at all
+- **WorkOS session** (Tier 1) — verified user sessions
+- **Org API tokens** (Tier 2a) — new org-scoped keys (primary path for service integrations)
+- **`ADMIN_TOKEN` env var** (Tier 2b) — break-glass for operators, CLI tooling
+- **Workspace tokens** (Tier 3) — deprecated per-workspace tokens
+
+## How to Get Started
+
+### Mint a key via API
+
+```bash
+curl -X POST https://your-deployment.molecule.ai/org/tokens \
+  -H "Authorization: Bearer <your-admin-session-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "ci-deploy-bot",
+    "description": "GitHub Actions deploy pipeline"
+  }'
+```
+
+Response (plaintext shown once — store it securely):
+
+```json
+{
+  "id": "tok_01HXYZ...",
+  "name": "ci-deploy-bot",
+  "display_prefix": "mole_a1b2",
+  "created_at": "2026-04-20T14:00:00Z",
+  "created_by": "admin@example.com"
+}
+```
+
+### List and revoke keys
+
+```bash
+# List all active keys (prefix-only, no plaintext)
+curl https://your-deployment.molecule.ai/org/tokens \
+  -H "Authorization: Bearer <your-admin-session-token>"
+
+# Revoke a key immediately
+curl -X DELETE https://your-deployment.molecule.ai/org/tokens/tok_01HXYZ... \
+  -H "Authorization: Bearer <your-admin-session-token>"
+```
+
+### Use in a workspace sub-route
+
+```bash
+# Token hits workspace sub-route via org auth
+curl https://your-deployment.molecule.ai/workspaces/ws_abc123/channels \
+  -H "Authorization: Bearer mole_a1b2c3d4..."
+```
+
+## Org API Keys and the Browser Automation Governance Story
+
+Org-scoped API keys pair with Chrome DevTools MCP to give you a complete browser automation governance story. When an agent makes a screenshot or navigation call via Chrome DevTools MCP, every action is logged with the org API key prefix — so you can answer the question "which agent accessed what in this browser session?" without any additional instrumentation.
+
+See [Chrome DevTools MCP and the MCP Governance Layer](/blog/2026-04-20-chrome-devtools-mcp) for the full browser automation story.
+
+## Competitive Note: Hermes v0.10.0 Tool Gateway
+
+Hermes v0.10.0 ships bundled tool primitives (web search, image generation, TTS, browser automation) as platform-level features for paid Portal subscribers. This positions Hermes as "batteries included" for single-user AI. However, Hermes has no multi-agent or A2A support — its tool gateway operates in a single-user context.
+
+Molecule's org-scoped API keys reinforce a different value proposition: **enterprise-grade identity and access management for multi-agent teams.** The skills architecture offers greater composability than Hermes' bundled approach, and org tokens give teams the access-control primitives needed to deploy that composability safely in production.
+
+## Get Started
+
+Org-scoped API keys are available now on all Molecule AI deployments.
+
+- [Token Management API](/docs/guides/org-api-keys) — mint, list, and revoke org API keys
+- [Org API Keys Architecture](/docs/architecture/org-api-keys) — technical deep-dive on the auth model and audit trail
+- [Chrome DevTools MCP + Governance](/blog/2026-04-20-chrome-devtools-mcp) — browser automation with org-key audit attribution