MCP server
Connect Claude Code, Claude Desktop, Cursor, Codex, VS Code or any MCP client to the catalog. Ten tools to search, inspect, quote and run APIs, with the same prices, routing and errors as the REST API.
Last updated
On this page
The Model Context Protocol server exposes the catalog as tools, so an AI agent can find an API, read its contract, check the price and run it without custom code.
| Property | Value |
|---|---|
| URL | https://api.primaryapi.com/mcp |
| Transport | Streamable HTTP, stateless: every request is a POST and the answer is plain JSON (no session, no server-sent stream). GET and DELETE answer 405. |
| Authentication | Authorization: Bearer pa_live_… (or X-API-Key) set in your MCP client. Discovery tools work without a key. |
| Billing | Exactly the REST rules, in credits: you pay only for answers, never more than the most the call can cost (its quote's maxCredits). |
Tools
| Tool | What it does | Arguments | Key access |
|---|---|---|---|
search_apis | Find APIs by keyword or use case ("tiktok comments", "verify an email"). | query, category?, limit? (1–50, default 10) | none |
list_apis | Browse by category or platform, one page at a time. | category?, platform?, limit? (1–100, default 25), cursor? | none |
get_api | Full contract of one SKU: input and output schemas, examples, notes, pricing and measured 30-day health. Unknown SKUs get suggestions. | sku | none |
quote_api | Validate an input and return the price in credits without running it. | sku, input? | run or full |
run_api | Run a SKU and return its envelope plus a one-line summary. Spends credits. | sku, input?, preferLatencyUnderMs?, maxCredits?, fields?, max_items?, summary?, idempotencyKey? | run or full |
get_request | Status of an earlier call, with its result when finished. | requestId | any |
read_result | Re-read a stored result for free, optionally trimmed. | requestId, fields?, max_items? | any |
get_balance | The workspace's credits: credits (spendable), paidCredits, promoCredits, includedCredits, promoExpiresAt, whether keys are paused, and where to buy credits. | none | view or full |
report_bug | Report wrong data, a schema mismatch or an error that looks like our fault. | message, requestId?, sku? | any |
send_feedback | Product feedback, or ask for a missing API (kind: "api_request"). | message, kind? (feedback, api_request, bug) | any |
Arguments are strict: the SKU's own fields go inside input ({"sku": "email.verify", "input": {"email": "[email protected]"}}), not next to sku. fields is a list of top-level output keys, max_items a number, and the routing arguments (maxCredits, preferLatencyUnderMs) behave exactly as in Routing and failover. search_apis, list_apis, get_api, quote_api, get_request, read_result and get_balance are marked read-only; run_api is marked as spending credits.
Errors come back as tool results with isError: true, carrying the same code as the REST API and a sentence about what to do next. A missing or wrong key on a tool that needs one is reported this way too, never as an HTTP failure.
Connect your client
Use a key with run access and a spend limit for agents. Keep the key in an environment variable or your client's secret prompt, never in a file you commit.
Add the server once for all your projects:
claude mcp add --transport http --scope user primaryapi https://api.primaryapi.com/mcp \
--header "Authorization: Bearer $PRIMARYAPI_API_KEY"Or share it with a project in .mcp.json, where Claude Code expands environment variables, so the key stays out of the file:
{
"mcpServers": {
"primaryapi": {
"type": "http",
"url": "https://api.primaryapi.com/mcp",
"headers": { "Authorization": "Bearer ${PRIMARYAPI_API_KEY}" }
}
}
}Check it with claude mcp list, or /mcp inside a session.
Claude Desktop starts local MCP servers from claude_desktop_config.json (Settings → Developer → Edit Config). Bridge to the remote server with the open-source mcp-remote package (needs Node.js):
{
"mcpServers": {
"primaryapi": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://api.primaryapi.com/mcp", "--header", "Authorization:${PRIMARYAPI_AUTH}"],
"env": { "PRIMARYAPI_AUTH": "Bearer pa_live_…" }
}
}
}Restart Claude Desktop afterwards. Writing the header as Authorization:${PRIMARYAPI_AUTH}, without a space, avoids argument-splitting problems on some platforms.
Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor fills in ${env:…} from your environment:
{
"mcpServers": {
"primaryapi": {
"url": "https://api.primaryapi.com/mcp",
"headers": { "Authorization": "Bearer ${env:PRIMARYAPI_API_KEY}" }
}
}
}Add the server to ~/.codex/config.toml. Codex reads the bearer token from the environment variable you name:
[mcp_servers.primaryapi]
url = "https://api.primaryapi.com/mcp"
bearer_token_env_var = "PRIMARYAPI_API_KEY"In .vscode/mcp.json, let VS Code prompt for the key once and store it securely:
{
"inputs": [
{ "type": "promptString", "id": "primaryapi-key", "description": "PrimaryAPI API key", "password": true }
],
"servers": {
"primaryapi": {
"type": "http",
"url": "https://api.primaryapi.com/mcp",
"headers": { "Authorization": "Bearer ${input:primaryapi-key}" }
}
}
}Any other client that supports Streamable HTTP with custom headers works the same way: point it at https://api.primaryapi.com/mcp and send the Authorization header. Without a key, only the three discovery tools work, limited to 120 requests per minute per IP address.
How an agent should use it
search_apiswith what you need, for example{"query": "google maps reviews"}. Free.get_apiwith the chosen SKU before its first run. ReadinputSchema: field names are exact and unknown fields are rejected.- Optional:
quote_apito see the price for this exact input. Free. run_apiwithskuandinput. Ask only for what you need withfieldsandmax_items.- If the result says the call is still running, call
get_requestwith therequestIdafter the suggested delay. Do not callrun_apiagain to wait: that starts, and bills, a second job. - Need other fields from the same result later?
read_resultre-reads it for free.
{
"sku": "reddit.search",
"input": { "query": "best mechanical keyboard", "limit": 10 },
"fields": ["title", "score", "permalink"],
"max_items": 5,
"idempotencyKey": "kb-search-2026-10-30-01"
}fields, max_items and summary shorten what comes back into the model's context; they never reduce the bill. On a per-result API, lower the API's own limit to pay for fewer results. Pass an idempotencyKey whenever a call might be repeated, for example after a client timeout. A result that is too large to show inline is replaced by an outline, with a pointer to read_result.
Debugging with raw HTTP
The server speaks JSON-RPC 2.0 over plain POST. Listing the tools needs no key:
curl -sS -X POST "https://api.primaryapi.com/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Every response carries an X-Request-Id header; include it when you report a problem.
Limits and safety
- Keyed MCP traffic shares the rate limits of the REST API: 200 requests per 10 seconds per key and 1,000 per minute per account.
- The server never asks a model to reveal its key, and tool results never contain it. Never paste a key into a prompt: configure it in the client as shown above.
- Agents that should only browse can connect without a key. Agents that run calls should use a dedicated
runkey with a spend limit in credits, so a runaway loop has a known ceiling.