BrowserPair
Connect AI agents to your existing Chrome browser through Remote MCP with scoped permissions, human approvals, and recoverable browser tasks.
Documentation
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.
Scoped
Every tool call stays inside the agent key and task authority.
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.
AI apps such as ChatGPT and Claude can connect without a key: they discover OAuth from the server's 401 response and you choose their limits on a consent screen. 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 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_diagnostics | Read a task tab's console messages or request list (bounded, redacted, no headers or bodies). Needs diagnostics_read. |
task_respond | Perform one bounded agent response, resolve an effect, finish, or report blocked. To answer a dismissed page confirmation dialog OK, repeat the action with acceptDialog: true (always approved by the user in Chrome; see REST API → Page dialogs). |
task_cancel | Cancel the task. |
Start a task
browser_run requires:
Goal
What the task should accomplish.
Browser
The connected
browser_idinside the key scope.
Allowed domains
One or more explicit task websites.
Optional fields are capabilities, confirmations, and max_side_effects.
If capabilities are omitted, BrowserPair uses the ordinary browsing set: read, navigate, hover, click, fill, and select.
[!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
Respond directly with task_respond, delegate routine work with task_subgoal, or request richer context with task_observe.
5. Finish deliberately
Report done, blocked, resolve an uncertain effect, or cancel.
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:
liteaccessibilitydomscreenshotcombined
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.
Respond safely
Current action kinds include navigate, open_tab, back, adopt_tab, click, double_click, context_click, hover, fill, select, focus, press, scroll, wait, drag, canvas_click, range_click, done, blocked, and resolve_effect. Hover, keys other than Enter, drag and drop, sliders and canvas points each need their own capability (hover, keyboard, drag_drop, range_interaction, canvas_interaction).
[!WARNING]
Never invent a DOM or accessibility ref. Use only refs returned by the current BrowserPair interaction, with the matching interaction generation.
A rejected action says why: capability_denied includes requiredCapability, reason and grantedCapabilities, and resolve_effect with definitely_not_executed is refused (fresh_observation_required) until you have called task_observe after the uncertain action. See REST API → When an action is rejected.
Idempotency
MCP request IDs are mapped to BrowserPair task idempotency keys for browser_run. Retrying the same MCP request does not create another task.
Prefer explicit HTTP if you do not need an MCP client.
Understand the authority applied to every tool call.
Add reusable workflow knowledge to bounded Reflex work.
This documentation is built and hosted on Mintlify, a developer documentation platform.