Scout

Browser MCP server that connects to your existing browser. Your sessions, passwords, extensions — all preserved. No bot detection because it IS your real browser.

Gives AI agents a visually-grounded, semantically-precise view of any web page through hybrid A11y + Set-of-Marks grounding.

Why Scout?

Most browser automation launches a clean, disposable browser — no cookies, no history, no extensions. Every site detects it as a bot. Scout flips this: it connects to the browser you're already using via Chrome DevTools Protocol (CDP).

• Connect to your browser — attach to Chrome with --remote-debugging-port, reuse all your logged-in sessions

• Accessibility tree extraction — scans the DOM for interactive elements, assigns each a stable numeric ID, returns a compact markdown summary

• Set-of-Marks badges — overlays numbered badges on a compressed screenshot so the agent can see what it's clicking

• Non-blocking human handoff — agent returns immediately, polls for completion. CAPTCHAs, MFA, SMS codes — you solve them in your own browser

• State healer — every action captures before/after state, telling the agent what changed

The result: agents reference elements by ID (scout_click(3)), not by CSS selector or pixel coordinate. No hallucination, no token bloat, no bot detection.

Quick start

Connect to your browser (recommended)

# 1. Start your browser with remote debugging enabled
google-chrome --remote-debugging-port=9222

# 2. Install and run Scout
npm install
SCOUT_MODE=connect SCOUT_CONNECT_URL=http://localhost:9222 npm run dev

Scout auto-discovers your browser and connects. All your open tabs, sessions, and saved passwords are available.

Launch a fresh browser

npm install
npx playwright install chromium
npm run dev

Claude Desktop / Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "scout": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/scout",
      "env": {
        "SCOUT_MODE": "connect",
        "SCOUT_CONNECT_URL": "http://localhost:9222"
      }
    }
  }
}

Docker

docker build -t scout .
docker run -it scout

Environment variables

Connection

Browser

Tools (27)

Navigation

Observation

Interaction

Human-in-the-loop

Tabs

Sessions

Performance

Login (opt-in)

How it works

Typical agentic loop

scout_navigate(url)
  → read numbered element list + badged screenshot
  → scout_click(3)          # healer returns stateChange
  → scout_snapshot()        # re-snapshot after state change
  → scout_type(7, "hello")
  → scout_handoff("Solve the CAPTCHA, then click Done")
  → scout_handoff_check(handoff_id)   # poll until completed

Connection modes

Connect mode (SCOUT_MODE=connect) — attaches to your running browser via CDP. Your open tabs, sessions, and passwords are all available. Start your browser with:

google-chrome --remote-debugging-port=9222

Scout auto-discovers the browser, or set SCOUT_CONNECT_URL=http://localhost:9222 explicitly. The browser stays running independently — Scout just connects to it.

Launch mode (SCOUT_MODE=launch) — starts a fresh Chromium instance. Use SCOUT_PROFILE_DIR for persistent cookies across restarts.

Auto mode (SCOUT_MODE=auto, default) — tries to discover a running browser first. If none found, launches a fresh one. Best of both worlds.

Browser persistence

In connect mode, Scout reconnects to your browser automatically if the MCP process restarts — the browser stays running.

In launch mode, Scout writes the CDP port to ~/.scout-browser.port and reconnects on restart if the browser is still alive.

Non-blocking handoff

Unlike blocking human-in-the-loop approaches, scout_handoff returns immediately with a handoff_id. The agent polls scout_handoff_check on its own schedule. The handoff banner re-injects across page navigations and auto-expires after timeout.

This matters because MCP tool calls often have timeouts (30-60s). A CAPTCHA that takes the user 2 minutes would kill a blocking approach.

HTTP dispatch server (optional)

Set SCOUT_LCP_PORT=8091 to expose an HTTP API alongside the MCP stdio transport. Useful for integrating Scout with non-MCP systems:

GET  /lcp/health              # Server status
POST /lcp/dispatch             # Execute tool operations
GET  /lcp/stream               # SSE event stream

Security: The LCP server has no built-in authentication by default. Set SCOUT_LCP_SECRET to require an X-Scout-Secret header on all mutation endpoints. Do not expose the LCP port on a public network without authentication — it provides full control over the connected browser session.

License

MIT