RUN

Use your signed-in browser.`/mcp`

Let an MCP client or backend use your signed-in Chrome session, including sites behind logins, SSO, and internal tools.

Try a tool Add to Chrome

Your signed-in browser

Use the sessions and permissions already available in Chrome.

MCP or HTTP

Connect an MCP client or send JSON from your backend.

Device and Cloud tools

Use browser tools on your device and knowledge tools in Cloud.

Chrome is required for device-backed tools. Cloud-only tools do not need an extension session.

CLI

Connect an MCP client from your terminal with rtrvr CLI.

rtrvr mcp init --client claude

Video Tutorials

Introduction

MCP Deep Dive

Browser as API/MCP Playground

POST/mcp

Control your logged-in Chrome or call cloud-only knowledge base tools via HTTP or MCP

API Key

Get from rtrvr.ai/cloud or your Chrome Extension

Device ID (optional)

Leave blank to auto-select. Use list_devices to find IDs.

Select Tool

Execute complex multi-step tasks from natural language

Task Description*

Starting URLs

URLs to open before starting

Additional Context

Max Steps

curl -X POST "https://mcp.rtrvr.ai" \
  -H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "planner",
  "params": {}
}'

Endpoint URLhttps://mcp.rtrvr.ai

Shared by both direct HTTP calls and MCP clients. Extension-generated MCP URLs include your API key and deviceId; cloud-only knowledge base tools do not require a device.

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. Extension-backed tools dispatch into your online browser devices, while cloud-only knowledge base tools execute immediately without a device.

"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_id

For 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

Header

Authorization: Bearer rtrvr_your_api_key

Security: Prefer OAuth or headers in production. Avoid exposing API keys in URLs/logs when possible.

Each Chrome/Chromium profile you install the extension into registers as a separate deviceId. This enables powerful multi-device workflows:

How deviceId works:

Your deviceId is 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 deviceId in your request
Leave deviceId blank to auto-select the most recently active online device

Device selection rules:

Explicit deviceId: Pass deviceId or device_id in the query or body to target a specific device.
No deviceId (default): The most recently active online device is auto-selected (highest lastSeen timestamp).
Multi-profile orchestration: Install the extension on multiple browser profiles and orchestrate them independently by calling /mcp with different device IDs.
Device-independent tools: Utility tools like get_current_credits and list_devices work even if no device is online.

Finding your deviceId:

From MCP URL: Open the extension → MCP / Remote Browser → copy the MCP URL. The deviceId parameter is embedded in the URL.
Via API: Call list_devices to see all registered devices and their online/offline status.

Discovering devices

// 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" }
    ]
  }
}

POSThttps://mcp.rtrvr.ai

The same endpoint powers both MCP and HTTP. For HTTP, you send a single JSON object describing which tool to run, which parameters to pass through, and optionally which device to target for extension-backed tools.

BrowserAgentApiRequest (conceptual)

interface BrowserAgentApiRequest {
  /**
   * Canonical tool name, e.g. "planner" or "get_browser_tabs".
   * Only one of "tool" or "action" is required.
   */
  tool?: string;

  /**
   * Optional alias of "tool". Use canonical snake_case tool names.
   */
  action?: string;

  /**
   * Parameters for the tool. "params" and "parameters" are equivalent.
   * Prefer canonical snake_case parameter names.
   */
  params?: Record<string, any>;
  parameters?: Record<string, any>;

