Claude Code

Give a Claude Code agent persistent Stagehand browser tools over MCP/stdio.

The Claude Code plugin installs through Claude Code’s official marketplace system and connects to the Stagehand facade MCP server over MCP/stdio. One server process owns the browser, so page state survives across run, snapshot, and screenshot calls.

The marketplace plugin requires the first @browserbasehq/stagehand-mcp@0.1.0 npm release. Until it is published, use the source workflow below.

Install the plugin

In Claude Code, run:

/plugin marketplace add browserbase/stagehand
/plugin install stagehand@browserbase-stagehand

Restart Claude Code, then use /mcp to check the Stagehand server. The plugin registers run, snapshot, and screenshot and keeps one browser alive across calls. You can use your existing Claude Code login; the plugin does not require a separate Anthropic API key.

You need Node.js 24+ and either local Chrome or a Browserbase credential. Export BROWSERBASE_API_KEY before starting Claude Code to use Browserbase. See below for optional STAGEHAND_* settings.

This uses Claude Code’s plugin marketplace. The Agent SDK example below is for embedding Claude in an application.

Source example prerequisites

• Node.js 24 or newer
• pnpm 11.10.0
• An Anthropic API key for the example agent
• A current Google Chrome installation for local browser mode

Run the Agent SDK example from source

1. Clone and build Stagehand

   git clone https://github.com/browserbase/stagehand.git
   cd stagehand
   pnpm install --frozen-lockfile
   pnpm exec turbo run build \
     --filter @browserbasehq/stagehand-integrations
   
2. Configure the Claude Code agent

   export ANTHROPIC_API_KEY="your-anthropic-api-key"
   

   Set CLAUDE_STAGEHAND_MODEL to select another model; the example defaults to claude-sonnet-5.

3. Choose the browser

   The example defaults to Browserbase when BROWSERBASE_API_KEY is set, otherwise it uses local Chrome:

   export STAGEHAND_BROWSER="browserbase"
   export BROWSERBASE_API_KEY="your-browserbase-api-key"
   
4. Run a browser task

   pnpm --dir packages/integrations/claude-code start -- \
     "Open https://example.com and report the page title."
   

Configuration

Variable	Purpose
CLAUDE_STAGEHAND_MODEL	Claude Code agent model; defaults to claude-sonnet-5.
ANTHROPIC_API_KEY	Credential for the example agent. The Claude Agent SDK does not forward it to the MCP child.
STAGEHAND_BROWSER	Select local or browserbase. Defaults to browserbase when BROWSERBASE_API_KEY is set, otherwise local.
BROWSERBASE_API_KEY	Required for Browserbase.
BROWSERBASE_PROJECT_ID	Optional Browserbase project ID.
STAGEHAND_MODEL_NAME	Optional model for Stagehand AI methods called inside run.
STAGEHAND_MODEL_API_KEY	Required with STAGEHAND_MODEL_NAME; the MCP child does not receive agent-provider credentials.

Keep the browser session alive

The example mounts one facade MCP server for the entire query loop and limits allowedTools to the three mcp__stagehand__ tools. A canUseTool guard denies everything else, because headless runs hang on any unanswered permission prompt. Preserve that lifetime if you adapt the integration; a new process per tool call starts a new browser.

The MCP child receives only Stagehand and Browserbase configuration plus the process values required to launch Node. The host’s model credential remains in the Claude Code process.

Connect a running Claude Code CLI

The package ships a project-scoped .mcp.json that mounts the same facade server in the Claude Code CLI. Its args path is relative to the package, so start the CLI from that directory:

cd packages/integrations/claude-code
claude

Claude Code inherits your shell environment, so the exports above are the only configuration. For a headless one-shot run:

claude -p "your instruction" --mcp-config .mcp.json --allowedTools "mcp__stagehand__run,mcp__stagehand__snapshot,mcp__stagehand__screenshot"

run executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the integration security boundary.

Claude Code integration source

Read the MCP mount, permission guard, and contract tests.