Agentsurf Browser Control Runtime

What agentsurf-browser-control-runtime does

agentsurf-browser-control-runtime lets an MCP-compatible agent operate Chrome or Edge on the local computer. It works with the browser session already in use, including its open tabs and login state, so workflows can act on sites where the user is already authenticated. Supported browser interactions include opening and reading pages, listing tabs, clicking controls, entering text, scrolling, capturing screenshots, uploading files, and working with iframes.

Chrome and Edge can be installed together. The agentsurf server targets Chrome for compatibility with existing configurations, while agentsurf-chrome explicitly selects Chrome and agentsurf-edge selects Edge. Each browser keeps separate tabs, page revisions, sessions, and identifiers.

How it works

The runtime combines an MCP server with an AgentSurf browser extension and a native host. The extension connects the selected browser to the local runtime, and the MCP client starts the appropriate launcher over stdio. Agents then call browser tools through the configured MCP server rather than controlling a separate browser instance.

For local use, the default arrangement keeps the runtime on the same computer as the agent and does not require network access. A remote gateway mode provides a Streamed HTTP MCP interface for cloud agents and other remote MCP clients. In that arrangement, the local extension connects to the gateway so a remote agent can dispatch actions to the local Chrome or Edge instance.

When multiple browsers are configured, choose the target through the MCP server name. Do not pass a Chrome tab or element identifier to the Edge server, or switch one workflow between the two server instances while reusing the same identifiers.

Setup and configuration

Local installation requires Node.js 20 or newer, Git, and Chrome or Edge 116 or newer. Clone the repository, enter its directory, and run the setup wizard:

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

The default setup installs Chrome support, installs dependencies, builds the project, registers the native host, and prints the MCP configuration. To configure both supported browsers, run npm run setup -- --browser all.

The wizard instructs you to enable developer mode in the browser extensions page, load the repository’s dist/ directory as an unpacked extension, copy the displayed extension ID, and enter it in the terminal. Add the generated command path to an MCP client using the stdio transport, then restart that client. The generated server names are agentsurf, agentsurf-chrome, and agentsurf-edge according to the selected configuration.

Remote deployments use the separate gateway setup and expose Streamed HTTP MCP for cloud or hosted agents. The extension panel controls whether local direct connection or cloud gateway connection is active.

Tools and capabilities

• Open URLs and inspect page titles or content.
• List browser tabs and operate on the selected tab.
• Click page elements, enter text, and scroll.
• Capture screenshots and interact with iframes.
• Upload files through browser controls.
• Reset sessions for the browser selected by the MCP server.
• Keep Chrome and Edge workflows isolated with separate server names and session identifiers.

Limitations and notes

The browser extension must be loaded and connected before the agent can act. Local setup requires access to the supported desktop browser and a compatible MCP client. Browser automation can perform consequential actions such as saving, publishing, deleting, uploading, or sending messages, so review those actions before execution.

Use read-only operations first when validating the setup. Do not provide an agent with passwords, verification codes, cookies, or tokens. A browser debugging notice shown during screenshots or browser control is expected behavior. Existing agentsurf configurations continue to target Chrome; use the explicit server names when selecting Chrome or Edge in a multi-browser setup.