Extension as Remote MCP Server

The rtrvr.ai Chrome Extension can act as an MCP (Model Context Protocol) server and as a direct HTTP automation endpoint. It exposes a single public entrypoint at https://www.rtrvr.ai/mcp. The extension generates a full MCP URL for you (including apiKey and optional deviceId) that you can paste into an MCP client or call directly from your backend.

Use Cases

• Research products on Claude and ask to 'use rtrvr tool buy' to make purchases
• Build a Slack bot that can file Jira tickets or update CRM records through the browser
• Create a platform for generating sales posts that automatically posts to Craigslist and Facebook Marketplace
• Develop custom automation workflows that require browser interaction
• Enable your users to connect their browsers for automated tasks on their behalf

Available Tools

The MCP server exposes both free and credit-based tools for browser automation:

Free Tools (No Credits Required)

• get_browser_tabs - Get information about currently open browser tabs with filtering options
• get_page_data - Retrieve webpages as accessibility tree representations for specified tab IDs
• take_page_action - Execute system tool actions on web pages (click, type, scroll, etc.)
• execute_javascript - Execute JavaScript code securely within the browser sandbox (disabled by default)

Credit-Based Tools

• planner - Execute complex, end-to-end tasks from a single prompt with multi-step planning
• act - Intelligently interact with web pages to accomplish specific tasks
• extract - Extract structured data from web pages into clean JSON or Google Sheets
• crawl - Crawl multiple pages of a website to compile comprehensive datasets

Utility Tools

• list_devices - List all available devices connected to your account
• get_current_credits - Check your current credit balance and usage
• user_function - Execute custom user-defined tools in the browser sandbox

Direct API Access (HTTP)

The same /mcp endpoint can be used as a REST-style API. In this mode you send a JSON body describing the tool/action to run plus parameters, and the server turns that into a task for one of your online extension devices.

• Endpoint: https://www.rtrvr.ai/mcp (the extension forwards its MCP URL here under the hood)
• tool or action – name of the tool to execute (e.g. 'get_browser_tabs', 'planner', or camelCase aliases like 'getBrowserTabs')
• params or parameters – JSON object with tool-specific parameters (snake_case and camelCase variants are both accepted)
• deviceId or device_id (optional) – target a specific Chrome profile / extension device; if omitted, the most recently active device is used
• timeout (optional) – override the default 5 minute max execution time per request
• async and webhookUrl (optional) – reserved for future async execution modes

Endpoint & Authentication

Direct API calls use the same API keys as the rest of the rtrvr.ai platform. Authentication can be provided in any of the following ways:

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

Tool Name Aliases

The Direct API handler is lenient about tool naming. It normalizes several camelCase and snake_case variants to the same underlying tool:

• get_browser_tabs or getBrowserTabs
• get_page_data or getPageData
• take_page_action or takePageAction
• get_current_credits or getCurrentCredits
• list_devices or listDevices
• planner (same name in both styles)
• act or actOnTab
• extract or extractFromTab
• crawl or crawlAndExtract
• execute_javascript, executeJavaScript, or executeJs

Parameter Aliases

Common parameter names also support both snake_case and camelCase, and are normalized internally:

• user_input or userInput
• tab_urls or tabUrls
• tab_id or tabId
• tab_ids or tabIds
• max_steps or maxSteps
• max_pages or maxPages
• follow_links or followLinks
• link_pattern or linkPattern
• output_destination or outputDestination

Device Routing & Multi-Profile Support

Each Chrome profile (or Chromium-based browser profile) you install the extension into registers as a separate deviceId. The Direct API handler uses device targeting rules to decide which browser to control:

• Pass deviceId or device_id in the query string (e.g. ?deviceId=dj75mmaTWP0) or in the request body to target a specific device.
• If deviceId is omitted, the server automatically selects the most recently active online extension device for that user (most recent lastSeen).
• You can install the extension on multiple browser profiles and orchestrate them independently by calling /mcp with different deviceId values.
• Local tools like get_current_credits / getCurrentCredits and list_devices / listDevices do not require an online deviceId and can be called even if the extension is offline.

API Examples

# Recommended: API key via header, explicit deviceId from the extension URL
curl -X POST "https://www.rtrvr.ai/mcp?deviceId=dj75mmaTWP0" \
  -H "X-API-Key: rtrvr_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_browser_tabs",
    "params": {
      "filter": "all"
    }
  }'

# Equivalent using alias fields (action/parameters + Authorization header)
curl -X POST "https://www.rtrvr.ai/mcp" \
  -H "Authorization: Bearer rtrvr_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "getBrowserTabs",
    "parameters": {
      "filter": "active"
    },
    "deviceId": "dj75mmaTWP0"
  }'

Response Format & Credits

Direct API responses use a consistent envelope with success metadata, tool-specific data, and execution metadata. For credit-based tools, credit usage is also surfaced via headers.

{
  "success": true,
  "data": {
    "success": true,
    "executionTime": 1234,
    "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"
}

• For credit tools (planner, act, extract, crawl), X-Credits-Used and X-Credits-Remaining headers are also set on the HTTP response.
• The data field is tool-specific and already formatted for direct consumption (e.g. tabs list, extracted data, crawl stats).
• The metadata.requestId field is useful for correlating logs between your system and rtrvr.ai.

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: object
  }],
  device_id?: string
})

execute_javascript({
  code: string,
  timeout?: number,
  context?: object,
  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?: object,
  tab_id?: number,
  device_id?: string
})

extract({
  user_input: string,
  tab_urls?: string[],
  schema?: object,
  output_destination?: {
    type: "json" | "google_sheet",
    new_sheet_title?: string,
    existing_sheet_id?: string
  },
  tab_id?: number,
  device_id?: string
})

crawl({
  user_input: string,
  tab_urls?: string[],
  schema?: object,
  max_pages?: number,
  follow_links?: boolean,
  link_pattern?: string,
  output_destination?: object,
  tab_id?: number,
  device_id?: string
})

Security & Configuration

Remote tool execution provides fine-grained control over which tools are accessible:

• Disable remote tool execution entirely from the Chrome Extension settings
• Enable/disable individual tools at the tool level
• Free tools and credit tools can be managed separately
• All settings sync between the Chrome Extension and cloud platform

Debugging & Troubleshooting

If /mcp requests fail with 'No online devices found', 4xx/5xx errors, or tools not executing as expected, work through the following steps:

• Open and close the rtrvr.ai Chrome extension popup to refresh its connection and presence status.
• Rotate your API key via the Chrome extension settings dropdown. This regenerates the key and re-syncs backend state.
• Sign out and then sign back into the Chrome extension. This completely resets device registration and presence logic.
• As a last resort, uninstall and reinstall the Chrome extension to force a clean device registration.
• Call the list_devices tool (or use /mcp with tool=listDevices) to see which deviceIds are online and verify you are targeting a valid device.
• Send a GET request to https://www.rtrvr.ai/mcp to confirm the endpoint is reachable and returning API metadata.

Getting Started

• Install the rtrvr.ai Chrome Extension
• Navigate to the MCP Server section in the extension
• Copy the generated MCP URL (it includes apiKey and, optionally, deviceId)
• For MCP clients: paste the URL into your MCP-enabled application
• For direct API usage: call https://www.rtrvr.ai/mcp with your API key in headers and optionally reuse the deviceId from the generated URL
• Configure which tools to enable/disable as needed in the extension settings
• Start using browser automation from your MCP client or HTTP client