rtrvr.ai logo
rtrvr.ai
Blog
Book Demo
Pricing
API Docs

Getting Started

  • Introduction
  • Quick Start

Capabilities

  • Web Agent
  • Sheets Workflows

API

  • API Overview
  • Agent API
  • Scrape API
  • Browser as API/MCP
    • Playground
    • Use Cases
    • Authentication
    • Endpoint & Request
    • Available Tools
    • Tool Parameters
    • Device Routing
    • Response & Credits
    • Security & Config
    • Debugging
    • Getting Started
    • Code Examples

Advanced

  • Tool Calling
  • Recordings
  • Webhooks
  • Schedules
DocsBrowser as API/MCP

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.

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.

Multi-Device

Install on multiple Chrome profiles and target specific devices by ID.

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

Video Tutorials

Introduction

MCP Deep Dive

Browser as API/MCP Playground

POST/mcp

Control your logged-in Chrome via HTTP or MCP protocol

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. 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_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 device to target, and which parameters to pass through.

BrowserAgentApiRequest (conceptual)
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

toolstring

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

actionstring

CamelCase alias, e.g. 'getBrowserTabs'. Normalized to the same underlying tool as 'get_browser_tabs'.

params / parametersobject

JSON object of tool-specific parameters. 'params' and 'parameters' are aliases; snake_case and camelCase keys are normalized.

deviceId / device_idstring

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

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 ⇔ getBrowserTabs
  • get_page_data ⇔ getPageData
  • take_page_action ⇔ takePageAction
  • execute_javascript ⇔ executeJavaScript ⇔ executeJs
  • list_devices ⇔ listDevices
  • replay_workflow ⇔ replayWorkflow

Parameter aliases

Common parameters accept snake_case and camelCase:

  • 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

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({
  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:

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;
  };
  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.

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"]
    },
    "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"]
    }
  }'

Ready to automate?

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

rtrvr.ai logo
rtrvr.ai

Retrieve, Research, Robotize the Web

By subscribing, you agree to receive marketing emails from rtrvr.ai. You can unsubscribe at any time.

Product

  • API & MCPNEW
  • Browser Extension
  • Cloud Platform
  • Templates
  • WhatsApp Bot
  • RoverSOON

Use Cases

  • Vibe Scraping
  • Lead Enrichment
  • Agentic Form Filling
  • Web Monitoring
  • Social Media
  • Job Applications
  • Data Migration
  • AI Web Context
  • Agentic Checkout

Compare

  • rtrvr vs Apify
  • rtrvr vs Bardeen
  • rtrvr vs Browserbase
  • rtrvr vs Browser Use
  • rtrvr vs Clay
  • rtrvr vs Claude
  • rtrvr vs Comet
  • rtrvr vs Firecrawl

Resources

  • Documentation
  • Blog
  • Changelog
  • Integrations
  • Pricing
  • Book Demo
  • Affiliate Program

Company

  • Team
  • Contact
  • GCP Partner
  • Privacy Policy
  • Terms of Service
  • Security Brief
support@rtrvr.ai

© 2026 rtrvr.ai. All rights reserved.

Made withfor the automation community