Skip to main content
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:
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

2

Configure the Claude Code agent

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:
4

Run a browser task

​
Configuration

​
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:
Claude Code inherits your shell environment, so the exports above are the only configuration. For a headless one-shot run:
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.