MCP server

extractr speaks the Model Context Protocol, so any MCP-capable agent — Claude Code, Claude Desktop, Cursor, or your own client built on an MCP SDK — can call every endpoint in the catalog as a tool.

There is nothing extra to enable and no separate billing. Tools are generated from the same provider definitions that produce this documentation, authenticate with the same API key, and cost the same credits per successful call.

Endpoint

POST https://api.extractr.dev/mcp

Transport is streamable HTTP, stateless: no session id, no SSE stream to keep open. Authenticate with your API key on the MCP endpoint itself, exactly as you would on a data endpoint:

X-API-Key: ext_live_...

Authorization: Bearer ext_live_... works too, if your client only supports that.

Connect a client

claude mcp add --transport http extractr https://api.extractr.dev/mcp \
  --header "X-API-Key: ext_live_YOUR_KEY"

Create a key in the dashboard first. If you plan to hand a key to an agent, consider scoping it to just the providers it needs — an agent that only reads event listings has no reason to hold a key that can reach everything.

Tool naming

Every endpoint becomes one tool named <provider>_<endpoint>, mirroring the HTTP path:

Each tool description states its credit price, so a well-behaved agent knows the cost before it calls. Arguments match the endpoint's query or body parameters, and are validated identically.

Calling a tool directly

If you are writing your own client, the JSON-RPC is plain:

curl -X POST https://api.extractr.dev/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ext_live_YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "instagram_get_profile",
      "arguments": { "username": "nasa" }
    }
  }'

The result carries the response twice — as pretty-printed text in content, for models, and as structuredContent, for code — plus what the call cost:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{ \"username\": \"nasa\", ... }" }],
    "structuredContent": { "username": "nasa", "followers": 98200000 },
    "isError": false,
    "_meta": {
      "extractr/creditsCharged": 2,
      "extractr/creditsBalance": 4871
    }
  }
}

tools/list needs no API key — the catalog is public, so an agent can discover what exists before it is configured with credentials. tools/call does.

Errors and credits

Credit rules are identical to the HTTP API: you are charged only for successful calls. A tool call that fails returns isError: true with the reason in content, and nothing is deducted:

Failures come back as tool errors rather than transport errors on purpose: the agent can read what went wrong and decide whether to retry, narrow its query, or tell you to top up.

See Credits for pricing and Errors for the full code list.