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.

One tool surface

Use the same tool names across agents: screenshots, batch capture, scripts, and automation.

Frictionless auth

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

Consistent outputs

Base64 images, console logs, and artifacts come back in the MCP response.

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

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.

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)

{
  "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)

{
  "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)

{
  "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.