  /**
   * Optional: route extension-backed tools to a specific Chrome profile / device.
   * Cloud-only knowledge base tools ignore this field.
   */
  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

toolstring

Canonical tool name (snake_case), e.g. 'planner' or 'get_browser_tabs'. Only one of tool/action is required.

actionstring

Optional alias of tool. Use canonical snake_case tool names for reliability.

params / parametersobject

JSON object of tool-specific parameters. 'params' and 'parameters' are aliases. Prefer snake_case parameter names.

params.options.ui.emitEventsbooleandefault false

Opt-in only. Set true to write execution progress events for SSE/polling consumers. If omitted/false, no execution event stream is written.

deviceId / device_idstring

Optional device routing for extension-backed tools. If omitted, we pick the most recently active online browser extension device for that user. Cloud-only knowledge base tools ignore this field.

timeoutnumberdefault 300000

Max execution time for this request in milliseconds. Defaults to 5 minutes.

async / webhookUrlboolean / string

Reserved for future async execution modes. Ignored for now.

emitEvents policy: API and extension/MCP executions only emit events whenoptions.ui.emitEvents: true. CLI streaming defaults on for run, agent, and scrape (use --no-stream to disable). Streamed payloads at or under 1MB stay inline; larger payloads include inline preview markers and storage references (`outputRef` / `resultRef` / `responseRef`) for full downloads.

The Browser as API/MCP exposes extension-backed browser tools, cloud-only tools, scheduling/trigger management, and utility tools. They are grouped into free, credit-based, cloud, utility, and user-defined families.

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_on_tab – intelligent page interaction with optional structured schemas.
extract_from_tab – structured extraction to JSON or Google Sheets.
crawl_and_extract_from_tab – multi-page crawls with schema extraction.
replay_workflow – replay a previously executed workflow by task ID or shared URL.
schedule – create or modify a scheduled workflow on the browser extension.
trigger_setup – create or modify a trigger workflow on the browser extension.

Cloud tools (no extension required)

cloud_scrape – scrape web pages using cloud browsers, returns accessibility trees.
cloud_agent – execute AI agent tasks using cloud browsers with structured output.
list_skills – list your skill files (persistent markdown memory the agent reads and updates).
get_skill – read one skill file's full markdown by name.
check_schedule_results – check execution results of scheduled workflows from cloud storage.
check_trigger_results – check execution results of trigger workflows from cloud storage.

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.
upload_file – upload a file (base64, URL import, or signed upload URL) to rtrvr storage and get back a storageUrl to attach to agent tools. Free, no device required.
list_recordings – list all user recordings (returns metadata: ID, name, timestamp).
list_custom_functions – list all custom functions (metadata only, not code).
list_schedules – list all scheduled workflow configurations. Works offline.
list_triggers – list all trigger workflow configurations. Works offline.
user_function – user-defined tools created in Cloud and executed in the extension sandbox.

Tool name aliases

Use canonical snake_case tool names. For direct HTTP, action can mirror tool:

tool: "agent" – unified alias that routes to cloud_agent (default) or planner (when extension/local session is requested).
tool: "scrape" – unified alias that routes to cloud_scrape (default) or extension scrape.
tool: "planner" is equivalent to action: "planner".
tool: "act_on_tab" is equivalent to action: "act_on_tab".
For MCP protocol calls, use tool names exactly as returned by tools/list.

Parameter aliases

Prefer snake_case parameters. Common compatibility aliases include:

user_input ⇔ userInput
tab_urls ⇔ tabUrls
device_id ⇔ deviceId
max_steps ⇔ maxSteps
task_id ⇔ taskId
recording_id ⇔ recordingId
file_urls ⇔ fileUrls
image_urls ⇔ imageUrls
shared_workflow_url ⇔ sharedWorkflowUrl
store_id ⇔ storeId
conversation_context ⇔ conversationContext
tab_ids ⇔ tabIds
web_page_map ⇔ webPageMap
auth_token ⇔ authToken

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. For local files that aren't hosted anywhere, use the upload_file tool first (see below) and pass the returned storageUrl.

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_urls

CSV, PDF, text files to use as input data

image_urls

JPG, PNG images for visual context

recording_id

Recorded workflow to use as context

Example with file inputs

{
  "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"
  }
}

Uploading local files: `upload_file`

The upload_file tool stores a file under your account and returns a storageUrl + gcsUri. It is free, needs no device, and supports three modes (max 20MB per file):

Base64: pass name, mimeType, and base64 data — best for small files.
URL import: pass url — the file is copied into rtrvr storage.
Signed upload URL: pass only name and mimeType — you get back a signed uploadUrl valid for 15 minutes. PUT the raw bytes to it (no base64 inflation), then use the returned storageUrl.

Local file → signed upload → agent attachment

# 1. Request a signed upload URL (no bytes in the request)
curl -X POST "https://mcp.rtrvr.ai" \
  -H "Authorization: Bearer rtrvr_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tool": "upload_file", "params": {"name": "resume.pdf", "mimeType": "application/pdf"}}'
# → { "mode": "signed_url", "uploadUrl": "https://storage.googleapis.com/…", "storageUrl": "…", "gcsUri": "gs://…" }

