AgentSurf

Let local (stdio) and remote (Streamable HTTP + OAuth 2.0) AI agents control the signed-in Chrome/Edge browser you already have open, with multi-PC window routing and read-only remote defaults.

Dokumentasi

AgentSurf

License Node.js MCP OAuth 2.0 Browser

English | 简体中文

Give any AI agent — local or cloud — safe control over the Chrome or Edge browser you are already signed into.

AgentSurf connects Claude Desktop, Cursor, Codex, Gemini Web, Notion AI, Dify, and any MCP-compatible agent to your real desktop browser. It reuses your existing logins and open tabs without launching headless browsers, exporting cookies, or triggering bot-detection walls.

AgentSurf live demo: MCP controls a signed-in browser tab with the AI cursor


Why AgentSurf?

If you are choosing between Playwright / Puppeteer MCP, local shell browser skills like Tencent BrowserSkill (bsk), and AgentSurf, here is why users pick AgentSurf:

  • Works with Cloud & Web AI — Not Just Local Terminals: Local CLI skills (like BrowserSkill) require an agent with local bash/shell access, and Playwright MCP launches isolated local sandboxes. AgentSurf exposes standard MCP (stdio + Streamable HTTP) with built-in OAuth 2.0 (PKCE) so Gemini Web, Notion AI, Dify, and mobile/cloud workflows can drive your real desktop browser with zero local shell permission required.
  • Home + Office Multi-PC on One Gateway: Instead of one daemon bound to one machine, both your home and office browsers connect to the same wss://.../ws endpoint without kicking each other offline—automatically routing to whichever Chrome window you are actively using.
  • No Shell Execution Risk & Built for Token Efficiency: Unlike CLI-driven browser skills, your agent never needs shell access to control the browser. Interactive snapshots are filtered and capped inside the page before crossing the wire—on a reference 665-element app page (245 KB raw JSON), the default 150-element cap cuts output from ~66,800 to ~15,100 tokens, and filtering hidden UI (visible_only: true) or querying by tag / role / name_contains shrinks it further depending on visible page density.
  • Self-Hosted Privacy & Zero Lock-In: No third-party cloud relay, no telemetry, and no account required. Run 100% offline locally or self-host the single-file standalone-gateway.js (read-only by default on remote, hashed tokens, SHA-256 operation idempotency journal, and zero MAIN-world console patching).
CapabilityAgentSurfLocal Shell Browser Skills (e.g. Tencent BrowserSkill)Headless MCP (Playwright / Puppeteer)
Reuses signed-in Chrome / EdgeYes (live tabs & cookies)Yes (live browser via extension)No (starts fresh or needs brittle profile copies)
Anti-bot friendlinessReal desktop browser sessionReal desktop browser sessionOften flagged by headless automation signals
Agent protocolStandard MCP (stdio + Streamable HTTP) — no shell requiredLocal CLI (bsk) — requires shell-capable coding agentLocal stdio / local server MCP
Cloud Web Agents (Gemini Web, Notion AI, Dify)Built-in OAuth 2.0 (PKCE) + Bearer + Reverse WSSLocal shell agents onlyLocal only unless custom-wrapped
Home + Office multi-PC routingYes — active-window auto-routing, session stickiness & pinningSingle local machine daemonSingle local process
Context & token footprintIn-page filtering (visible_only, tag, role, name_contains) + 150-element capPage extraction via CLI commandsLarge raw DOM / AX tree dumps
Safety & isolationRemote read-only default, per-session Tab Groups, operation_unknown idempotency, zero MAIN-world patchingDedicated agent window / tab borrowing + human confirmationShared browser state; full read/write by default

Key Features

  • Dual-Channel Transport:
    • Local Native (stdio): Zero network dependencies, ultra-low latency via Chrome Native Messaging + loopback bridge (127.0.0.1:8765).
    • Cloud Remote Gateway (Streamable HTTP + Reverse WSS): Deploy a single self-contained standalone-gateway.js on any VPS. Your local browser initiates an outbound encrypted WebSocket connection—no port forwarding, SSH tunnels, or public IP needed on your PC.
  • Full OAuth 2.0 + PKCE & Bearer Token Support:
    • Implements MCP OAuth discovery (/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server), Client ID / Client Secret, S256 PKCE, consent UI, and refresh tokens—ready for Gemini Web.
    • Also supports static Bearer Token headers for Notion AI, Dify, and custom HTTP MCP agents.
  • Port-Agnostic Public Routing:
    • Host, Origin, and OAuth metadata adapt dynamically to the incoming request Host and X-Forwarded-Proto, so one gateway config works across standard port 443 or any alternate reverse-proxy port.
  • Multi-Computer Coexistence (Home + Office):
    • Connect multiple computers (e.g., Home and Office) to the same wss://.../ws endpoint without kicking each other offline.
    • Routes automatically to whichever Chrome window you actively focused/used most recently, locks active sessions to their originating computer, and supports pinning in the extension popup or explicit device targeting.
  • 29 Browser Control Tools (Token-Efficient by Design):
    • Semantic interactive element snapshots (browser_get_interactives with opaque element_ids, in-page filtering by tag / role / name_contains / visible_only, and default 150 cap—trimming a 245 KB / 665-element raw snapshot to 150 elements by default, and much smaller when scoped to visible or matching controls).
    • Page content extraction, click/double-click/type/press/select/checkbox/drag/scroll, viewport & full-page screenshots, iframe navigation, JS dialog handling, downloads, and file uploads (DOM.setFileInputFiles).

Architecture

