# 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.

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": "person@example.com"}}`), 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](/docs/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.

**Claude Code:**

Add the server once for all your projects:

```bash
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:

```json title=".mcp.json"
{
  "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:**

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):

```json title="claude_desktop_config.json"
{
  "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.

**Cursor:**

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project). Cursor fills in `${env:…}` from your environment:

```json title="mcp.json"
{
  "mcpServers": {
    "primaryapi": {
      "url": "https://api.primaryapi.com/mcp",
      "headers": { "Authorization": "Bearer ${env:PRIMARYAPI_API_KEY}" }
    }
  }
}
```

**Codex:**

Add the server to `~/.codex/config.toml`. Codex reads the bearer token from the environment variable you name:

```toml title="config.toml"
[mcp_servers.primaryapi]
url = "https://api.primaryapi.com/mcp"
bearer_token_env_var = "PRIMARYAPI_API_KEY"
```

**VS Code:**

In `.vscode/mcp.json`, let VS Code prompt for the key once and store it securely:

```json title=".vscode/mcp.json"
{
  "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

1. `search_apis` with what you need, for example `{"query": "google maps reviews"}`. Free.
2. `get_api` with the chosen SKU before its first run. Read `inputSchema`: field names are exact and unknown fields are rejected.
3. Optional: `quote_api` to see the price for this exact input. Free.
4. `run_api` with `sku` and `input`. Ask only for what you need with `fields` and `max_items`.
5. If the result says the call is still running, call `get_request` with the `requestId` after the suggested delay. Do not call `run_api` again to wait: that starts, and bills, a second job.
6. Need other fields from the same result later? `read_result` re-reads it for free.

```json title="run_api arguments"
{
  "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:

```bash
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](/docs/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 `run` key with a spend limit in credits, so a runaway loop has a known ceiling.
