Riddle MCP

One MCP client, two modes. Use the hosted gateway with your login token or run locally with an API key. Same tools, same outputs—different auth and deployment tradeoffs.

What MCP Gives You

MCP exposes Riddle's browser automation tools to AI agents in a standard, tool-call format. The client handles screenshots, automation, and artifacts without your agent managing Chrome directly.

11 tools, one surface

Screenshots, Playwright scripts, scraping, crawling, visual diffs, and container previews—all as MCP tool calls.

Frictionless auth

Hosted mode uses your Riddle login token. Local mode uses API keys. Both map to your account.

Auth on every tool

Pass cookies, localStorage, headers, or enable stealth mode on any tool to handle logged-in pages and bot detection.

Built for agents

Works cleanly with Claude, Cursor, and other MCP-aware environments.

Two Modes, Same Tools

Pick the mode that matches your security model and onboarding flow.

Feature	Hosted MCP	Local MCP
Auth	Login token (JWT)	API key
Setup	Paste token, start client	Store key, start client
Best for	Teams, quick onboarding	Services, CI, long-lived jobs
Billing	Account-bound via login	Key-bound via owner

Option 1: Hosted MCP (Gateway)

Your MCP client calls the Riddle gateway at api.riddledc.com. Auth uses a short-lived login token (JWT). Billing and access are tied to the user account.

No API key creation required.
Great for teams and shared environments.
Centralized billing and permissions.

Option 2: Local MCP (Direct)

The MCP client calls the Riddle API directly with your API key. This is the simplest path if you already manage keys in secrets.

Stable credentials that do not expire.
Works anywhere you can store a secret.
Ideal for CI and backend services.

Hosted MCP Setup

Hosted MCP supports either a login token (JWT) or an API key. Use a JWT for quick tests, or an API key for long-lived sessions.

Install from npm

npm install @riddledc/riddle-mcp

MCP Client Configuration (Hosted, JWT)

// Copy this into your MCP client config (e.g. claude_desktop_config.json)
{
  "mcpServers": {
    "riddle": {
      "command": "npx",
      "args": ["riddle-mcp"],
      "env": {
        "RIDDLE_MCP_GATEWAY_URL": "https://api.riddledc.com",
        "RIDDLE_AUTH_TOKEN": "your_login_token_here"
      }
    }
  }
}

MCP Client Configuration (Hosted, API Key)

// Copy this into your MCP client config
{
  "mcpServers": {
    "riddle": {
      "command": "npx",
      "args": ["riddle-mcp"],
      "env": {
        "RIDDLE_MCP_GATEWAY_URL": "https://api.riddledc.com",
        "RIDDLE_API_KEY": "rdc_live_your_key_here"
      }
    }
  }
}

You can confirm the gateway is live without auth by listing tools:

List Hosted MCP Tools

curl -sS https://api.riddledc.com/v1/mcp/tools | jq .

Get a Login Token

Hosted MCP can use the same short-lived token as the Riddle web app. Tokens expire, so refresh if you see auth errors.

Log in at your dashboard.
Open DevTools and go to the Network tab.
Click any request to api.riddledc.com and copy the Authorization header.
Paste the token value into RIDDLE_AUTH_TOKEN for your MCP config.

For always-on sessions, use an API key in hosted mode instead.

Need a plain-text doc for your agent? Use https://riddledc.com/mcp/markdown.md.

Repo: github.com/riddledc/integrations · NPM: @riddledc/riddle-mcp

Local MCP Setup

Use an API key from your Riddle dashboard. This key never expires and is best for long-running services.

MCP Client Configuration (Local)

// Copy this into your MCP client config
{
  "mcpServers": {
    "riddle": {
      "command": "npx",
      "args": ["riddle-mcp"],
      "env": {
        "RIDDLE_API_KEY": "rdc_live_your_key_here"
      }
    }
  }
}

Auth and Billing Notes

Hosted MCP accepts a login token (JWT) or an API key and bills to your account.
Local MCP uses your API key and bills to that key's owner.

Never share tokens or API keys—anyone with them can run jobs on your account. Do not paste tokens into issues or public threads. Store them in env vars or secret managers.

Need more API details? See the API docs.

Tools

11 tools organized by purpose. Every tool accepts optional auth parameters: cookies, localStorage, headers, and stealth.

Core

Tool	Description
`riddle_screenshot`	Screenshot one or many URLs. Pass `url` for a single shot or `urls` for a batch. Device presets: desktop, ipad, iphone.
`riddle_script`	Run Playwright code with full access to `page`, `saveScreenshot()`, `saveJson()`, `scrape()`, `map()`, `crawl()`. Returns screenshots, console logs, and network HAR.
`riddle_steps`	Declarative JSON workflow—an array of steps like `goto`, `click`, `fill`, `screenshot`, `scrape`. Simpler alternative to script for straightforward flows.
`riddle_get_job`	Check status and artifacts of a previously submitted job.

Data Extraction

Tool	Description
`riddle_scrape`	Extract structured content from a URL: title, description, markdown, links, headings, word count.
`riddle_map`	Discover all URLs on a website. Returns an array of links for building sitemaps or selecting pages to process.
`riddle_crawl`	Crawl a site and extract content into a dataset. Supports JSONL, JSON, CSV, or ZIP output.

Visual Testing

Tool	Description
`riddle_visual_diff`	Screenshot two URLs and compute a pixel-level diff. Returns change percentage and before/after/diff images.

Preview & Deploy

Tool	Description
`riddle_preview`	Deploy a directory of static files to an ephemeral preview URL (24-hour expiry).
`riddle_server_preview`	Run a server-side app in a stock Docker container (node:20-slim, python:3.12-slim, etc.) and screenshot it.
`riddle_build_preview`	Build a custom Dockerfile, run the container, and screenshot. Supports image caching and security audits.

Give Your Agent a Browser

Create an account and connect via MCP in minutes.

Get Started Free View API Docs