Transport

WebSocket configuration, message format, authentication, and security for BAP connections.

WebSocket Configuration

Setting	Default	Description
Endpoint	ws://localhost:9222	WebSocket URL for the BAP server
Health check	GET /health	Returns {"status":"ok","version":"0.8.0"}
Max message size	10 MB	Configurable via BAP_MAX_MESSAGE_SIZE env var

Message Format

All messages follow the JSON-RPC 2.0 specification.

Request

{
  "jsonrpc": "2.0",
  "method": "page/navigate",
  "params": {
    "url": "https://example.com",
    "waitUntil": "domcontentloaded"
  },
  "id": 1
}

Success Response

{
  "jsonrpc": "2.0",
  "result": {
    "url": "https://example.com",
    "title": "Example Domain"
  },
  "id": 1
}

Error Response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32012,
    "message": "Element not found",
    "data": {
      "retryable": true,
      "retryAfterMs": 500,
      "details": { "selector": { "type": "text", "value": "Submit" } },
      "recoveryHint": "Run observe() to refresh interactive elements, then retry with an updated selector"
    }
  },
  "id": 2
}

Notification (Server to Client)

Notifications have no id field and expect no response:

{
  "jsonrpc": "2.0",
  "method": "notifications/console",
  "params": {
    "pageId": "page-1",
    "type": "error",
    "text": "Uncaught TypeError: Cannot read property 'x' of null"
  }
}

Authentication

BAP supports optional token-based authentication via two mechanisms:

Query Parameterws://localhost:9222?token=your-secret-token

HeaderX-BAP-Token: your-secret-token

When a token is configured on the server, all connections must provide a valid token. Connections without a valid token are rejected immediately.

Security Features

Domain Allowlist

The server supports a domain allowlist that restricts which URLs can be navigated to:

# MCP server with domain restriction
npx @browseragentprotocol/mcp --allowed-domains "example.com,api.example.com"

Attempting to navigate to a domain not in the allowlist returns a DomainNotAllowed error (code -32041).

Scope-Based Authorization

BAP defines four authorization scopes that control what actions a client can perform:

Scope	Allowed Operations
readonly	Observations only (screenshot, accessibility, content, observe)
standard	Read + navigation + safe actions (click, fill, type)
full	All operations including storage, cookies, file upload
privileged	Full + eval, network interception, approval override

Network Event Redaction

Server-pushed network events automatically redact sensitive headers:

• authorization, cookie, set-cookie
• x-api-key, x-auth-token, x-csrf-token
• proxy-authorization
• All postData is blanket-redacted

URL Validation

All navigation methods (page/navigate, page/create, storage/setState) validate URLs before execution. javascript: protocol and cloud metadata endpoints are blocked.

Connection Management

Auto-Reconnect (Client SDK)

The TypeScript and Python SDKs implement exponential backoff reconnection:

Attempt 1: delay * 2^0 = 1000ms
Attempt 2: delay * 2^1 = 2000ms
Attempt 3: delay * 2^2 = 4000ms
...
Max attempts: 5 (configurable)

Request Timeout

All requests have a 30-second default timeout. Timed-out requests receive a Timeout error (code -32016) with retryable: true.

Concurrent Requests

The protocol supports multiple in-flight requests. Each request gets a unique numeric ID, and responses are matched by ID. There is no ordering guarantee between independent requests.