> ## Documentation Index
> Fetch the complete documentation index at: https://stagehand-integrations-claude-plugin.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## Install the plugin

In Claude Code, run:

```text theme={null}
/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](https://code.claude.com/docs/en/discover-plugins). 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

<Steps>
  <Step title="Clone and build Stagehand">
    ```bash theme={null}
    git clone https://github.com/browserbase/stagehand.git
    cd stagehand
    pnpm install --frozen-lockfile
    pnpm exec turbo run build \
      --filter @browserbasehq/stagehand-integrations
    ```
  </Step>

  <Step title="Configure the Claude Code agent">
    ```bash theme={null}
    export ANTHROPIC_API_KEY="your-anthropic-api-key"
    ```

    Set `CLAUDE_STAGEHAND_MODEL` to select another model; the example defaults to `claude-sonnet-5`.
  </Step>

  <Step title="Choose the browser">
    The example defaults to Browserbase when `BROWSERBASE_API_KEY` is set, otherwise it uses local Chrome:

    ```bash theme={null}
    export STAGEHAND_BROWSER="browserbase"
    export BROWSERBASE_API_KEY="your-browserbase-api-key"
    ```
  </Step>

  <Step title="Run a browser task">
    ```bash theme={null}
    pnpm --dir packages/integrations/claude-code start -- \
      "Open https://example.com and report the page title."
    ```
  </Step>
</Steps>

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

```bash theme={null}
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:

```bash theme={null}
claude -p "your instruction" --mcp-config .mcp.json --allowedTools "mcp__stagehand__run,mcp__stagehand__snapshot,mcp__stagehand__screenshot"
```

<Warning>
  `run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary).
</Warning>

<Card title="Claude Code integration source" icon="github" href="https://github.com/browserbase/stagehand/tree/main/packages/integrations/claude-code">
  Read the MCP mount, permission guard, and contract tests.
</Card>