# 2. Upload the raw bytes
curl -X PUT -H "Content-Type: application/pdf" --upload-file ./resume.pdf "<uploadUrl>"

# 3. Attach it to any agent tool
curl -X POST "https://mcp.rtrvr.ai" \
  -H "Authorization: Bearer rtrvr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "planner",
    "params": {
      "user_input": "Apply to this job with my resume",
      "tab_urls": ["https://example.com/careers/apply"],
      "file_urls": ["<storageUrl>"]
    }
  }'

For agent / cloud_agent, attach files via the files parameter instead of file_urls:

cloud_agent / agent files parameter

{
  "tool": "agent",
  "params": {
    "user_input": "Summarize the attached report",
    "files": [
      { "displayName": "report.pdf", "uri": "<storageUrl>", "mimeType": "application/pdf" }
    ]
  }
}

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 ID
shared_workflow_url – replay a workflow shared by another user

At least one of these must be provided.

Parameters

task_idstring

The task ID from a previous workflow execution in your history.

shared_workflow_urlstring

A shared workflow URL (e.g., https://rtrvr.ai/shared/Tasks/userId/taskId/token). Use this to replay workflows shared by other users.

tab_execution_modestringdefault new_tabs

How to handle tabs during replay.

new_tabsreuse_tabscurrent_context

recording_idstring

Optional 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.

Replay workflow examples

// 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://rtrvr.ai/shared/Tasks/userId/taskId/token"
  }
}

Below is a conceptual TypeScript view of each tool's parameters.

Agentic tool 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_on_tab({
  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_from_tab({
  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_and_extract_from_tab({
  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[];
});

// Cloud-only skill tools (no device_id required)
list_skills({});

get_skill({
  name: string;
}});

// Utility: upload a local file to rtrvr storage (free, no device_id required)
upload_file({
  name?: string;      // filename incl. extension; required unless url given
  mimeType?: string;  // inferred from extension if omitted
  data?: string;      // base64 content (small files)
  url?: string;       // OR: public URL to import
  // neither data nor url → returns a signed PUT uploadUrl (15 min)
  // → { storageUrl, gcsUri } to pass via file_urls or files[]
});

// 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:

BrowserAgentApiResponse (conceptual)

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;
    inlineOutputMaxBytes?: number;
    outputTooLarge?: boolean;
    responseRef?: StorageReference;
  };
  timestamp: string;
}

Example: get_browser_tabs response

{
  "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.deviceId shows which device executed the request.
metadata.requestId is useful for joining logs with rtrvr.ai's internal state.
HTTP headers like X-Credits-Used and X-Credits-Remaining are also surfaced.
Large payloads keep inline previews and expose storage refs via metadata.responseRef and/or outputRef/resultRef.

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.

Important: Remote tool execution is enabled by default. Review allowed tools in the Chrome extension MCP / Remote Tools settings to match your security posture.

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_devices to see which devices are online.
Ensure the deviceId you're targeting matches an online device.

Most device issues are resolved by refreshing the extension, rotating the API key, or resetting the sign-in.

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.ai with your API key in headers. Optionally pass deviceId to 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.

The MCP URL generated by the extension includes your API key and deviceId. Treat this URL as a secret: store it safely, avoid logging it in plaintext, and rotate as needed.

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.

cURL

# 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"],
      "options": {
        "ui": {
          "emitEvents": true
        }
      }
    },
    "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"]
    }
  }'

# 5) Cloud-only skills listing (no deviceId required)
curl -X POST "https://mcp.rtrvr.ai" \
  -H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_skills",
    "params": {}
  }'

# 6) Cloud-only skill read (no deviceId required)
curl -X POST "https://mcp.rtrvr.ai" \
  -H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_skill",
    "params": {
      "name": "general"
    }
  }'

YOUR NEXT RUN

Run the example on a real site.

Use Chrome for the page in front of you. Use Cloud when the run should continue on a schedule or across many pages.

Video Tutorials

Introduction

MCP Deep Dive

// 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" } ] } }

interface BrowserAgentApiRequest { /** * Canonical tool name, e.g. "planner" or "get_browser_tabs". * Only one of "tool" or "action" is required. */ tool?: string; /** * Optional alias of "tool". Use canonical snake_case tool names. */ action?: string; /** * Parameters for the tool. "params" and "parameters" are equivalent. * Prefer canonical snake_case parameter names. */ params?: Record<string, any>; parameters?: Record<string, any>; /** * Optional: route extension-backed tools to a specific Chrome profile / device. * Cloud-only knowledge base tools ignore this field. */ 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; }

