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

> MCP server for Browser Agent Protocol. Gives any MCP-compatible AI agent full browser control.

# BAP MCP Server

MCP (Model Context Protocol) server that gives any MCP-compatible AI agent full browser control. Translates MCP tool calls into BAP protocol commands, which drive a real browser via Playwright.

## Architecture

```
+--------------+     MCP      +--------------+    BAP     +--------------+
|  AI Agent    | ------------ |  BAP MCP     | ---------- | BAP Server   |
|  (any MCP    |   (stdio)    |   Server     | (WebSocket)| (Playwright) |
|   client)    |              |              |            |              |
+--------------+              +--------------+            +--------------+
                                                               |
                                                               v
                                                         +-----------+
                                                         |  Browser  |
                                                         +-----------+
```

1. AI agent sends tool calls via MCP (stdio transport)
2. BAP MCP server translates them to BAP protocol
3. BAP Playwright server controls the browser via Playwright
4. Results flow back to the agent

## Two Modes

<CardGroup cols={2}>
  <Card title="Standalone Mode (default)" icon="rocket">
    Auto-starts a BAP Playwright server as a child process. No separate server setup needed. Just
    run the MCP server and it handles everything.
  </Card>

  <Card title="Connected Mode" icon="plug">
    Connects to an externally-managed BAP Playwright server via `--url`. Use when you want to share
    a single server across multiple MCP clients or manage the server lifecycle yourself.
  </Card>
</CardGroup>

### Standalone Mode

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

The MCP server spawns a Playwright server internally. No configuration needed.

### Connected Mode

Start a BAP server externally, then point the MCP server at it:

```bash theme={null}
npx @browseragentprotocol/mcp --url ws://localhost:9222
```

## Quick Start

<Steps>
  <Step title="Run the MCP server">`bash npx @browseragentprotocol/mcp `</Step>

  <Step title="Connect from your AI agent">
    The server communicates over stdio. Configure your MCP client to launch the command above.
  </Step>

  <Step title="Use browser tools">
    Your agent now has access to 23 browser tools: navigate, observe, act, extract, screenshot, and
    more.
  </Step>
</Steps>

## 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 -- your agent is notified of errors as they happen.

## CLI Options

<ParamField path="-b, --browser" type="string" default="chrome">
  Browser to use: `chrome`, `chromium`, `firefox`, `webkit`, `edge`.
</ParamField>

<ParamField path="-u, --url" type="string">
  Connect to an existing BAP server (skips auto-start). Example: `ws://localhost:9222`.
</ParamField>

<ParamField path="-p, --port" type="number" default="9222">
  Port for the auto-started server (standalone mode only).
</ParamField>

<ParamField path="--headless" type="flag" default="true">
  Run browser in headless mode (default).
</ParamField>

<ParamField path="--no-headless" type="flag">
  Show the browser window.
</ParamField>

<ParamField path="--allowed-domains" type="string">
  Comma-separated list of allowed domains. Supports wildcards (e.g., `*.example.com`).
</ParamField>

<ParamField path="--slim" type="flag">
  Expose only 5 essential tools. See [Slim Mode](/mcp/slim-mode).
</ParamField>

<ParamField path="--in-process" type="flag">
  Run the Playwright server in-process. See [In-Process Mode](/mcp/in-process).
</ParamField>

<ParamField path="-v, --verbose" type="flag">
  Enable verbose logging to stderr.
</ParamField>

## 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 in your MCP client config:

    ```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="Local Chrome not found">
    The MCP server tries your local Chrome first. If not found, it falls back to bundled Chromium with a warning. To use a specific browser, pass `--browser chromium` or `--browser firefox`.
  </Accordion>
</AccordionGroup>