Browser as API/MCP (/mcp)

The rtrvr.ai Chrome Extension registers as a remote browser device and exposes a single public entrypoint at https://www.rtrvr.ai/mcp. 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.

Direct API calls use the same API keys as the rest of the platform. Get yours by signing into rtrvr.ai/cloud, or find it embedded in your MCP URL after installing the Chrome Extension.

Auth can be provided via:

• Authorization: Bearer YOUR_API_KEY
• X-API-Key: YOUR_API_KEY
• Query param: ?apiKey=YOUR_API_KEY

Authorization: Bearer rtrvr_your_api_key

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

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.

// List all your devices
curl -X POST "https://www.rtrvr.ai/mcp" \
  -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" }
    ]
  }
}

Device presence is tracked per user in Firestore with online flags and lastSeen timestamps.

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.

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

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.

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

Parameter aliases

Common parameters accept snake_case and camelCase:

• user_input ⇔ userInput
• tab_urls ⇔ tabUrls
• device_id ⇔ deviceId
• max_steps ⇔ maxSteps

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

act({
  user_input: string;
  tab_urls?: string[];
  schema?: {
    fields: {
      name: string;
      description: string;
      type: string;
      required?: boolean;
    }[];
  };
  tab_id?: number;
  device_id?: 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;
});

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;
    new_tab_title?: string;
  };
  tab_id?: number;
  device_id?: 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.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.

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.

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://www.rtrvr.ai/mcp 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.

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://www.rtrvr.ai/mcp" \
  -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://www.rtrvr.ai/mcp" \
  -H "X-API-Key: rtrvr_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_browser_tabs",
    "params": {
      "filter": "all"
    }
  }'

# 3) Using action/parameters aliases (camelCase)
curl -X POST "https://www.rtrvr.ai/mcp" \
  -H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "getBrowserTabs",
    "parameters": {
      "filter": "active"
    },
    "device_id": "dj75mmaTWP0"
  }'