Browser as API/MCP /mcp
Turn your logged-in Chrome profile into an agentic API endpoint. Call planner + tools in your own browser via a simple HTTP request or any MCP-compatible client.
Unlike /agent and /scrape (which run in rtrvr.ai's browser cluster), /mcp controls your local Chrome via the extension as a remote MCP server.
OAuth Support
Sign in with Google via mcp.rtrvr.ai for secure, token-based authentication.
HTTP + MCP Protocol
Use the MCP URL in Claude/clients, or POST JSON directly from any backend.
Multi-Device
Install on multiple Chrome profiles and target specific devices by ID.
Video Tutorials
Introduction
MCP Deep Dive
Browser as API/MCP Playground
POST/mcpControl your logged-in Chrome via HTTP or MCP protocol
https://mcp.rtrvr.aiShared by both direct HTTP calls and MCP clients. Both your API key and deviceId are embedded in the MCP URL generated by the extension.
The rtrvr.ai Chrome Extension registers as a remote browser device and exposes a single public entrypoint at https://mcp.rtrvr.ai. That same endpoint speaks:
- MCP: paste the generated MCP URL (includes
apiKey+deviceId) into any MCP-enabled client (e.g. Claude). - HTTP: POST JSON describing
tool+params, and we dispatch that task into one of your online extension devices.
"Your Chrome browser is now an Agentic API Endpoint."
Trigger complex workflows in your own logged-in browser instance from CI/CD, Slack bots, cron jobs, or backend services.
OAuth Support (Recommended)
MCP clients that support OAuth can authenticate by connecting to mcp.rtrvr.ai directly. This triggers a Google Sign-In flow and returns a secure session token.
API Key in URL (Fallback)
For MCP clients without OAuth support, embed your API key directly in the URL:
https://mcp.rtrvr.ai?apiKey=rtrvr_your_api_key&deviceId=your_device_idFor direct HTTP calls, auth can be provided via:
Authorization: Bearer YOUR_API_KEY(recommended)X-API-Key: YOUR_API_KEY- Query param:
?apiKey=YOUR_API_KEY
Authorization: Bearer rtrvr_your_api_keyEach Chrome/Chromium profile you install the extension into registers as a separate deviceId. This enables powerful multi-device workflows:
How deviceId works:
- Your
deviceIdis embedded in the MCP URL generated by the extension - Install the extension on multiple browsers/profiles to get multiple deviceIds
- Target a specific device by passing
deviceIdin your request - Leave deviceId blank to auto-select the most recently active online device
Device selection rules:
- Explicit deviceId: Pass
deviceIdordevice_idin the query or body to target a specific device. - No deviceId (default): The most recently active online device is auto-selected (highest
lastSeentimestamp). - Multi-profile orchestration: Install the extension on multiple browser profiles and orchestrate them independently by calling
/mcpwith different device IDs. - Device-independent tools: Utility tools like
get_current_creditsandlist_deviceswork even if no device is online.
Finding your deviceId:
- From MCP URL: Open the extension → MCP / Remote Browser → copy the MCP URL. The
deviceIdparameter is embedded in the URL. - Via API: Call
list_devicesto see all registered devices and their online/offline status.
// List all your devices
curl -X POST "https://mcp.rtrvr.ai" \
-H "Authorization: Bearer rtrvr_xxx" \
-H "Content-Type: application/json" \
-d '{"tool": "list_devices"}'
// Response shows deviceId + online status
{
"success": true,
"data": {
"devices": [
{ "deviceId": "dj75mmaTWP0", "online": true, "lastSeen": "2025-01-15T10:30:00Z" },
{ "deviceId": "abc123XYZ", "online": false, "lastSeen": "2025-01-14T18:00:00Z" }
]
}
}https://mcp.rtrvr.aiThe same endpoint powers both MCP and HTTP. For HTTP, you send a single JSON object describing which tool to run, which device to target, and which parameters to pass through.
interface BrowserAgentApiRequest {
/**
* Canonical tool name, e.g. "planner" or "get_browser_tabs".
* Only one of "tool" or "action" is required.
*/
tool?: string;
/**
* CamelCase alias, e.g. "getBrowserTabs".
* Normalized to the same underlying tool.
*/
action?: string;
/**
* Parameters for the tool. Normalized with "parameters".
* snake_case and camelCase are both accepted and merged.
*/
params?: Record<string, any>;
parameters?: Record<string, any>;
/**
* Optional: route to a specific Chrome profile / device.
* If omitted, the most recently active online device is used.
*/
deviceId?: string;
device_id?: string;
/**
* Per-request timeout in milliseconds (default: 300000 / 5 minutes).
*/
timeout?: number;
/**
* Reserved for future async modes.
*/
async?: boolean;
webhookUrl?: string;
}Top-level fields
toolstringCanonical tool name (snake_case), e.g. 'planner' or 'get_browser_tabs'. Only one of tool/action is required.
actionstringCamelCase alias, e.g. 'getBrowserTabs'. Normalized to the same underlying tool as 'get_browser_tabs'.
params / parametersobjectJSON object of tool-specific parameters. 'params' and 'parameters' are aliases; snake_case and camelCase keys are normalized.
deviceId / device_idstringOptional device routing. If omitted, we pick the most recently active online browser extension device for that user. Find yours in the MCP URL or via list_devices.
timeoutnumberdefault: 300000Max execution time for this request in milliseconds. Defaults to 5 minutes.
async / webhookUrlboolean / stringReserved for future async execution modes. Ignored for now.
The Browser as API/MCP exposes the same tool surface as the extension. Tools are grouped into free (no credits) and credit-based families, plus utility tools and user-defined functions.
Free tools (no credits)
get_browser_tabs– list open tabs (filter by all/active/domain).get_page_data– get accessibility-tree representations for specific tab IDs.take_page_action– run system tools like click, type, scroll, etc.execute_javascript– run JS inside a secure browser sandbox (disabled by default).
Credit-based tools
planner– multi-step planning and tool orchestration from natural language.act– intelligent page interaction with optional structured schemas.extract– structured extraction to JSON or Google Sheets.crawl– multi-page crawls with schema extraction.replay_workflow– replay a previously executed workflow by task ID or shared URL.
Utility & user-defined tools
list_devices– list all registered extension devices and online/offline status.get_current_credits– fetch current plan, credits used, and credits remaining.user_function– user-defined tools created in Cloud and executed in the extension sandbox.
Tool name aliases
The handler normalizes several variants:
get_browser_tabs⇔getBrowserTabsget_page_data⇔getPageDatatake_page_action⇔takePageActionexecute_javascript⇔executeJavaScript⇔executeJslist_devices⇔listDevicesreplay_workflow⇔replayWorkflow
Parameter aliases
Common parameters accept snake_case and camelCase:
user_input⇔userInputtab_urls⇔tabUrlsdevice_id⇔deviceIdmax_steps⇔maxStepstask_id⇔taskIdrecording_id⇔recordingIdfile_urls⇔fileUrlsimage_urls⇔imageUrlsshared_workflow_url⇔sharedWorkflowUrl
All credit tools support file and image inputs via publicly fetchable URLs. Files are automatically uploaded to Firebase Storage and passed to the agent as context.
Supported input parameters:
file_urls– array of publicly fetchable file URLs (CSV, PDF, etc.)image_urls– array of publicly fetchable image URLs (JPG, PNG, etc.)recording_id– ID of a recorded workflow to use as context
file_urlsCSV, PDF, text files to use as input data
image_urlsJPG, PNG images for visual context
recording_idRecorded workflow to use as context
{
"tool": "planner",
"params": {
"user_input": "Upload this CSV and submit the form",
"tab_urls": ["https://example.com/upload"],
"file_urls": ["https://example.com/data.csv"],
"image_urls": ["https://example.com/screenshot.png"],
"recording_id": "rec_abc123"
}
}The replay_workflow tool allows you to re-execute a previously completed workflow. You can replay your own workflows by task ID, or replay workflows shared by other users via a shared URL.
Two ways to replay:
task_id– replay your own workflow by execution IDshared_workflow_url– replay a workflow shared by another user
At least one of these must be provided.
Parameters
task_idstringThe task ID from a previous workflow execution in your history.
shared_workflow_urlstringA shared workflow URL (e.g., https://www.rtrvr.ai/shared/Tasks/userId/taskId/token). Use this to replay workflows shared by other users.
tab_execution_modestringdefault: new_tabsHow to handle tabs during replay.
"new_tabs""reuse_tabs""current_context"recording_idstringOptional recording ID to use as additional context.
file_urlsstring[]Optional file URLs to include as input.
image_urlsstring[]Optional image URLs to include as input.
// By task ID (your own workflow)
{
"tool": "replay_workflow",
"params": {
"task_id": "abc123xyz",
"tab_execution_mode": "new_tabs"
}
}
// By shared URL (another user's workflow)
{
"tool": "replay_workflow",
"params": {
"shared_workflow_url": "https://www.rtrvr.ai/shared/Tasks/userId/taskId/token"
}
}Below is a conceptual TypeScript view of each tool's parameters.
// Free tools
get_browser_tabs({
filter?: "all" | "active" | "domain";
domain?: string;
device_id?: string;
});
get_page_data({
tabIds: number[];
device_id?: string;
});
take_page_action({
actions: {
tab_id?: number;
tool_name: SystemToolName;
args: Record<string, any>;
}[];
device_id?: string;
});
execute_javascript({
code: string;
timeout?: number;
context?: Record<string, any>;
device_id?: string;
});
// Credit tools
planner({
user_input: string;
context?: string;
tab_urls?: string[];
max_steps?: number;
device_id?: string;
recording_id?: string; // Recording ID to use as workflow context
file_urls?: string[]; // Publicly fetchable file URLs
image_urls?: string[]; // Publicly fetchable image URLs
});
act({
user_input: string;
tab_urls?: string[];
schema?: {
fields: {
name: string;
description: string;
type: string;
required?: boolean;
}[];
};
tab_id?: number;
device_id?: string;
recording_id?: string;
file_urls?: string[];
image_urls?: string[];
});
extract({
user_input: string;
tab_urls?: string[];
schema?: {
fields: {
name: string;
description: string;
type: string;
required?: boolean;
}[];
};
output_destination?: {
type: "json" | "google_sheet";
new_sheet_title?: string;
new_tab_title?: string;
existing_sheet_id?: string;
existing_tab_title?: string;
};
tab_id?: number;
device_id?: string;
recording_id?: string;
file_urls?: string[];
image_urls?: string[];
});
crawl({
user_input: string;
tab_urls?: string[];
schema?: { fields: { name: string; description: string; type: string; required?: boolean; }[]; };
max_pages?: number;
follow_links?: boolean;
link_pattern?: string;
output_destination?: { type: "json" | "google_sheet"; new_sheet_title?: string; };
tab_id?: number;
device_id?: string;
recording_id?: string;
file_urls?: string[];
image_urls?: string[];
});
replay_workflow({
task_id?: string; // Task ID from previous execution
shared_workflow_url?: string; // Shared workflow URL from another user
tab_execution_mode?: "new_tabs" | "reuse_tabs" | "current_context";
recording_id?: string;
file_urls?: string[];
image_urls?: string[];
});
// User functions (defined in Cloud and executed in the browser sandbox)
user_function({
functionName: string;
// your custom parameters...
});All tools return a consistent envelope with tool-specific data plus metadata:
interface BrowserAgentApiResponse<TData = any> {
success: boolean;
data: TData | null;
error: string | null;
metadata: {
requestId: string;
executionTime: number;
tool: string;
deviceId?: string;
creditsUsed?: number;
creditsRemaining?: number;
};
timestamp: string;
}{
"success": true,
"data": {
"tabs": [{ "id": 1, "url": "https://example.com" }],
"activeTab": { "id": 1, "url": "https://example.com" },
"tabCount": 1
},
"error": null,
"metadata": {
"requestId": "req_abc123",
"executionTime": 1234,
"tool": "get_browser_tabs",
"deviceId": "dj75mmaTWP0",
"creditsUsed": 0,
"creditsRemaining": 10000
},
"timestamp": "2025-01-01T12:00:00.000Z"
}metadata.deviceIdshows which device executed the request.metadata.requestIdis useful for joining logs with rtrvr.ai's internal state.- HTTP headers like
X-Credits-UsedandX-Credits-Remainingare also surfaced.
Remote tool execution can be configured at a per-user and per-tool level via the extension settings and the Cloud dashboard.
- Disable remote browser tools entirely for a given user.
- Independently enable/disable free tools and credit tools.
- Toggle individual tools inside each family.
- All configuration is respected by the MCP handler; disabled tools yield an explanatory error.
If /mcp calls fail with No online devices found or other errors:
- Open/close the rtrvr.ai Chrome extension popup to refresh its connection.
- Rotate your API key from the extension dropdown to re-sync backend state.
- Sign out and sign back into the extension to reset device registration.
- Call
list_devicesto see which devices are online. - Ensure the deviceId you're targeting matches an online device.
- Install the rtrvr.ai Chrome Extension.
- Open the MCP / Remote Browser section in the extension.
- Copy the generated MCP URL — your API key and deviceId are already embedded. Alternatively, get your API key from rtrvr.ai/cloud.
- For MCP clients: paste the URL directly into your MCP-enabled application (e.g. Claude).
- For direct HTTP: call
https://mcp.rtrvr.aiwith your API key in headers. Optionally passdeviceIdto target a specific device. - Multi-device setup: Install the extension on multiple Chrome profiles. Each gets its own deviceId. Target specific devices or leave blank for auto-selection.
- Configure which tools to enable/disable in extension settings.
These snippets show the recommended integration pattern: a thin server-side helper that wraps POST /mcp, keeps your API key off the frontend, and centralizes rate limiting + logging.
# 1) Your browser as an agentic API endpoint
curl -X POST "https://mcp.rtrvr.ai" \
-H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"tool": "planner",
"params": {
"user_input": "Go to ChatGPT.com, ask for top Indian restaurants in SF, and extract back citations.",
"tab_urls": ["https://chatgpt.com"]
},
"deviceId": "dj75mmaTWP0"
}'
# 2) Free tool: list all tabs on your most recent device (no deviceId = auto-select)
curl -X POST "https://mcp.rtrvr.ai" \
-H "X-API-Key: rtrvr_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"tool": "get_browser_tabs",
"params": { "filter": "all" }
}'
# 3) Replay a workflow with file inputs
curl -X POST "https://mcp.rtrvr.ai" \
-H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"tool": "replay_workflow",
"params": {
"task_id": "abc123xyz",
"tab_execution_mode": "new_tabs",
"file_urls": ["https://example.com/data.csv"]
}
}'
# 4) Planner with image context
curl -X POST "https://mcp.rtrvr.ai" \
-H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"tool": "planner",
"params": {
"user_input": "Find similar products to the one in this image",
"tab_urls": ["https://amazon.com"],
"image_urls": ["https://example.com/product.jpg"]
}
}'