MCP server

The ScraperCompany MCP server exposes the API's hotel, flight and vacation-rental data as tools an AI agent can call. Any Model Context Protocol client that can send a header works: Claude Code, Cursor, and Claude Desktop through a small bridge.

Overview#

Connect a client#

Claude Code#

Add the server once; the key is read from your environment when you run the command.

claude mcp add --transport http scrapercompany https://api.scrapercompany.com/mcp \
  --header "x-api-key: $SCRAPERCOMPANY_API_KEY"

Cursor and other header-capable clients#

In ~/.cursor/mcp.json (or your client's equivalent config), point a server at the URL and pass the key as a header:

{
  "mcpServers": {
    "scrapercompany": {
      "url": "https://api.scrapercompany.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop and stdio-only clients#

Clients that only launch local (stdio) servers connect through the mcp-remote bridge. In claude_desktop_config.json:

{
  "mcpServers": {
    "scrapercompany": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.scrapercompany.com/mcp",
               "--header", "x-api-key:${SCRAPERCOMPANY_API_KEY}"],
      "env": { "SCRAPERCOMPANY_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Check the connection#

Listing the tools is free and needs no session. A plain HTTP client gets the same JSON-RPC reply an MCP client does:

curl -X POST "https://api.scrapercompany.com/mcp" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

A 401 means the key is missing or wrong. Treat the key like a password: keep it in the client's secret store or an environment variable rather than in a config file you share.

Tools#

Each tool wraps one REST endpoint and takes that endpoint's request fields (most of them), validated the same way. Options that change a call's price, such as basis and verify_sources on the calendar, stay REST-only. Tool descriptions carry the cost too, so the agent sees what a call will charge before making it.

A typical hotel conversation: resolve_hotel with a name and city returns a token; hotel_rate_calendar with that token and days: 60 returns 60 nightly prices; then hotel_offers for the cheapest night returns each booking site's price. For flights: flight_search with a return date, flight_next_leg with the chosen outbound's departure_token, then flight_booking_options with the return's booking_token.

Results#

A successful call returns the route's JSON twice: in structuredContent, and as text in content[0].text for clients that only read text. Per-row provenance blocks are left out to save the agent's context; call the REST endpoint when you need them for an audit.

_meta on every result gives the HTTP status of the wrapped call, the request id and, when the call was metered, the credits charged and remaining (as strings, copied from the credit headers):

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [{ "type": "text", "text": "{\"token\":\"ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ\",\"requested_days\":60,\"coverage\":0.95,\"rates\":[...]}" }],
    "structuredContent": { "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ", "requested_days": 60, "coverage": 0.95, "rates": ["..."] },
    "isError": false,
    "_meta": { "http_status": 200, "credits_charged": "5", "credits_remaining": "995", "request_id": "req_..." }
  }
}

Errors#

Errors come back at two levels.

Tool errors are results with isError: true, so the model can read them and fix its next call. The text is {"error": ..., "status": ...} with the wrapped route's detail and status. They cover:

• a missing or unknown argument (the message lists the allowed ones);
• anything the route rejects, such as a date in the past (422) or a property Google no longer lists (404);
• a source that failed or blocked the request (502) or changed its contract (503);
• no credits left (402, once enforcement is on) or the key's rate limit (429).

An unexpected server error is also a tool error, with a generic message and the request_id to quote to support. Tool errors are not charged.

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [{ "type": "text", "text": "{\"error\": \"check_in is in the past\", \"status\": 422}" }],
    "isError": true,
    "_meta": { "http_status": 422, "request_id": "req_..." }
  }
}

Protocol errors are JSON-RPC errors, for problems with the message itself:

A missing or invalid key is an HTTP 401 before any JSON-RPC handling.

Limits#

• One JSON-RPC message per POST under 2025-06-18, which removed batching. 2025-03-26 clients may batch up to 10 messages.
• Request bodies over 256 KB get 413.
• Tool calls count against your key's rate limit through the route they wrap. Every other message (initialize, tools/list, ping), and any tool call rejected before it reaches a route, counts once.
• A browser Origin must be scrapercompany.com (or a subdomain) or localhost; anything else gets 403, which guards against DNS rebinding. Agents and CLIs send no Origin.
• GET and DELETE on /mcp return 405: the server never opens a stream or a session.