rtrvr.ai logo
rtrvr.ai
PricingBlogDashboard

Core Agent

Getting StartedWeb AgentSheets Workflows

Building Blocks

Recordings & GroundingTool CallingKnowledge Base (RAG)

Platform Access

CLI & SDKAPI OverviewAgent APIScrape APIBrowser as API/MCP

Automation

ShortcutsTriggersWebhooksSchedules

Account & Security

Cookie SyncPermissions & Privacy
DocsBrowser as API/MCP

Browser as API/MCP /mcp

Turn your logged-in Chrome profile into an agentic API endpoint, and access cloud-only knowledge base tools from the same MCP surface.

Most /mcp tools control your local Chrome via the extension as a remote MCP server. Cloud-only knowledge base tools like knowledge_base_query run without a device session.

Try PlaygroundInstall Extension

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.

Extension + Cloud

Mix device-backed browser tools with cloud-only knowledge base tools on one endpoint.

Chrome only (for now):Extension-as-remote-MCP-server currently supports Chrome. Additional browsers are planned.

Quick setup: Configure MCP 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

Get from rtrvr.ai/cloud or your Chrome Extension

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

Execute complex multi-step tasks from natural language

URLs to open before starting

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.
  • knowledge_base_list_stores – list your private knowledge base stores and their metadata.
  • knowledge_base_query – query a private knowledge base by store_id.
  • knowledge_base_batch_index – batch index scraped pages into a private knowledge base.
  • 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.
  • list_recordings – list all user recordings (returns metadata: ID, name, timestamp).
  • list_file_search_stores – list all file search / knowledge base stores and metadata.
  • 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.

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

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://www.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_tabs""reuse_tabs""current_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://www.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 knowledge base tools (no device_id required)
knowledge_base_list_stores({});

knowledge_base_query({
  store_id: string;
  query: string;
  conversation_context?: string;
  model?: string;
});

knowledge_base_batch_index({
  store_id: string;
  tab_ids: number[];
  web_page_map: Record<number, {
    url: string;
    title: string;
    content_type: string;
    content?: string;
    tree?: string;
    element_link_record?: Record<number, string>;
    acc_tree_id?: string;
  }>;
  results?: { tab_id: number; success: boolean; url?: string; error?: string }[];
  auth_token?: 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:

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.
  1. Install the rtrvr.ai Chrome Extension.
  2. Open the MCP / Remote Browser section in the extension.
  3. Copy the generated MCP URL — your API key and deviceId are already embedded. Alternatively, get your API key from rtrvr.ai/cloud.
  4. For MCP clients: paste the URL directly into your MCP-enabled application (e.g. Claude).
  5. For direct HTTP: call https://mcp.rtrvr.ai with your API key in headers. Optionally pass deviceId to target a specific device.
  6. Multi-device setup: Install the extension on multiple Chrome profiles. Each gets its own deviceId. Target specific devices or leave blank for auto-selection.
  7. 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 knowledge base query (no deviceId required)
curl -X POST "https://mcp.rtrvr.ai" \
  -H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "knowledge_base_query",
    "params": {
      "store_id": "hn-w0wa7ckmk7ch",
      "query": "Summarize what this knowledge base says about pricing."
    }
  }'

Ready to automate?

Join teams using rtrvr.ai to build playful, powerful web automation workflows.