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

# BrowserPair Remote MCP for AI Browser Agents

> Connect MCP-speaking AI agents to BrowserPair with scoped keys, durable tasks, bounded Reflex subgoals, and browser observations.

Use Remote MCP when Claude, Codex, or another MCP-speaking agent should remain the **Brain** while BrowserPair provides scoped access to the user's connected browser.

<CardGroup cols={3}>
  <Card title="Scoped" icon="shield">
    Every tool call stays inside the agent key and task authority.
  </Card>

  <Card title="Durable" icon="arrows-rotate">
    Task identity and effect state survive normal reconnects.
  </Card>

  <Card title="Composable" icon="plug">
    The external Brain can inspect state, delegate bounded Reflex work, request observations, and respond.
  </Card>
</CardGroup>

## Connect

<CardGroup cols={2}>
  <Card title="MCP endpoint" icon="plug">
    `https://mcp.browserpair.com`
  </Card>

  <Card title="Authentication" icon="key">
    `Authorization: Bearer bp_live_…`
  </Card>
</CardGroup>

<Note>
  The `bp_live_…` token is an agent credential, not a browser-device credential. The extension never stores the agent key.
</Note>

## Tool surface

| Tool           | Purpose                                                                           |
| -------------- | --------------------------------------------------------------------------------- |
| `browser_list` | List browser profiles available to the key and whether each is online.            |
| `browser_run`  | Start one durable bounded browser task.                                           |
| `task_state`   | Read current task state and the latest bounded interaction.                       |
| `task_subgoal` | Delegate a bounded subgoal to BrowserPair Reflex.                                 |
| `task_observe` | Request a fresh browser observation without performing an action.                 |
| `task_respond` | Perform one bounded agent response, resolve an effect, finish, or report blocked. |
| `task_cancel`  | Cancel the task.                                                                  |

## Start a task

`browser_run` requires:

<CardGroup cols={3}>
  <Card title="Goal" icon="bullseye">
    What the task should accomplish.
  </Card>

  <Card title="Browser" icon="browser">
    The connected `browser_id` inside the key scope.
  </Card>

  <Card title="Allowed domains" icon="globe">
    One or more explicit task websites.
  </Card>
</CardGroup>

Optional fields are `capabilities`, `confirmations`, and `max_side_effects`.

If capabilities are omitted, BrowserPair uses the ordinary browsing set: `read`, `navigate`, `click`, `fill`, and `select`.

<Tip>
  Multiple websites can be authorized at task start. Keep the set as narrow as the workflow allows.
</Tip>

## Recommended external-agent loop

<Steps>
  <Step title="Discover">
    Call `browser_list` and select an online browser inside the key scope.
  </Step>

  <Step title="Create">
    Call `browser_run` with the goal, browser, websites, and required capabilities.
  </Step>

  <Step title="Read state">
    Call `task_state` and use only the current interaction generation.
  </Step>

  <Step title="Choose the next mode">
    Respond directly with `task_respond`, delegate routine work with `task_subgoal`, or request richer context with `task_observe`.
  </Step>

  <Step title="Finish deliberately">
    Report `done`, `blocked`, resolve an uncertain effect, or cancel.
  </Step>
</Steps>

## Delegate to Reflex

`task_subgoal` is useful when the external Brain knows the next bounded objective but does not need to choose every click.

<CardGroup cols={2}>
  <Card title="Bounded work" icon="bolt">
    Provide a subgoal, optional success criteria, and an optional maximum step count.
  </Card>

  <Card title="Skill-aware" icon="wand-magic-sparkles">
    Optionally bind a compatible Skill so Reflex has reusable workflow knowledge.
  </Card>
</CardGroup>

Reflex returns control when confidence is too low, it reaches its bound, or it becomes blocked.

## Request richer context

`task_observe` can request:

* `lite`
* `accessibility`
* `dom`
* `screenshot`
* `combined`

with either `relevant-region` or `full-page` scope.

<Warning>
  Observation depth does not change authority. Account observation policy, domain scope, capabilities, and sensitive-data redaction still apply.
</Warning>

## Respond safely

Current action kinds include `navigate`, `open_tab`, `back`, `click`, `fill`, `select`, `focus`, `press`, `scroll`, `wait`, `done`, `blocked`, and `resolve_effect`.

<Warning>
  Never invent a DOM or accessibility ref. Use only refs returned by the current BrowserPair interaction, with the matching interaction generation.
</Warning>

## Idempotency

MCP request IDs are mapped to BrowserPair task idempotency keys for `browser_run`. Retrying the same MCP request does not create another task.

<CardGroup cols={3}>
  <Card title="REST API" icon="code" href="/rest-api">
    Prefer explicit HTTP if you do not need an MCP client.
  </Card>

  <Card title="Permissions" icon="shield" href="/permissions">
    Understand the authority applied to every tool call.
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/skills">
    Add reusable workflow knowledge to bounded Reflex work.
  </Card>
</CardGroup>