MCP Setup

Add BAP as an MCP server for Claude Code, Codex, Cursor, and other MCP clients

The BAP MCP server gives any MCP-compatible AI agent full browser control. It auto-starts a Playwright server and exposes browser tools over MCP stdio transport.

One-Command Setup

npx @browseragentprotocol/mcp

This starts standalone mode: auto-spawns a BAP Playwright server and bridges MCP tool calls to browser actions. No separate server process needed.

Client Configuration

Claude Code

claude mcp add --transport stdio bap-browser -- npx -y @browseragentprotocol/mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bap-browser": {
      "command": "npx",
      "args": ["-y", "@browseragentprotocol/mcp"]
    }
  }
}

Codex CLI

bash codex mcp add bap-browser -- npx -y @browseragentprotocol/mcp

Codex Desktop

Add to ~/.codex/config.toml: toml [mcp_servers.bap-browser] command = "npx" args = ["-y", "@browseragentprotocol/mcp"]

Cursor

Add to your MCP configuration in Cursor settings:

{
  "bap-browser": {
    "command": "npx",
    "args": ["-y", "@browseragentprotocol/mcp"]
  }
}

Available Tools

The MCP server exposes 23 tools by default, grouped by category:

Navigation (4 tools)

Tool	Description
navigate	Navigate to a URL. Supports fused observe parameter
go_back	Navigate back in browser history
go_forward	Navigate forward in browser history
reload	Reload the current page

Element Interaction (7 tools)

| Tool | Description | |------|-------------| | click | Click an element using semantic selectors | | type | Type text character by character | | fill | Fill a form field (clears existing content) | | press | Press keyboard keys (Enter, Tab, shortcuts) | | select | Select a dropdown option | | scroll | Scroll the page or a specific element | | hover | Hover over an element |

Observation (5 tools)

| Tool | Description | |------|-------------| | screenshot | Take a page screenshot | | accessibility | Full accessibility tree | | aria_snapshot | Token-efficient YAML snapshot (~80% fewer tokens) | | content | Page text content as text or markdown | | element | Query element properties (exists, visible, enabled) |

AI Agent Methods (3 tools)

| Tool | Description | |------|-------------| | observe | AI-optimized observation with interactive elements and stable refs. Supports incremental and responseTier | | act | Execute a sequence of browser actions in one call. Supports fused postObserve | | extract | Extract structured data using schema and CSS heuristics |

Page Management (3 tools)

| Tool | Description | |------|-------------| | pages | List all open pages/tabs | | activate_page | Switch to a different page/tab | | close_page | Close the current page/tab |

Discovery (1 tool)

Tool	Description
discover_tools	Discover WebMCP tools exposed by the current page

Slim Mode

Use --slim to expose only 5 essential tools, reducing tool definitions from ~4,200 to ~600 tokens:

npx @browseragentprotocol/mcp --slim

The 5 slim tools: navigate, observe, act, extract, screenshot.

Slim mode is ideal for models with limited context windows or when you want to minimize token overhead from tool definitions.

CLI Options

-b, --browser <name>        Browser: chrome (default), chromium, firefox, webkit, edge
-u, --url <url>             Connect to existing BAP server (skips auto-start)
-p, --port <number>         Port for auto-started server (default: 9222)
--headless                  Run browser headless (default: true)
--no-headless               Visible browser window
--allowed-domains <list>    Comma-separated domain allowlist
--slim                      Expose only 5 essential tools
--in-process                Run Playwright server in-process (zero overhead)
-v, --verbose               Enable verbose logging to stderr

Connected Mode

If you already have a BAP Playwright server running, connect to it directly:

npx @browseragentprotocol/mcp --url ws://localhost:9222

This skips auto-start and connects to your existing server instance.

In-Process Mode

For zero-overhead MCP, use --in-process to bypass the WebSocket layer entirely:

npx @browseragentprotocol/mcp --in-process

This runs the Playwright server in the same process using DirectTransport.

In-process mode does not support server-push notifications (event streaming). Use standard mode if you need console error and network failure forwarding.

Event Streaming

Browser console errors and 4xx/5xx network responses are automatically forwarded to connected MCP clients as notifications/message log entries. No configuration needed.

Selector Formats

All tools that accept a selector parameter support these formats:

role:button:Submit        # ARIA role + accessible name (recommended)
text:Sign in              # Visible text content
label:Email address       # Associated label
testid:submit-button      # data-testid attribute
ref:@submitBtn            # Stable element reference from observe
css:.btn-primary          # CSS selector (fallback)
xpath://button[@type]     # XPath selector (fallback)

Programmatic Usage

import { BAPMCPServer } from "@browseragentprotocol/mcp";

const server = new BAPMCPServer({
  bapServerUrl: "ws://localhost:9222",
  name: "my-browser-server",
  verbose: true,
});

await server.run();

Troubleshooting

Connection closed on Windows

On native Windows (not WSL), use the cmd /c wrapper:

{
  "mcpServers": {
    "bap-browser": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@browseragentprotocol/mcp"]
    }
  }
}

Server not starting

Ensure Playwright browsers are installed: bash npx playwright install chromium

Headless mode on retina displays

MCP defaults to headless: true. If you override to headless: false on a retina Mac, screenshots will be 2x DPI, doubling their size. BAP mitigates this with deviceScaleFactor: 1 and scale: "css" on screenshots.