MCP server

BrowserGen ships a hosted MCP server that turns any MCP client into a browser operator: 16 tools for creating sessions, navigating, clicking, typing, and reading pages. One URL, one API key, no glue code.

Quickstart

With Claude Code, connecting is one command:

claude mcp add --transport http browsergen https://api.browsergen.com/mcp \
  --header "Authorization: Bearer brl-k-v7-YOUR-KEY"

Then ask your agent to browse: "open news.ycombinator.com and tell me the top story". The first page tool call creates a browser session automatically; there is no setup step inside the conversation.

Endpoint and authentication

The server lives at https://api.browsergen.com/mcp (Streamable HTTP, stateless). Authenticate with an API key, in one of three ways:

• Authorization: Bearer brl-k-v7-... header (preferred).
• x-api-key header with the same key value.
• ?key=brl-k-v7-... query parameter for clients that cannot send custom headers (ChatGPT, claude.ai connectors). Keys in URLs can end up in logs, so prefer a header where possible.

The MCP server sits behind the same gate as the REST API: it needs an active BrowserGen plan, and sessions it creates count against your plan's concurrency.

For clients that only speak stdio, the browsergen-mcp npm package is a thin local bridge to the hosted endpoint (run npx -y browsergen-mcp with BROWSERGEN_API_KEY in the environment). The tools live server-side either way, so both transports behave identically.

Client setup

Claude Code

claude mcp add --transport http browsergen https://api.browsergen.com/mcp \
  --header "Authorization: Bearer brl-k-v7-YOUR-KEY"

Or, if you prefer a local stdio process:

claude mcp add browsergen --env BROWSERGEN_API_KEY=brl-k-v7-YOUR-KEY \
  -- npx -y browsergen-mcp

Codex CLI

export BROWSERGEN_API_KEY=brl-k-v7-YOUR-KEY
codex mcp add browsergen --url https://api.browsergen.com/mcp \
  --bearer-token-env-var BROWSERGEN_API_KEY

# Or over stdio:
codex mcp add browsergen --env BROWSERGEN_API_KEY=brl-k-v7-YOUR-KEY -- npx -y browsergen-mcp

Gemini CLI

gemini mcp add --transport http browsergen https://api.browsergen.com/mcp \
  --header "Authorization: Bearer brl-k-v7-YOUR-KEY"

Cursor

{
  "mcpServers": {
    "browsergen": {
      "url": "https://api.browsergen.com/mcp",
      "headers": { "Authorization": "Bearer brl-k-v7-YOUR-KEY" }
    }
  }
}

Windsurf

Windsurf uses serverUrl where other clients use url:

{
  "mcpServers": {
    "browsergen": {
      "serverUrl": "https://api.browsergen.com/mcp",
      "headers": { "Authorization": "Bearer brl-k-v7-YOUR-KEY" }
    }
  }
}

VS Code

For Copilot agent mode:

code --add-mcp '{"name":"browsergen","type":"http","url":"https://api.browsergen.com/mcp","headers":{"Authorization":"Bearer brl-k-v7-YOUR-KEY"}}'

Claude Desktop

Under Settings > Connectors, add a custom connector with this URL (Claude Desktop connectors cannot send headers, hence the query key):

https://api.browsergen.com/mcp?key=brl-k-v7-YOUR-KEY

Or run the stdio bridge instead:

{
  "mcpServers": {
    "browsergen": {
      "command": "npx",
      "args": ["-y", "browsergen-mcp"],
      "env": { "BROWSERGEN_API_KEY": "brl-k-v7-YOUR-KEY" }
    }
  }
}

ChatGPT and claude.ai

Both take a plain server URL (ChatGPT under Developer mode, claude.ai under custom connectors). Paste the endpoint with the query-parameter key:

https://api.browsergen.com/mcp?key=brl-k-v7-YOUR-KEY

Tools

The server exposes 16 tools. Four manage session lifecycle; the rest drive the page.

Session lifecycle

Page control

How sessions behave

• Implicit creation. The first page tool call auto-creates a session with default settings; agents can simply call browser_navigate. Use browser_create_session first when you need a specific timeout, exit country, or proxy.
• Idle end. A session ends 2 minutes after its last tool call (or CDP disconnect), and always at its absolute timeout. browser_stop_session frees the slot immediately.
• Human handoff via the live view. Every session has a live view at https://browsergen.com/dash/sessions/{id} where a person can watch the agent work and take over for logins, captchas, or 2FA, then hand control back.

Related