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

# Cursor

> Give a local Cursor SDK agent persistent Stagehand browser tools over MCP/stdio.

The Cursor integration uses the same shared Cursor SDK session library as the eval harness, built on `@cursor/sdk`, and mounts the Stagehand facade as one MCP/stdio server. One Cursor agent and one facade process own the browser across `run`, `snapshot`, and `screenshot` calls, preserving page state and snapshot IDs.

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

## Prerequisites

* Node.js 24 or newer
* pnpm 11.10.0
* A Cursor user or service-account API key
* A current Google Chrome installation for local browser mode

## Quickstart

<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-cursor-sdk
    ```
  </Step>

  <Step title="Authenticate Cursor">
    Create a user API key in the Cursor dashboard or a service-account key in your team settings, then export it:

    ```bash theme={null}
    export CURSOR_API_KEY="your-cursor-api-key"
    ```

    The example uses `composer-2.5` by default. Set `CURSOR_STAGEHAND_MODEL` to another model ID available to your Cursor account when needed.
  </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/cursor start -- \
      "Open https://example.com, snapshot it, and report the heading."
    ```
  </Step>
</Steps>

## Configuration

| Variable                  | Purpose                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `CURSOR_API_KEY`          | Cursor user or service-account key. The example does not forward it to the MCP child.                        |
| `CURSOR_STAGEHAND_MODEL`  | Optional Cursor model ID; defaults to `composer-2.5`.                                                        |
| `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`.                                                                        |

## SDK and session lifecycle

This V1 integration uses Cursor's local runtime. The agent loop and temporary workspace run locally, while Cursor hosts model inference. Cursor Cloud requires a remotely reachable MCP server and is not part of this example.

The example creates an isolated temporary workspace, disables ambient Cursor setting sources, and enables only Cursor's `mcp` capability group. Its only inline server is the Stagehand facade, so the model receives `run`, `snapshot`, and `screenshot` without shell, file-editing, user MCP, or project MCP tools. The example prefixes the canonical Stagehand tool instructions to the task because the main Cursor agent API does not expose a separate system-prompt option.

The shared session library owns SDK event consumption, cancellation, and agent disposal. The facade process remains attached to one Cursor agent for the full run. On completion or failure, the example disposes the agent and deletes its temporary workspace. `SIGINT` and `SIGTERM` first cancel the active run so in-flight MCP calls stop cleanly.

Only non-empty `STAGEHAND_*` and `BROWSERBASE_*` variables cross into the MCP child. The Cursor API key and unrelated host secrets remain in the agent process.

## Connect a running Cursor CLI

The package ships a project-scoped `.cursor/mcp.json` that mounts the Stagehand facade MCP server in the Cursor CLI. Its `args` path is relative to the package, so start the CLI from that directory:

```bash theme={null}
cd packages/integrations/cursor
agent mcp list
agent mcp list-tools stagehand
agent
```

Cursor inherits your shell environment, so the exports above are the only configuration. For a headless one-shot run, approve the configured MCP server so tool calls do not wait for an interactive prompt:

```bash theme={null}
agent -p --approve-mcps "your instruction"
```

<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="Cursor integration source" icon="github" href="https://github.com/browserbase/stagehand/tree/main/packages/integrations/cursor">
  Read the isolated Cursor agent setup, MCP mount, lifecycle handling, and unit tests.
</Card>