Skip to main content
Give your coding agent a browser it can use alongside its coding tools. Stagehand’s MCP adapter lets the agent navigate a running application, interact with its UI, and read page content without adding a browser tool loop to your project. CLI agents that support stdio MCP can connect to the Stagehand MCP adapter. One server process owns the browser session, so navigation, authentication, and page state remain available across tool calls.

​
Choose a CLI agent

Agents with a native extension integration can register the browser tools directly. Follow the individual agent guide for that setup; the steps below cover the MCP adapter.
These integrations are experimental and run from the Stagehand repository. The shared adapter is not published as a standalone package.

​
Set up the MCP adapter

You need Node.js 24 or newer, pnpm 11.10.0, and an installed, authenticated CLI agent. Local browser mode also requires Google Chrome.
1

Clone and build Stagehand

2

Register the server with your agent

Configure a stdio MCP server with these values, replacing the path with your checkout:Use the linked agent guide for the exact configuration format and permissions. Let the CLI agent start the server and keep the connection open for the session.
3

Choose a browser

Set STAGEHAND_BROWSER=local in the MCP server’s environment to use local Chrome. To use Browserbase, set STAGEHAND_BROWSER=browserbase and BROWSERBASE_API_KEY; BROWSERBASE_PROJECT_ID is optional.When STAGEHAND_BROWSER is unset, the adapter selects Browserbase if BROWSERBASE_API_KEY is present, otherwise local Chrome. Follow the agent guide to pass environment variables to its MCP child process.
4

Try a browser task

Start or reload your agent’s MCP connection, then ask:
The agent should use run to navigate and report Example Domain. Your CLI agent manages its own model and authentication.

​
Configure models

Your CLI agent selects its own model and manages its authentication. The MCP adapter provides browser tools to that agent; it does not choose or replace the agent’s model. Deterministic browser operations do not require a separate Stagehand model. If you use Stagehand AI methods through an integration that supports them, configure the Stagehand model separately and pass its required credentials to the browser runtime. See your agent’s guide for supported settings and environment forwarding.

​
Browser tools

For example, the agent can navigate with this run input:
Keep one MCP connection open throughout the task. Starting a new server for each call creates a new browser and loses the previous session’s page state. Snapshot element IDs belong to the latest snapshot; take another snapshot after navigation or when an ID becomes stale.

​
Security boundary

run executes agent-authored JavaScript in the Stagehand browser extension’s service worker. It can control the browser and access data available in that session. Use Browserbase for untrusted browser tasks, and configure tool permissions in your CLI agent. Treat authenticated browser sessions as privileged. The adapter does not change the permissions of the agent’s other tools.

MCP adapter source

Read the shared browser tools and stdio server implementation.