MCP server | Scrappy Docs

Connect to the hosted server

The server is at POST https://scrappy.gg/api/mcpand speaks MCP's Streamable HTTP transport. Authenticate with a Scrappy API key in the Authorization header. Every tool call runs as the user who owns the key.

Most MCP clients take a JSON entry with a URL and headers. Field names vary a little between clients, so check yours:

{
  "mcpServers": {
    "scrappy": {
      "type": "http",
      "url": "https://scrappy.gg/api/mcp",
      "headers": { "Authorization": "Bearer sk_..." }
    }
  }
}

In Claude Code the same thing is one command:

claude mcp add --transport http scrappy https://scrappy.gg/api/mcp \
  --header "Authorization: Bearer sk_..."

To check a key without a client, list the tools directly. The body and response are MCP JSON-RPC messages, not Scrappy's usual REST shape.

curl -X POST https://scrappy.gg/api/mcp \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

API keys and scopes

A key only reaches the tools its scopes allow. The cloud browser tools need browser:read to look and browser:write to act. Give an agent the narrowest set that covers its job. See Teams and API keys for creating keys.

Response	Meaning
`401 UNAUTHORIZED`	The Authorization header is missing, or the key is invalid or expired.
`429 RATE_LIMIT_EXCEEDED`	The key's rate limit was reached. Wait for the Retry-After header's number of seconds.
`405 METHOD_NOT_ALLOWED`	A method other than POST was used.

What the hosted server exposes

Toolset	Examples	What it is for
API-backed tools	`search_leads`, `create_source`, `create_job`, `get_credit_balance`	The platform itself: leads, sources, jobs, campaigns, matching, exports, webhooks and the rest of the REST API.
57 `browser_*` tools	`browser_create_session`, `browser_read_page`, `browser_click`, `browser_batch`	The cloud browser. Each tool maps to one browser API endpoint.
`send_chat_message`		A conversation with Scrappy's own AI agent.

Driving a browser

The browser_* tools cover the same ground as the cloud browser API: sessions, navigation, reading a page as an accessibility tree, clicking and typing by ref, batches, waits, screenshots, uploads and downloads, recording, dialogs and saved-login profiles. A typical agent run is:

browser_create_session returns a session id.
browser_navigate opens a page in it.
browser_read_page or browser_find returns elements with refs, and browser_click and browser_type act on those refs.
browser_release_session ends the session and stops the meter.

curl -X POST https://scrappy.gg/api/mcp \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "browser_create_session", "arguments": {} }
  }'

Sessions opened through MCP cost the same as any other: 5 credits to start and 1 per minute until released. Tell your agent to release sessions when it finishes. To let a person watch or take over, browser_viewer_token returns a short-lived viewer URL.

If one key drives browsers for many of your own users, see the X-Client-Ref header in Saved logins.

Talking to the Scrappy agent

send_chat_messagehands a request in plain language to Scrappy's built-in agent and returns when it has finished replying. Use it when you would sooner delegate a multi-step job than have your own agent work out the individual tool calls.

{
  "name": "send_chat_message",
  "arguments": {
    "message": "Find sources for independent bookshops in Oregon and tell me which look scrapeable.",
    "title": "Oregon bookshops"
  }
}

Field	Direction	Meaning
`message`	Argument, required	What to ask, up to 10,000 characters.
`conversationId`	Argument	Continue an existing conversation. Omit it to start a new one.
`title`	Argument	Title for a new conversation.
`conversationId`	Result	Pass it back on the next call to keep context.
`reply`	Result	The agent's full text answer.
`toolCalls`	Result	The tools the agent invoked, with their inputs.
`warnings`	Result	Any warnings the agent raised during the turn.

Chat is billed in credits like chat in the dashboard. See Chat agent for what the agent can do.

The stdio server

The same server also runs as a local process over stdio. It registers everything the hosted endpoint does, plus toolsets that hold a live browser inside the process and so cannot run over stateless HTTP. The main one is local_browser_*: 30 tools that drive a Playwright browser on your own machine.

The stdio server is started from the Scrappy source with tsx, so it suits local development and self-hosted setups. If you only need the platform and the cloud browser, use the hosted endpoint.

{
  "mcpServers": {
    "scrappy": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "env": {
        "SCRAPPY_API_KEY": "sk_...",
        "SCRAPPY_BASE_URL": "https://scrappy.gg"
      }
    }
  }
}

Variable	Purpose
`SCRAPPY_API_KEY`	The API key every tool call is made with. Required.
`SCRAPPY_BASE_URL`	Which Scrappy to talk to. Defaults to a local instance, so set it for scrappy.gg.
`SCRAPPY_PROJECT_ID`	Scope every request to one project.
`SCRAPPY_CLIENT_REF`	Send this value as X-Client-Ref on every browser request.
`SCRAPPY_TIMEOUT_MS`	Per-request timeout. Defaults to 10000.

Which one to use

Hosted HTTP for agents that run anywhere: a hosted assistant, a server-side agent, a desktop client. Nothing to install, and the browser runs in the cloud.
stdio when you are working from the source and want a browser on your own machine as well.