Rtrvr CLI MCP Server

rtrvr CLI + SDK

Browser automation for AI agents and humans. One CLI, three execution modes: cloud, local browser extension, or auto-routed.

• Cloud mode: run agents and scrape pages via rtrvr's cloud infrastructure
• Extension mode: route to your local browser extension for authenticated sessions
• Auto mode: smart routing with automatic fallback between cloud and extension

Install

# CLI (global)
npm install -g @rtrvr-ai/cli

# SDK (in your project)
npm install @rtrvr-ai/sdk

Quick Start

# Authenticate
rtrvr auth login

# Run an AI agent task
rtrvr run "Extract the top 10 products and prices" --url https://example.com

# Scrape a page
rtrvr scrape --url https://example.com

# Check what you can do
rtrvr capabilities

# Diagnose connectivity
rtrvr doctor

Authentication

Login methods

# Browser-based OAuth (recommended)
rtrvr auth login --oauth

# Direct API key
rtrvr auth login --api-key rtrvr_...

# Check auth status
rtrvr auth status

Token types

Token	Prefix	Access
API key	rtrvr_	Full cloud + CLI endpoints
OAuth token	mcp_at_	MCP endpoint only

Storage

Tokens are stored securely in your OS keychain (macOS Keychain / Linux secret-service) by default. Fallback to ~/.config/rtrvr/config.json if no secure store is available.

Environment variables override stored credentials:

export RTRVR_API_KEY=rtrvr_...
# or
export RTRVR_AUTH_TOKEN=rtrvr_...

Commands

rtrvr run / rtrvr agent

Run an AI agent task with smart routing.

rtrvr run "Find the latest pricing for each plan" --url https://example.com
rtrvr run --input-file ./task.txt --url https://example.com --target cloud
echo "Summarize this page" | rtrvr run --url https://example.com

Option	Description
<input>	Task description (positional)
--input <text>	Task description (flag)
--input-file <path>	Read task from file
--url <url>	Target URL(s)
--target <mode>	Routing: auto, cloud, extension
--cloud	Shortcut for --target cloud
--extension	Shortcut for --target extension
--device-id <id>	Target a specific browser extension device
--schema-file <path>	JSON schema for structured output
--json	Machine-readable JSON output
--no-stream	Hide live progress; async completion still follows the run

rtrvr scrape

Scrape URLs with cloud or extension routing.

rtrvr scrape --url https://example.com
rtrvr scrape --url https://example.com --target extension --device-id my-device

Option	Description
--url <url>	URL(s) to scrape
--target <mode>	Routing: auto, cloud, extension
--cloud	Shortcut for --target cloud
--extension	Shortcut for --target extension
--json	Machine-readable JSON output

rtrvr extension

Route directly to the browser extension planner.

rtrvr extension "Click the login button and fill the form" --url https://example.com

rtrvr devices

List online browser extension devices.

rtrvr devices list

rtrvr skills

Manage local reusable skill templates.

rtrvr skills templates              # List built-in templates
rtrvr skills install-template agent-web
rtrvr skills add ./my-skill.md      # Add from markdown
rtrvr skills list                   # Show installed skills
rtrvr skills apply my-skill "Find financing options" --url https://example.com

rtrvr mcp

Configure rtrvr as an MCP server for AI coding tools.

# Generate config for Claude Code
rtrvr mcp init --client claude

# Generate config for Cursor
rtrvr mcp init --client cursor

# Print the MCP endpoint URL
rtrvr mcp url

rtrvr config

Manage CLI configuration.

rtrvr config get                          # Show all config
rtrvr config set defaultTarget cloud      # Set default routing
rtrvr config set retryMaxAttempts 3       # Set retry policy

rtrvr profile / rtrvr capabilities

Check your identity and feature access.

rtrvr profile
rtrvr capabilities

rtrvr doctor

Run diagnostics to verify endpoints, auth, and connectivity.

rtrvr doctor

SDK Usage

import { createRtrvrClient } from '@rtrvr-ai/sdk';

const client = createRtrvrClient({
  apiKey: process.env.RTRVR_API_KEY!,
  defaultTarget: 'auto',
});

// Run an agent task
const result = await client.run({
  input: 'Find latest headline and author',
  urls: ['https://example.com'],
  target: 'auto',
});

