secure-browser-mcp

Features

• Fill by reference: The agent holds an opaque secret reference and cannot read the value. It calls fill_secret, and the broker injects the plaintext straight into the page over raw CDP

• Secrets stay out of the context: The agent never receives the secret value. Every tool result passes through a single redaction choke point before it reaches the model context, the transcript, or logs. Redaction also catches copies that the page reformats, re-renders, or echoes into other elements. End-to-end tests assert no leak over the wire. A destination page can always encode a value past redaction; see docs/THREAT-MODEL.md

• Destination bindings: Each secret binds at import to an exact origin, URL pattern, and field selector. A page that talks the agent into filling anywhere else gets a broker-side refusal before any export

• Consensus approvals: Turnkey policies decide who must sign an export. A gated fill parks as pending_approval; a human approves the activity, and await_fill completes the fill. Approvers still cannot read the value — only an ephemeral key held by the broker can decrypt it

• One approval per form: A JSON-payload secret (card number, expiry, CVC) fills several fields in one call, under one export and one approval

• Secure enclave storage: Credentials live in Turnkey Secrets, so no single party can access them alone. That includes Turnkey, and it includes the agent

• Cryptographic audit trail: Every export request, approver, and destination lands as a signed Turnkey activity you can query

• Any MCP client: Point Claude Code, Codex, or any agent framework at the server over stdio, or at a hosted broker by URL (docs/HOSTED.md)

• Skill and evals included: Ships with an Agent Skill that teaches agents the workflow and an eval harness that runs real headless agent sessions and hard-fails any leak

Related MCP server: PhantomAuth

Overview

Secure Browser MCP is an MCP server that acts as a credential broker and owns its own browser. The agent drives the browser through a small set of tools. Passwords, cards, and API keys stay in Turnkey Secrets until a fill passes policy. The broker then exports the secret, decrypts it in its own process memory, and types it into the bound field. The agent sees only [REDACTED].

Ask an agent to buy something. It navigates to checkout and requests the stored card. The card requires a human approver, so the fill pauses until someone signs the export in the Turnkey dashboard. All three card fields fill under that single approval, the payment succeeds, and the card number never appears in any byte the server sent.

There is no evaluate_script tool. That is a security decision, not a gap — see docs/DESIGN.md and docs/THREAT-MODEL.md.

Quickstart

Using Hermes? Start with the Hermes setup guide for installation, MCP configuration, a first local login and checkout, and the transition to Turnkey Secrets. No Turnkey account is needed for the local demo.

bun install
bun test          # e2e: fills secrets into a local storefront and asserts
                  # the plaintext never appears in server output
bun run dev       # starts the MCP server on stdio
bun run serve     # or over Streamable HTTP; see docs/HOSTED.md

The server needs a Chromium-based browser. It checks SBM_CHROME_PATH first, then common install locations (Chrome, Chromium, Brave, Edge). Set SBM_HEADLESS=false to watch it work.

Connect it to Claude Code:

claude mcp add secure-browser -- bun run /path/to/secure-browser-mcp/src/index.ts
bun run skill:install -- --claude   # teaches the agent the fill protocol

Try it: bun run demo:fixture serves a demo storefront at http://localhost:4173 (login at /login, checkout at /checkout), pre-wired to seeded mock secrets.

Backends

The server uses an in-memory mock backend by default. Set these to use real Turnkey Secrets (closed beta):

export TURNKEY_API_PUBLIC_KEY=...
export TURNKEY_API_PRIVATE_KEY=...
export TURNKEY_ORGANIZATION_ID=...

TURNKEY_API_BASE_URL selects the Turnkey environment (default https://api.turnkey.com). An environment with its own enclaves also needs TURNKEY_SIGNER_PUBLIC_KEY, the quorum key that signs its secret bundles; without it every import and export fails signature verification.

To import your own credential, use bun run scripts/import-secret.ts --help and follow the generic import walkthrough. list_secret_refs reports the active backend alongside references. Cross-origin iframe inputs (including embedded Stripe Elements) are currently unsupported; verify the broker can see your target fields before importing.

A secret is fillable when it is imported with binding static properties: sbm:origin (required), sbm:url-pattern, sbm:selector, or sbm:fields for JSON payloads — see src/broker/types.ts. Bindings are immutable after import. A secret with a malformed binding is never fillable, and a secret with sbm:fields fills only by key.

To require approval for exports, add a Turnkey policy whose consensus names both the broker user (its submission is the first vote) and the approver:

approvers.any(user, user.id == '<broker-user-id>') && approvers.any(user, user.id == '<approver-user-id>')

For a real-world walkthrough — an agent paying a Stripe test checkout with a card it can never read — see docs/DEMO-STRIPE.md.

Agent Skill and evals

skills/secure-browser/ is an Agent Skill that teaches agents the protocol: secrets are handles, binding rejections are policy, pending approvals are normal. Install with bun run skill:install -- --claude, --codex, or --hermes. Claude supports --project for a repo-local install; Hermes uses $HERMES_HOME/skills when set, otherwise ~/.hermes/skills. You can also copy the folder anywhere a skills-compatible agent looks.

evals/ runs a real headless agent against the server and grades the transcript: no leakage (hard fail), fill_secret used instead of type_text, task completed, plus tool-call metrics for spotting regressions. bun run eval — see evals/README.md.

Development