MCP Directory

How to add Auto Browser to Windsurf

MCP-native browser control plane with human takeover, reusable auth profiles, approvals, and audit trails. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 579★ · stdio · no auth

Windsurf config for Auto Browser

uvx auto-browser-mcp
{
  "mcpServers": {
    "auto-browser": {
      "command": "uvx",
      "args": [
        "auto-browser-mcp"
      ],
      "env": {
        "AUTO_BROWSER_BASE_URL": "http://127.0.0.1:8000/mcp",
        "AUTO_BROWSER_BEARER_TOKEN": ""
      }
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Auto Browser config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Auto Browser's tools become available to Cascade.

Before you start

  • Docker and Docker Compose to run the controller and browser-node stack locally
  • The Auto Browser controller running and reachable at http://127.0.0.1:8000/mcp
  • uv / uvx installed to run the stdio bridge via `uvx auto-browser-mcp` (or Python 3.10+ to run scripts/mcp_stdio_bridge.py from a checkout)
  • An MCP client such as Claude Desktop or Cursor

What Auto Browser can do in Windsurf

browser.create_session

Create a new browser session, optionally with a name, start_url, and a saved auth_profile to resume pre-authenticated.

browser.list_sessions

List active browser sessions.

browser.verify_witness

Read-only tool that walks the full hash-chained Witness receipt log for a session and reports the first divergent receipt if the log was altered, reordered, or truncated.

harness.list_runs

Read-only convergence-harness tool (curated profile) to list harness runs.

harness.get_status

Read-only convergence-harness tool (curated profile) to inspect the status of a harness run.

harness.get_trace

Read-only convergence-harness tool (curated profile) to fetch the recorded trace of a harness run.

harness.start_convergence

Full-profile tool that starts a convergence run against a live browser session (use workflow_profile=governed).

harness.list_candidates

Full-profile tool to list staged skill candidates produced by convergence runs.

Security

The MCP stdio bridge proxies the client to the local controller at http://127.0.0.1:8000/mcp; all published ports bind to 127.0.0.1 by default. The example config leaves AUTO_BROWSER_BEARER_TOKEN empty for local development. For real private deployments the README recommends setting APP_ENV=production, a strong API_BEARER_TOKEN (and the matching AUTO_BROWSER_BEARER_TOKEN on the bridge), REQUIRE_OPERATOR_ID=true, AUTH_STATE_ENCRYPTION_KEY (44-char Fernet) with REQUIRE_AUTH_STATE_ENCRYPTION=true, REQUEST_RATE_LIMIT_ENABLED=true, METRICS_ENABLED=true, and STEALTH_ENABLED=false. COMPLIANCE_TEMPLATE (strict or balanced) can apply a hardened posture at startup. Authorized workflows only; the project explicitly does not support CAPTCHA solving, unauthorized scraping, or bypass tooling.

Auto Browser + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Auto Browser config there under the "mcpServers" key and restart the client.

Is Auto Browser safe to use with Windsurf?

The MCP stdio bridge proxies the client to the local controller at http://127.0.0.1:8000/mcp; all published ports bind to 127.0.0.1 by default. The example config leaves AUTO_BROWSER_BEARER_TOKEN empty for local development. For real private deployments the README recommends setting APP_ENV=production, a strong API_BEARER_TOKEN (and the matching AUTO_BROWSER_BEARER_TOKEN on the bridge), REQUIRE_OPERATOR_ID=true, AUTH_STATE_ENCRYPTION_KEY (44-char Fernet) with REQUIRE_AUTH_STATE_ENCRYPTION=true, REQUEST_RATE_LIMIT_ENABLED=true, METRICS_ENABLED=true, and STEALTH_ENABLED=false. COMPLIANCE_TEMPLATE (strict or balanced) can apply a hardened posture at startup. Authorized workflows only; the project explicitly does not support CAPTCHA solving, unauthorized scraping, or bypass tooling.

How does an MCP client connect to Auto Browser?

Start the stack locally (docker compose up --build), then point a stdio-first client like Claude Desktop at the bundled bridge via `uvx auto-browser-mcp`, with AUTO_BROWSER_BASE_URL set to http://127.0.0.1:8000/mcp. HTTP-capable clients can talk to the /mcp endpoint directly.

Which tools are available by default?

The default MCP_TOOL_PROFILE is `curated`, which keeps the browser surface compact and hides approval-admin, agent-queue, provider-introspection, and remote-access-admin tools. Read-only harness inspection tools are included. Set MCP_TOOL_PROFILE=full to expose the full surface, including harness.* convergence tools and the agent-queue tools.

How do I secure a non-local deployment?

Set APP_ENV=production, a strong API_BEARER_TOKEN (and the matching AUTO_BROWSER_BEARER_TOKEN on the bridge), REQUIRE_OPERATOR_ID=true, AUTH_STATE_ENCRYPTION_KEY with REQUIRE_AUTH_STATE_ENCRYPTION=true, rate limiting, and metrics. COMPLIANCE_TEMPLATE=strict or =balanced applies a preconfigured posture at startup.

View repo Full Auto Browser page