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

# 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

```bash theme={null}
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

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport stdio bap-browser -- npx -y @browseragentprotocol/mcp
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "bap-browser": {
          "command": "npx",
          "args": ["-y", "@browseragentprotocol/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex CLI">
    `bash codex mcp add bap-browser -- npx -y @browseragentprotocol/mcp `
  </Tab>

  <Tab title="Codex Desktop">
    Add to `~/.codex/config.toml`: `toml [mcp_servers.bap-browser] command = "npx" args = ["-y",
          "@browseragentprotocol/mcp"] `
  </Tab>

  <Tab title="Cursor">
    Add to your MCP configuration in Cursor settings:

    ```json theme={null}
    {
      "bap-browser": {
        "command": "npx",
        "args": ["-y", "@browseragentprotocol/mcp"]
      }
    }
    ```
  </Tab>
</Tabs>

## Available Tools

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

<AccordionGroup>
  <Accordion title="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                               |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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) |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="Discovery (1 tool)">
    | Tool             | Description                                       |
    | ---------------- | ------------------------------------------------- |
    | `discover_tools` | Discover WebMCP tools exposed by the current page |
  </Accordion>
</AccordionGroup>

## Slim Mode

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

```bash theme={null}
npx @browseragentprotocol/mcp --slim
```

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

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

## 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:

```bash theme={null}
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:

```bash theme={null}
npx @browseragentprotocol/mcp --in-process
```

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

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

## 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

```typescript theme={null}
import { BAPMCPServer } from "@browseragentprotocol/mcp";

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

await server.run();
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection closed on Windows">
    On native Windows (not WSL), use the `cmd /c` wrapper:

    ```json theme={null}
    {
      "mcpServers": {
        "bap-browser": {
          "command": "cmd",
          "args": ["/c", "npx", "-y", "@browseragentprotocol/mcp"]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Server not starting">
    Ensure Playwright browsers are installed: `bash npx playwright install chromium `
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>