Claude Code

The Claude Code integration connects a Claude Agent SDK query loop 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.

Stagehand ships this experimental integration from the repository rather than publishing it as a standalone adapter.

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

Quickstart

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

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.

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"

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.

First steps

The basics

Configuration

Integrations

Best practices

Migration guide

SDK reference

Prerequisites

Quickstart

Configuration

Keep the browser session alive

Connect a running Claude Code CLI

Claude Code integration source

​Prerequisites

​Quickstart

​Configuration

​Keep the browser session alive

​Connect a running Claude Code CLI

Claude Code integration source

Prerequisites

Quickstart

Configuration

Keep the browser session alive

Connect a running Claude Code CLI