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

Variable	Default	Description
SCOUT_MODE	auto	connect (attach to your browser), launch (start fresh), auto (try connect, fallback to launch)
SCOUT_CONNECT_URL	—	Explicit browser debug URL, e.g. http://localhost:9222

Browser

Variable	Default	Description
SCOUT_HEADLESS	false	Run browser in headless mode (only applies to launch mode)
SCOUT_BROWSER	chromium	Browser engine for launch mode (chromium or firefox)
SCOUT_CDP_PORT	9229	Debug port when launching a fresh browser
SCOUT_VIEWPORT_WIDTH	1280	Browser viewport width
SCOUT_VIEWPORT_HEIGHT	800	Browser viewport height
SCOUT_MAX_ELEMENTS	1000	Max elements per snapshot
SCOUT_MAX_TABS	10	Max open tabs
SCOUT_PROFILE_DIR	—	Persistent browser profile path (launch mode only)
SCOUT_LOGIN_ENABLED	false	Enable scout_login tool for automated platform auth
SCOUT_LCP_PORT	—	Enable HTTP dispatch server on this port

Tools (27)

Navigation

Tool	Params	Description
scout_navigate	url	Navigate and return full snapshot
scout_back	—	Browser back
scout_forward	—	Browser forward
scout_refresh	—	Reload current page

Observation

Tool	Params	Description
scout_snapshot	—	Full snapshot: numbered element list + badged screenshot
scout_elements	—	Element list only (faster, no screenshot)
scout_screenshot	—	Plain screenshot without badges
scout_console_logs	clear?	Last 100 browser console logs/errors

Interaction

Tool	Params	Description
scout_click	id	Click element by snapshot ID
scout_type	id, text, clear?	Type into input (React-safe keyboard events)
scout_select	id, value	Select dropdown option
scout_hover	id	Hover over element
scout_press_key	key	Press keyboard key (Enter, Escape, etc.)
scout_drag	sourceId, targetId	Drag one element onto another
scout_scroll	direction, pixels?	Scroll up/down/left/right

Human-in-the-loop

Tool	Params	Description
scout_handoff	instruction, timeout?	Show banner asking user to take manual action. Returns immediately with handoff_id — does NOT block.
scout_handoff_check	handoff_id	Poll whether handoff is completed/expired
scout_handoff_cancel	handoff_id	Cancel handoff and remove banner

Tabs

Tool	Params	Description
scout_tabs	—	List all open tabs
scout_switch_tab	index	Switch active tab
scout_new_tab	url?	Open a new tab

Sessions

Tool	Params	Description
scout_save_session	name	Save cookies + localStorage to ~/.scout-sessions/<name>.json
scout_load_session	name	Restore a saved session (restarts browser context)
scout_list_sessions	—	List saved sessions

Performance

Tool	Params	Description
scout_wait	condition, value?, timeout?	Wait for navigation, network_idle, selector, or timeout
scout_block_resources	types	Block resource types (e.g. ["image", "media"])

Login (opt-in)

Tool	Params	Description
scout_login	platform, username, password	Automated social login with challenge detection. Requires SCOUT_LOGIN_ENABLED=true.

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