Skip to main content
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.
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
  • A Cursor user or service-account API key
  • A current Google Chrome installation for local browser mode

​
Quickstart

1

Clone and build Stagehand

2

Authenticate Cursor

Create a user API key in the Cursor dashboard or a service-account key in your team settings, then export it:
The example uses composer-2.5 by default. Set CURSOR_STAGEHAND_MODEL to another model ID available to your Cursor account when needed.
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

​
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:
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:
run executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the integration security boundary.

Cursor integration source

Read the isolated Cursor agent setup, MCP mount, lifecycle handling, and unit tests.