MCP server

The brawsr MCP server lets coding agents create browser sessions, checkpoints, rewinds, and forks through high-level tools. Version 0.1.0 runs as a local stdio process and requires Node.js 22 or newer.

The package is available on npm (opens in a new tab) and in the official MCP Registry (opens in a new tab). It includes the TypeScript SDK, so you do not need another package.

Codex

Add brawsr to Codex from the command line:

codex mcp add brawsr \
  --env BRAWSR_API_KEY=brawsr_... \
  -- npx -y @brawsr/[email protected]

Codex writes MCP settings to ~/.codex/config.toml. You can also configure the server directly:

[mcp_servers.brawsr]
command = "npx"
args = ["-y", "@brawsr/[email protected]"]

[mcp_servers.brawsr.env]
BRAWSR_API_KEY = "brawsr_..."

Use codex mcp list to confirm that the server is configured.

Claude Code

Add the server at user scope so it is available in every project:

claude mcp add \
  --env BRAWSR_API_KEY=brawsr_... \
  --transport stdio \
  --scope user \
  brawsr -- npx -y @brawsr/[email protected]

Run claude mcp list to check the connection, or /mcp from an interactive Claude Code session.

Cursor

Create ~/.cursor/mcp.json for a personal configuration, or .cursor/mcp.json for one project:

{
  "mcpServers": {
    "brawsr": {
      "command": "npx",
      "args": ["-y", "@brawsr/[email protected]"],
      "env": {
        "BRAWSR_API_KEY": "brawsr_..."
      }
    }
  }
}

If the project file contains a real API key, keep it out of source control. Restart or reload Cursor after changing the configuration, then check the brawsr server under Settings → Tools & MCP.

VS Code

Create .vscode/mcp.json. This example uses a password input so the key is not stored in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "brawsr-api-key",
      "description": "brawsr API key",
      "password": true
    }
  ],
  "servers": {
    "brawsr": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@brawsr/[email protected]"],
      "env": {
        "BRAWSR_API_KEY": "${input:brawsr-api-key}"
      }
    }
  }
}

Run MCP: List Servers from the Command Palette and start brawsr. VS Code asks you to trust a local MCP server the first time it starts.

Configuration

BRAWSR_API_KEY is the only required setting. The server connects to https://api.brawsr.io by default. Once the key is configured, it connects to brawsr automatically and never reads connection settings from tool arguments.

BRAWSR_API_KEY=...
BRAWSR_MCP_TIMEOUT_MS=30000  # optional

Two optional environment variables are available:

• BRAWSR_MCP_TIMEOUT_MS changes the default 30-second operation wait and accepts an integer from 1 through 300000;
• BRAWSR_BASE_URL connects the MCP process to another brawsr deployment.

Pin the package version in client configuration so restarting your MCP client does not select a newer release without review.

Tools and recovery behavior

The server exposes:

• session create, list, get, label update, and close tools;
• checkpoint create, get, list, delete, and rewindable-checkpoint tools;
• activity and lineage reads;
• rewind and ordered fork tools;
• operation get and wait tools; and
• bounded multi-session cleanup.

Checkpoint, rewind, and fork are each one tool call. Checkpoint and fork return completed results. Rewind can return a CDP-usable result before bounded post-restore work is terminal; wait for its operation before another lifecycle mutation on that session. If the configured wait expires, the structured error includes operation recovery fields and the operation may still continue. Use brawsr_get_operation or brawsr_wait_operation rather than submitting a new mutation.

Fork returns ordered peer children. An agent decides which results to keep and calls brawsr_close_sessions for the rest. The server does not select a winner, merge browser state, replay CDP commands, or proxy CDP traffic.

The API key and CDP authorization header are never tool output. Treat returned CDP URLs as sensitive and do not log them. The 0.1.x package supports local stdio transport; there is no hosted MCP endpoint.