MCP server

twin-browser-mcp exposes the execution engine as 35 native tools over stdio to any MCP client — Cursor, Claude Desktop, Claude Code, Cline, or your own. One API key, nothing to install or clone: the client launches the server via npx. Every target-bearing tool is authenticated with your key, scoped to your tenant, metered, and audited.

1 · Get a key

The hosted server needs a single Twin Browser API key from Keys & Secrets.

# 1. Create an API key at https://twin-browser.com/dashboard/keys
#    (starts with ab_live_…). That's the only thing the hosted server needs.

# 2. Optional — smoke-test the server yourself before wiring it into a client:
TWIN_API_KEY=ab_live_… npx -y twin-browser-mcp
#    → "transport: customer (web API at https://twin-browser.com …)"

2 · Register the server

Pick the config for your client — the shape is the same everywhere.

// .cursor/mcp.json  (project) or ~/.cursor/mcp.json (global)
// HOSTED setup — one variable, nothing to install. Every tool routes through the web API.
{
  "mcpServers": {
    "twin-browser": {
      "command": "npx",
      "args": ["-y", "twin-browser-mcp"],
      "env": {
        "TWIN_API_KEY": "ab_live_…"
      }
    }
  }
}

// claude_desktop_config.json → mcpServers
// HOSTED setup — one variable. WEB_BASE_URL defaults to https://twin-browser.com.
{
  "mcpServers": {
    "twin-browser": {
      "command": "npx",
      "args": ["-y", "twin-browser-mcp"],
      "env": {
        "TWIN_API_KEY": "ab_live_…"
      }
    }
  }
}

# Claude Code CLI — register the server in one line. Cline uses the same shape.
# HOSTED setup — one variable, nothing to install. (Operators running their own
# engine add EXEC_URL + EXEC_SHARED_SECRET instead.)
claude mcp add twin-browser \
  --env TWIN_API_KEY=ab_live_… \
  -- npx -y twin-browser-mcp

Environment & modes

Hosted-only mode (recommended): set ONLY TWIN_API_KEY — WEB_BASE_URL defaults to https://twin-browser.com — and every tool routes through the hosted web API under your key. The startup log names the resolved mode: look for [twin-browser-mcp] transport: customer in your MCP client's logs; if it says operator, stale EXEC_URL/EXEC_SHARED_SECRET env is set.

Operator mode: running your own engine, set EXEC_URL (default http://localhost:7070) and EXEC_SHARED_SECRET instead of a key and the server talks to your fleet directly. The web-backed tools — search_library, dispatch, deep_search, etl/etl_query, the monitor tools, and the streamed-run branch of submit_verification — still need WEB_BASE_URL + TWIN_API_KEY.

3 · The tools

Lead with dispatch, run_goal, compile_skill and run_skill — the rest cover async jobs, observation, extraction, search, crawl, ETL, monitors, sessions, CAPTCHA, and recording.

Capture a session from your own browser

For sites whose sign-in is hard to automate remotely — popup-based “Continue with Google”, hardware-attested logins — sign in on your OWN browser (where OAuth just works) and hand the session to Twin Browser. Your password never leaves your browser; only the resulting session cookies are sent, encrypted at rest.

Use it

# Once connected, ask your agent in natural language, e.g.:
#   "Compile a skill that logs into app.acme.com and exports invoices,
#    then replay it." → compile_skill → run_skill (no LLM on replay)
#   "Search the library for 'export invoices as CSV' on app.acme.com"
#    → search_library
# Every target-bearing call is authenticated with your key and acts on the
# url you pass — scoped to your tenant, metered, and written to the audit log.

Replays run with no LLM: run_skill replays a compiled skill deterministically, and compile_skill discovers a path once and minimizes it for reuse — so repeated tasks avoid the per-run model cost entirely.