AgentSurf
Enables Notion AI to control the real local browser through the remote Streamable HTTP gateway using a static Bearer token (OAuth 2.0 + Reverse WSS), so cloud-side Notion agents can navigate, snapshot interactive elements, and act on signed-in pages.
AgentSurf
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.

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://.../wsendpoint 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 bytag/role/name_containsshrinks 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-onlyby default on remote, hashed tokens, SHA-256 operation idempotency journal, and zeroMAIN-worldconsolepatching).
Capability | AgentSurf | Local Shell Browser Skills (e.g. Tencent BrowserSkill) | Headless MCP (Playwright / Puppeteer) |
Reuses signed-in Chrome / Edge | Yes (live tabs & cookies) | Yes (live browser via extension) | No (starts fresh or needs brittle profile copies) |
Anti-bot friendliness | Real desktop browser session | Real desktop browser session | Often flagged by headless automation signals |
Agent protocol | Standard MCP ( | Local CLI ( | Local |
Cloud Web Agents (Gemini Web, Notion AI, Dify) | Built-in OAuth 2.0 (PKCE) + Bearer + Reverse WSS | Local shell agents only | Local only unless custom-wrapped |
Home + Office multi-PC routing | Yes — active-window auto-routing, session stickiness & pinning | Single local machine daemon | Single local process |
Context & token footprint | In-page filtering ( | Page extraction via CLI commands | Large raw DOM / AX tree dumps |
Safety & isolation | Remote | Dedicated agent window / tab borrowing + human confirmation | Shared browser state; full read/write by default |
Related MCP server: agent-chrome
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-containedstandalone-gateway.json 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,S256PKCE, 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
HostandX-Forwarded-Proto, so one gateway config works across standard port443or any alternate reverse-proxy port.
Multi-Computer Coexistence (Home + Office):
Connect multiple computers (e.g.,
HomeandOffice) to the samewss://.../wsendpoint 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
devicetargeting.
29 Browser Control Tools (Token-Efficient by Design):
Semantic interactive element snapshots (
browser_get_interactiveswith opaqueelement_ids, in-page filtering bytag/role/name_contains/visible_only, and default150cap—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
endQuick Start
Prerequisites
Requirement | Version & Check |
Node.js |
|
Git |
|
Chrome or Edge |
|
No administrator privileges required. Your existing browser profiles, passwords, and settings are never modified.
Path A: Local Deployment (Claude Desktop, Cursor, Codex, etc.)
Clone and run the setup wizard:
git clone https://github.com/ztao0916/agentsurf-browser-control-runtime.git cd agentsurf-browser-control-runtime npm run setupTo configure both Chrome and Edge simultaneously (with separate ports and configs):
npm run setup -- --browser allLoad the extension in Chrome / Edge:
Open
chrome://extensions(oredge://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.

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

Add the printed MCP config to your agent:
{ "mcpServers": { "agentsurf": { "command": "<absolute launcher path printed by setup>" } } }When installed with
--browser all,setupprints separateagentsurf-chromeandagentsurf-edgeentries 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.
Build the single-file gateway locally (
npm run buildproducesdist/mcp/standalone-gateway.jswith zeronode_modulesneeded on the server).Upload
dist/mcp/standalone-gateway.jsto your server behind Caddy/Nginx HTTPS, initialize credentials (init-remote --url https://mcp.example.com), and start it with PM2 (start-remote).Pair your Chrome/Edge extension in the popup under Remote Gateway using your
wss://.../wsURL, Pairing Token, and an optional Device Name (e.g.,Home/Office).Connect your cloud client:
Gemini Web: Use the generated
OAuth Client IDandOAuth Client Secret, register Gemini's Redirect URI withadd-oauth-redirect --uri "...", and approve the browser prompt with your Pairing Token.Notion AI / Dify / Custom HTTP MCP: Use
https://mcp.example.com/mcpwithAuthorization: Bearer <token>.

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 clickAlways allowon 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 toAlways allowin 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)
Connect both browsers to the same
wss://mcp.example.com/wsURL with the same Pairing Token and distinct Device Names (e.g.,Home,Office).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.
Session stickiness: Once
browser_start_sessionstarts on a computer, every step of that task stays pinned to that same computer until completion.Manual control when needed: Click Pin as active in the extension popup to lock a browser, pass
device: "Office"tobrowser_start_session, or connect viahttps://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-onlymode when deploying the remote gateway (init-remotedefaults toread-only; explicitly switch tointeractiveonly 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.jsonorremote-config.jsonfiles.
Documentation & Links
Licensed under the Apache License 2.0.
Available Tools
29 toolsbrowser_backbrowser_backB
Go back one entry in the tab history.
Inputs: tab_id (required), session_id, session_name.
browser_claim_tabbrowser_claim_tabAIdempotent
Take over a tab this session does not own yet, for example a page the user already had open. The tab joins the session group unless you pass group: false, and other sessions are refused it from then on.
Inputs: tab_id (required), group, session_id, session_name.
browser_clickbrowser_clickB
Click an element returned by browser_get_interactives.
Inputs: tab_id (required), element_id (required), frame_id, modifiers, +2 more.
browser_close_tabbrowser_close_tabCDestructive
Close a Chrome tab.
Inputs: tab_id (required), session_id, session_name.
browser_double_clickbrowser_double_clickB
Double-click an element returned by browser_get_interactives.
Inputs: tab_id (required), element_id (required), frame_id, modifiers, +2 more.
browser_dragbrowser_dragB
Drag one element from browser_get_interactives onto another.
Inputs: tab_id (required), source_element_id (required), target_element_id (required), frame_id, +2 more.
browser_forwardbrowser_forwardB
Go forward one entry in the tab history.
Inputs: tab_id (required), session_id, session_name.
browser_get_framesbrowser_get_framesARead-onlyIdempotent
List the frames inside a tab: iframes and blank-src app frames included. Frame 0 is the top document. Pass a returned frame_id to page reads and element actions to work inside that frame.
Inputs: tab_id (required), session_id, session_name.
browser_get_interactivesbrowser_get_interactivesARead-onlyIdempotent
List interactive page elements and their opaque element_ids. Call this before any element action. Pass frame_id to inspect an iframe; the top document is frame 0, and an element_id only works in the frame that returned it. A heavy page can hold hundreds of elements, so the list is capped at 150 and reports total plus truncated; narrow it with limit, visible_only, tag, role or name_contains instead of asking for everything.
Inputs: tag, role, limit, tab_id, +5 more.
browser_get_pagebrowser_get_pageCRead-onlyIdempotent
Read page metadata and viewport state.
Inputs: tab_id, frame_id, session_id, session_name.
browser_get_page_contentbrowser_get_page_contentARead-onlyIdempotent
Extract readable page text, and optionally HTML, image, and iframe metadata. Covers the top document unless frame_id targets a frame; app shells keep their real content inside an iframe, so check browser_get_frames when the text looks like navigation only.
Inputs: tab_id (required), frame_id, session_id, include_html, +4 more.
browser_handle_dialogbrowser_handle_dialogA
Accept or dismiss a JavaScript alert, confirm, or prompt. Supply prompt_text when accepting a prompt.
Inputs: action (required), tab_id (required), session_id, prompt_text, +1 more.
browser_list_downloadsbrowser_list_downloadsARead-onlyIdempotent
List recent Chrome downloads. Chrome does not record which tab started a download, so tab_id is null unless a previous browser_wait_for_download associated it.
Inputs: tab_id, session_id, session_name.
browser_list_tabsbrowser_list_tabsARead-onlyIdempotent
List Chrome tabs without changing the active tab. Start here to find a tab_id. Only this conversation tabs and unclaimed tabs are returned, with other_session_tabs counting what was hidden; pass include_all to see every tab.
Inputs: window_id, session_id, include_all, session_name.
browser_observebrowser_observeBRead-onlyIdempotent
Capture page state, interactive elements, accessibility data, and a screenshot in one call.
Inputs: tab_id (required), clip, include, full_page, +3 more.
browser_openbrowser_openB
Open a URL in Chrome, or navigate an existing tab when tab_id is given.
Inputs: url (required), tab_id, activate, session_id, +1 more.
browser_pressbrowser_pressC
Press a key on an element returned by browser_get_interactives. Supports optional modifier keys.
Inputs: key (required), tab_id (required), element_id (required), frame_id, +3 more.
browser_reloadbrowser_reloadB
Reload the tab, re-running its scripts.
Inputs: tab_id (required), session_id, session_name.
browser_reset_sessionsbrowser_reset_sessionsADestructiveIdempotent
Finish a browser task: release this conversation's session and ungroup its tabs so the group does not linger in the user's tab bar. It also closes the tabs this conversation opened itself, but never a tab the user already had open, so pass close_opened_tabs: false to keep them. force: true instead releases every session, including other conversations', and only ungroups.
Inputs: force, session_id, session_name, close_opened_tabs.
browser_screenshotbrowser_screenshotARead-onlyIdempotent
Capture a screenshot of a Chrome tab as an image. Works on a background tab. Prefer this over describing a page in text when layout or visual state matters.
Inputs: tab_id (required), clip, full_page, session_id, +2 more.
browser_scrollbrowser_scrollB
Scroll the document by a pixel delta, reporting whether it reached the top or bottom.
Inputs: tab_id (required), delta_x (required), delta_y (required), session_id, +1 more.
browser_select_optionbrowser_select_optionCIdempotent
Choose options in a select element by value.
Inputs: tab_id (required), values (required), element_id (required), frame_id, +2 more.
browser_select_textbrowser_select_textCIdempotent
Select text or place the cursor before or after text in an editable element.
Inputs: tab_id (required), element_id (required), text, frame_id, +3 more.
browser_set_checkedbrowser_set_checkedCIdempotent
Set a checkbox or radio button to a specific checked state.
Inputs: tab_id (required), checked (required), element_id (required), frame_id, +2 more.
browser_set_filesbrowser_set_filesB
Set files on a file input element using absolute local paths.
Inputs: files (required), tab_id (required), element_id (required), frame_id, +2 more.
browser_switch_tabbrowser_switch_tabAIdempotent
Bring a tab to the front of its window. Screenshots work without this, but the user will see the tab change.
Inputs: tab_id (required), session_id, session_name.
browser_typebrowser_typeC
Type into an editable element returned by browser_get_interactives.
Inputs: text (required), tab_id (required), element_id (required), frame_id, +2 more.
browser_wait_for_downloadbrowser_wait_for_downloadBRead-only
Wait for a download to complete or fail, optionally only one started from a given tab.
Inputs: tab_id, session_id, timeout_ms, session_name.
browser_wait_for_elementbrowser_wait_for_elementARead-onlyIdempotent
Wait for an element from browser_get_interactives to become attached, detached, visible, or hidden. Get a fresh element_id if the page revision changed while waiting.
Inputs: state (required), tab_id (required), element_id (required), frame_id, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Most tools target clearly distinct browser actions or resources, such as click vs. type vs. drag vs. select_option. The main overlap is browser_observe, which combines page state, interactives, accessibility, and screenshot, potentially competing with browser_get_page, browser_get_interactives, and browser_screenshot, but descriptions clarify when to use each.
All tools use a consistent browser_ prefix and snake_case, making the set predictable. Most names are verb_noun or verb-only, which is readable, though the mix of patterns is a minor deviation from a strict verb_noun convention.
At 29 tools, the surface is heavy for a single server, even for browser automation. Several inspection tools could be consolidated, and the count exceeds the 25-tool threshold where each tool must strongly justify its place.
The set covers navigation, tabs, frames, element interaction, dialogs, downloads, file inputs, screenshots, and waiting, which is a broad browser-automation lifecycle. Minor gaps remain, such as JavaScript evaluation, hover, and cookie/storage management, but agents can work around most of these.
Maintenance
Related MCP Connectors
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables remote AI agents to control a local, authenticated desktop browser over MCP through an outbound WebSocket bridge and Chrome extension, supporting tab management, navigation, page reading, clicking, typing, scrolling, screenshots, and JavaScript evaluation.1MIT
- AlicenseNot gradedqualityCmaintenanceLets local AI agents drive the Chrome browser a user already has open, including signed-in sessions, by listing tabs, reading page text and actionable elements, then clicking, filling, selecting, scrolling, navigating, and capturing viewport screenshots without exporting cookies. Runs as a dependency-free local stdio process over Native Messaging, with per-tab leases, automatic reconnection, and pause/write-action controls.MIT
- AlicenseNot gradedqualityAmaintenanceLets AI coding tools drive the real, already-logged-in Chrome browser over local stdio—snapshotting and reading pages, clicking, typing, managing tabs, capturing screenshots, and inspecting network, console, storage, and cookies—without opening a remote-debugging port. It installs as a Chrome extension plus native-messaging bridge, so agents work in the user's authenticated sessions while passing bot detection.1 npmISC
- AlicenseNot gradedqualityAmaintenanceLets AI agents control the real, already-logged-in Chrome browser: reading pages, clicking, typing, navigating tabs, taking screenshots, and inspecting cookies, network traffic, console output, and storage. It connects as a local extension over Native Messaging, so no remote-debugging port or headless profile is needed.1 npmISC