flowchart LR
  subgraph Local["Local Mode (Zero Network)"]
    LAgent["Claude Desktop / Cursor / Codex"] -->|stdio MCP| LServer["agentsurf-mcp"]
    LServer -->|Local WS| NHost["Native Messaging Host"]
    NHost -->|Native Messaging| Ext["AgentSurf Extension (Chrome / Edge)"]
  end

  subgraph Cloud["Cloud Mode (OAuth 2.0 + Reverse WSS)"]
    CAgent["Gemini Web (OAuth 2.0) / Notion AI / Dify"] -->|HTTPS Streamable MCP| Proxy["Caddy / Nginx HTTPS"]
    Proxy --> GW["standalone-gateway.js (:8767)"]
    HomeExt["Home Chrome Extension"] -->|Outbound WSS| GW
    WorkExt["Office Chrome Extension"] -->|Outbound WSS| GW
  end

Quick Start

Prerequisites

RequirementVersion & Check
Node.js20+ (node -v)
Gitgit --version
Chrome or Edge116+ (chrome://version / edge://version)

No administrator privileges required. Your existing browser profiles, passwords, and settings are never modified.


Path A: Local Deployment (Claude Desktop, Cursor, Codex, etc.)

  1. Clone and run the setup wizard:

    git clone https://github.com/ztao0916/agentsurf-browser-control-runtime.git
    cd agentsurf-browser-control-runtime
    npm run setup
    

    To configure both Chrome and Edge simultaneously (with separate ports and configs):

    npm run setup -- --browser all
    
  2. Load the extension in Chrome / Edge:

    • Open chrome://extensions (or edge://extensions) and enable Developer mode.
    • Click Load unpacked and select the project's dist/ folder.
    • Copy the generated Extension ID from the AgentSurf card and paste it into the terminal prompt.

    Getting the AgentSurf extension ID from its Chrome extension card

  3. Reload & verify the extension popup:

    • Click Reload on the AgentSurf extension card, then click the AgentSurf toolbar icon and verify Local Native is active.

    AgentSurf extension panel status

  4. Add the printed MCP config to your agent:

    {
      "mcpServers": {
        "agentsurf": {
          "command": "<absolute launcher path printed by setup>"
        }
      }
    }
    

    When installed with --browser all, setup prints separate agentsurf-chrome and agentsurf-edge entries so you can target either browser cleanly.


Path B: Remote Cloud Gateway (Gemini Web, Notion AI, Dify, Remote Agents)

Use Remote Gateway mode when your AI runs in the cloud and needs to control your local browser over HTTPS/WSS.

  1. Build the single-file gateway locally (npm run build produces dist/mcp/standalone-gateway.js with zero node_modules needed on the server).
  2. Upload dist/mcp/standalone-gateway.js to your server behind Caddy/Nginx HTTPS, initialize credentials (init-remote --url https://mcp.example.com), and start it with PM2 (start-remote).
  3. Pair your Chrome/Edge extension in the popup under Remote Gateway using your wss://.../ws URL, Pairing Token, and an optional Device Name (e.g., Home / Office).
  4. Connect your cloud client:
    • Gemini Web: Use the generated OAuth Client ID and OAuth Client Secret, register Gemini's Redirect URI with add-oauth-redirect --uri "...", and approve the browser prompt with your Pairing Token.
    • Notion AI / Dify / Custom HTTP MCP: Use https://mcp.example.com/mcp with Authorization: Bearer <token>.

Gemini Web controlling a local Chrome browser over AgentSurf Cloud Gateway (OAuth 2.0 + Reverse WSS)

Note on Gemini Web confirmations: The demo GIF above trims out waiting spinners and permission cards for brevity. AgentSurf marks read-only inspection tools with MCP readOnlyHint: true (which Gemini groups under Read and allows automatically), while Gemini Web's client-side security policy still prompts you to click Always allow on interactive / state-changing tools (browser_start_session, browser_open, browser_type, browser_click, browser_scroll, browser_end_session, etc.)—even if Write / delete is already set to Always allow in App actions.

👉 Full step-by-step instructions: Remote Gateway & OAuth 2.0 Guide (docs/remote-gateway.en.md)


Multi-Browser & Multi-Computer Routing

Multiple browsers on one PC (Chrome + Edge)

Each MCP server entry (agentsurf / agentsurf-chrome vs agentsurf-edge) runs its own isolated bridge, tab leases, and sessions. Do not pass a Chrome tab_id or element_id to the Edge server.

Multiple PCs on one Cloud Gateway (Home + Office)

  1. Connect both browsers to the same wss://mcp.example.com/ws URL with the same Pairing Token and distinct Device Names (e.g., Home, Office).
  2. Automatic active routing: The gateway defaults to whichever computer's Chrome window was most recently focused or used by you—idle/background browsers reconnecting will not steal control.
  3. Session stickiness: Once browser_start_session starts on a computer, every step of that task stays pinned to that same computer until completion.
  4. Manual control when needed: Click Pin as active in the extension popup to lock a browser, pass device: "Office" to browser_start_session, or connect via https://mcp.example.com/mcp?device=Home.

Use and verify

Ask your connected agent:

Open https://example.com and tell me the page title.

Seeing "Chrome is being debugged" during screenshots or file uploads is normal Chrome CDP behavior.

Safety Recommendations

  • Start in read-only mode when deploying the remote gateway (init-remote defaults to read-only; explicitly switch to interactive only when ready).
  • Keep human confirmation before consequential actions such as submitting forms, making purchases, deleting records, uploading files, or sending messages.
  • Never share secrets (passwords, OTPs, cookies, or pairing tokens) inside prompts, and never commit local config.json or remote-config.json files.

Documentation & Links

Licensed under the Apache License 2.0.