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 Brain while BrowserPair provides scoped access to the user's connected browser.

Scoped

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

Durable

Task identity and effect state survive normal reconnects.

Composable

The external Brain can inspect state, delegate bounded Reflex work, request observations, and respond.

Connect

MCP endpoint

https://mcp.browserpair.com

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 Reflex.
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:

Goal

What the task should accomplish.

Browser

The connected browser_id inside the key scope.

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 Reflex

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

Bounded work

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

Skill-aware

Optionally bind a compatible Skill so Reflex has reusable workflow knowledge.

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.

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.

REST API

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

Permissions

Understand the authority applied to every tool call.

Skills

Add reusable workflow knowledge to bounded Reflex work.

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