console.log(result);

// Use specific tools
const extracted = await client.tools.extract({
  user_input: 'Extract all product names and prices',
  tab_urls: ['https://example.com/products'],
});

// Scrape
const scraped = await client.scrape.run({
  urls: ['https://example.com'],
});

// List devices
const devices = await client.devices.list();

// Check credits
const credits = await client.credits.get();

MCP Integration

rtrvr works as a native MCP server, giving AI coding tools (Claude Code, Cursor, etc.) direct access to browser automation.

# Auto-configure for Claude Code
rtrvr mcp init --client claude

# Auto-configure for Cursor
rtrvr mcp init --client cursor

This writes the MCP server config to the appropriate location so your AI tool can call rtrvr tools directly.

Available MCP tools

Tool	Description
planner	Multi-step browser automation planner
act_on_tab	Interact with a web page
extract_from_tab	Extract structured data from a page
crawl_and_extract_from_tab	Crawl and extract across multiple pages
cloud_agent	Run a cloud AI agent
cloud_scrape	Cloud-based page scraping
list_devices	List online extension devices
get_current_credits	Check credit balance

Routing Behavior

Target	run/agent	scrape
cloud	Cloud /agent API	Cloud /scrape API
extension	Extension planner via MCP	Extension scrape via MCP
auto (default)	Check extension availability, fallback to cloud	Same with fallback

The response includes routing metadata:

{
  "metadata": {
    "selectedMode": "cloud",
    "fallbackApplied": true,
    "fallbackReason": "no extension devices online"
  }
}

Progress Streaming

Long-running tasks stream real-time progress via SSE:

# Default: streaming enabled
rtrvr run "Complex multi-step task" --url https://example.com

# Disable streaming
rtrvr run "Quick task" --url https://example.com --no-stream

Events include planner_step, tool_start, tool_progress, tool_complete and credits_update, depending on the cloud and tools in use. JSON mode sends progress to stderr and the final result to stdout. Progress respects pipe backpressure instead of queuing event history.

Version 0.3.0 sends Prefer: respond-async. A server that returns HTTP 202 lets the client follow the run through the MCP events relay. Closed or dropped streams reconnect with since set to the last durable event sequence. The client reads the full final response after completion. If a progress frame exceeds its byte envelope, a typed repair resumes with status only and preserves the full final response. A server that returns HTTP 200 keeps its existing final-response behavior.

--no-stream hides progress. Async runs still follow events to completion. Ctrl-C requests cloud cancellation and waits up to 10 seconds for acknowledgement, then exits with code 130. The server's run limit governs execution. The default client wait covers 45 minutes; SDK callers can set an explicit timeoutMs for their wait.

Retries and errors

Every cloud agent and scrape call sends a trajectoryId and matching Idempotency-Key, including calls with --no-stream. Retries reuse that identity. For SDK retries across separate calls, keep the same trajectoryId and request body. The server must support the idempotency contract; older servers may reject a repeated id instead of replaying its result.

On HTTP 429 or 503, Retry-After can specify seconds or an HTTP date. The client waits at least that long if its deadline permits another attempt. Retry waits and event reconnects share the call's deadline.

Errors include the server's code, offending fields and requestId when supplied. SDK errors expose these as RtrvrError.code, .fields and .requestId. Retained partial results stay available in .details and CLI error output.

Configuration

Config is stored at ~/.config/rtrvr/config.json.

Key	Default	Description
defaultTarget	auto	Default routing mode
preferExtensionByDefault	false	Prefer extension in auto mode
retryMaxAttempts	1	Max retry attempts
retryBaseDelayMs	250	Base retry delay
retryMaxDelayMs	4000	Max retry delay
telemetryOptIn	false	Telemetry opt-in

Packages

Package	Description
@rtrvr-ai/cli	CLI binary (rtrvr command)
@rtrvr-ai/sdk	TypeScript SDK for programmatic use
@rtrvr-ai/core	Core API client, types, and transport

Development

git clone https://github.com/rtrvr-ai/rtrvr-cli.git
cd rtrvr-cli
pnpm install
pnpm build
node packages/cli/dist/index.js --help

License

Apache-2.0