BrowserPair

BrowserPair Remote MCP for AI Browser Agents

Connect AI agents through OAuth or MCP keys to run durable tasks with explicit tools, verified results and account-wide Permissions.

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

[card] Scoped

Every tool call follows the authorised connected browser, task contract and current account-wide Permissions.

[card] Durable

Task identity and effect state survive normal reconnects.

[card] Composable

The external Agent Model can inspect state, delegate bounded Decision Model work, request observations, and respond.

Connect

[card] MCP endpoint

https://mcp.browserpair.com

[card] Authentication

Authorization: Bearer bp_live_…, or OAuth for AI apps

[!NOTE]

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

ChatGPT and Claude can connect via OAuth without a copied key; confirm their identity and browser on consent. Account-wide Permissions control sensitive-step questions. See Connect an AI app.

Every tool declares readOnlyHint, destructiveHint and openWorldHint, and results include a short guidance sentence that tells the agent what to do next, for example when a step waits for the user's approval in Chrome or an uncertain effect must be checked before any retry.

Tool surface

Tool	Purpose
browser_list	List available browser profiles, names and online status.
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 Decision Model.
task_observe	Request a fresh browser observation without performing an action.
task_diagnostics	Read a task tab's console messages or request list (bounded, redacted, no headers or bodies). Needs diagnostics_read.
Page actions	task_navigate, task_click, task_fill, task_select, task_press, task_hover, task_scroll, task_drag, task_upload, task_set_viewport and other individually named tools act on current task evidence.
Tabs	task_open_tab, task_back, task_switch_tab, task_adopt_tab and task_close_tab (only a task-owned tab can be closed).
User steps and uncertain effects	task_user_step requests manual user input; task_resolve_effect reconciles an uncertain action after a fresh observation.
Finish	task_done, task_blocked and task_handoff finish or return control without claiming an unsupported result.
Legacy compatibility (agent keys only)	task_respond can still be available to key-authenticated MCP clients. OAuth connections use only the named actions.
task_cancel	Cancel the task.

Tabs and browser ownership

Observations can include task_tabs for task-owned tabs and open_tabs for eligible user-opened tabs, according to the user's current Permissions setting. An agent can continue an existing user-owned tab with task_adopt_tab only when it names that tab and the site is authorized. Adoption never transfers ownership: the user's tab is not closed by BrowserPair. task_close_tab and task_done with tabs: close can close task-created tabs only.

Start a task

browser_run requires:

[card] Goal

What the task should accomplish.

[card] Browser

The connected browser_id inside the key scope.

[card] Allowed domains

One or more explicit task websites.

Optional fields are capabilities, confirmations, and max_side_effects.

Capability names are task hints; the current account Permissions governs sensitive-step confirmations, and task-required confirmations remain immutable.

[!TIP]

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

Recommended external-agent loop

1. Discover

Call browser_list and select an online browser inside the key scope.

2. Create

Call browser_run with the goal, browser, websites, and required capabilities.

3. Read state

Call task_state and use only the current interaction generation.

4. Choose the next mode

Choose one current task_* action, delegate bounded work with task_subgoal, or request richer context with task_observe.

5. Finish deliberately

Use task_done with observable evidence, task_blocked when the work cannot continue, or cancel. An uncertain effect needs fresh evidence first.

Delegate to Decision Model

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

[card] Bounded work

Provide a subgoal, optional success criteria, and an optional maximum step count.

[card] Skill-aware

Optionally bind a compatible Skill so Decision Model has reusable workflow knowledge.

Decision Model 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.

Use current tools safely

Each Remote MCP browser step has a separate named tool, taking fresh observation refs and the matching interaction_generation where required. For OAuth-connected AI apps, use the named task_* tools: task_respond is not advertised to those connections. Agent-key MCP clients may still receive task_respond for compatibility with older integrations; new clients should prefer the named tools. The separate REST endpoint POST /v1/tasks/:id/respond also remains available.

When an action's effect is unknown, request a fresh observation and reconcile with task_resolve_effect rather than replaying the action. A dismissed page confirmation can be accepted only through a new, specifically approved action. BrowserPair still checks account Permissions, task contract and Chrome restrictions at every step.

[!WARNING]

Never invent element refs, task permissions or a verified result. An apparent success in the model's text is not proof of a website side effect.

Idempotency

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

[card] REST API

Prefer explicit HTTP if you do not need an MCP client.

[card] Permissions

Understand the authority applied to every tool call.

[card] Skills

Add reusable workflow knowledge to bounded Decision Model work.

This documentation is built and hosted on Mintlify, a developer documentation platform.