{ "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" } }

# 1. Request a signed upload URL (no bytes in the request) curl -X POST "https://mcp.rtrvr.ai" \ -H "Authorization: Bearer rtrvr_xxx" \ -H "Content-Type: application/json" \ -d '{"tool": "upload_file", "params": {"name": "resume.pdf", "mimeType": "application/pdf"}}' # → { "mode": "signed_url", "uploadUrl": "https://storage.googleapis.com/…", "storageUrl": "…", "gcsUri": "gs://…" } # 2. Upload the raw bytes curl -X PUT -H "Content-Type: application/pdf" --upload-file ./resume.pdf "<uploadUrl>" # 3. Attach it to any agent tool curl -X POST "https://mcp.rtrvr.ai" \ -H "Authorization: Bearer rtrvr_xxx" \ -H "Content-Type: application/json" \ -d '{ "tool": "planner", "params": { "user_input": "Apply to this job with my resume", "tab_urls": ["https://example.com/careers/apply"], "file_urls": ["<storageUrl>"] } }'

{ "tool": "agent", "params": { "user_input": "Summarize the attached report", "files": [ { "displayName": "report.pdf", "uri": "<storageUrl>", "mimeType": "application/pdf" } ] } }

// 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://rtrvr.ai/shared/Tasks/userId/taskId/token" } }

// 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_on_tab({ 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_from_tab({ 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_and_extract_from_tab({ 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[]; }); // Cloud-only skill tools (no device_id required) list_skills({}); get_skill({ name: string; }}); // Utility: upload a local file to rtrvr storage (free, no device_id required) upload_file({ name?: string; // filename incl. extension; required unless url given mimeType?: string; // inferred from extension if omitted data?: string; // base64 content (small files) url?: string; // OR: public URL to import // neither data nor url → returns a signed PUT uploadUrl (15 min) // → { storageUrl, gcsUri } to pass via file_urls or files[] }); // User functions (defined in Cloud and executed in the browser sandbox) user_function({ functionName: string; // your custom parameters... });

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; inlineOutputMaxBytes?: number; outputTooLarge?: boolean; responseRef?: StorageReference; }; 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" }

# 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"], "options": { "ui": { "emitEvents": true } } }, "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"] } }' # 5) Cloud-only skills listing (no deviceId required) curl -X POST "https://mcp.rtrvr.ai" \ -H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "tool": "list_skills", "params": {} }' # 6) Cloud-only skill read (no deviceId required) curl -X POST "https://mcp.rtrvr.ai" \ -H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "tool": "get_skill", "params": { "name": "general" } }'

Video Tutorials

Browser as API/MCP Playground

Conceptual Overview

Authentication: OAuth & API Keys

Device Routing & Multi-Device Support

Device selection rules:

Finding your deviceId:

Endpoint & Request Schema

Top-level fields

Available Tools & Aliases

Free tools (no credits)

Credit-based tools

Cloud tools (no extension required)

Utility & user-defined tools

Tool name aliases

Parameter aliases

File & Image Inputs

Uploading local files: upload_file

Replay Workflow Tool

Parameters

Tool Parameters (TypeScript Sketch)

Response Format & Credits

Security & Configuration

Debugging & Troubleshooting

Getting Started

Code Examples

Run the example on a real site.

Video Tutorials

Browser as API/MCP Playground

Conceptual Overview

Authentication: OAuth & API Keys

Device Routing & Multi-Device Support

Device selection rules:

Finding your deviceId:

Endpoint & Request Schema

Top-level fields

Available Tools & Aliases

Free tools (no credits)

Credit-based tools

Cloud tools (no extension required)

Utility & user-defined tools

Tool name aliases

Parameter aliases

File & Image Inputs

Uploading local files: upload_file

Replay Workflow Tool

Parameters

Tool Parameters (TypeScript Sketch)

Response Format & Credits

Security & Configuration

Debugging & Troubleshooting

Getting Started

Code Examples

Run the example on a real site.

Uploading local files: `upload_file`

Uploading local files: `upload_file`