# MCP server

Connect Claude Code, Claude Desktop, Cursor, Codex, VS Code or any MCP client with one URL and a sign-in, or with an API key. 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 | Sign in from your MCP client: add the URL with no headers and the client opens the browser ([Signing in](#signing-in)). Or send an API key as `Authorization: Bearer pa_live_…` (or `X-API-Key`). Every request needs one or the other. |
| Discovery document | `https://api.primaryapi.com/.well-known/oauth-protected-resource/mcp` (RFC 9728) |
| 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) | any |
| `list_apis` | Browse by category or platform, one page at a time. | `category?`, `platform?`, `limit?` (1–100, default 25), `cursor?` | any |
| `get_api` | Full contract of one SKU: input and output schemas, examples, notes, pricing and measured 30-day health. Unknown SKUs get suggestions. | `sku` | any |
| `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 |

Every tool needs a sign-in or a key. A sign-in has the permissions you approved on the consent page, which match the key access levels: running and quoting APIs is what a `run` key can do, and seeing the balance is what a `view` key can do. **Full access to your workspace** is what a `full` key can do: the MCP server asks for it, so an agent can also buy and renew domains and change DNS and nameservers. Only owners and admins can allow it; for anyone else the app gets the other permissions. A sign-in never manages your API keys, webhook signing secrets, monitors, billing or members.

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 from a tool come back as tool results with `isError: true`, carrying the same `code` as the REST API and a sentence about what to do next. Credentials are checked first, at the HTTP level: a request with no sign-in and no key, an unknown key, or a sign-in that expired, was revoked or was disabled answers `401`, so your client knows to sign in. An API key that is disabled or expired, or a key or sign-in paused for lack of credits, still connects: every tool, search included, then answers with its usual error and what to do.

## Connect your client

Add the URL and sign in: there is no key to copy. Each client below shows that first, then the same client with an API key, for clients that can't sign in and for agents working on their own. Give agents a key with `run` access and a spend limit, and keep it in an environment variable or your client's secret prompt, never in a file you commit.

**Claude Code:**

**Sign in**

```bash
claude mcp add --transport http primaryapi https://api.primaryapi.com/mcp
```

Then type `/mcp` in Claude Code to sign in. To add the server for all your projects at once, put `--scope user` before `primaryapi`.

To share it with a project, commit a `.mcp.json`. Each person signs in with `/mcp`:

```json title=".mcp.json"
{
  "mcpServers": {
    "primaryapi": {
      "type": "http",
      "url": "https://api.primaryapi.com/mcp"
    }
  }
}
```

**With an API key**

```bash
claude mcp add --transport http --scope user primaryapi https://api.primaryapi.com/mcp \
  --header "Authorization: Bearer $PRIMARYAPI_API_KEY"
```

Or 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), then restart Claude Desktop.

**Sign in**

`mcp-remote` opens the browser for you to sign in:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "primaryapi": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.primaryapi.com/mcp"]
    }
  }
}
```

**With an API key**

```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_…" }
    }
  }
}
```

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

**Sign in**

Cursor opens the browser for you to sign in:

```json title="mcp.json"
{
  "mcpServers": {
    "primaryapi": {
      "url": "https://api.primaryapi.com/mcp"
    }
  }
}
```

**With an API key**

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

**Sign in**

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

Then run `codex mcp login primaryapi` to sign in in the browser.

**With an API key**

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

Add the server to `.vscode/mcp.json`.

**Sign in**

```json title=".vscode/mcp.json"
{
  "servers": {
    "primaryapi": {
      "type": "http",
      "url": "https://api.primaryapi.com/mcp"
    }
  }
}
```

Sign in when the browser opens.

**With an API key**

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 connects to remote MCP servers over Streamable HTTP works the same way: add `https://api.primaryapi.com/mcp` with no headers and sign in when the client opens the browser. If it can't sign in, send the `Authorization` header with a key.

## Signing in

Signing in uses OAuth, the way the MCP authorization spec describes, so a client that supports it needs nothing but the URL:

1. The client sends a request with no credentials. The server answers `401` with a `WWW-Authenticate: Bearer` header whose `resource_metadata` points to `https://api.primaryapi.com/.well-known/oauth-protected-resource/mcp` ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)).
2. The client reads that document, finds where to sign in and opens that page in your browser.
3. You sign in, or create an account, then pick the workspace and approve. You can set a spend limit for the app on the same page.
4. The client keeps the token it gets and sends it with every request.

A sign-in acts through a key that the approval creates in the workspace, listed in the dashboard under **Settings › Connected apps**. Billing, access levels, spend limits and rate limits are the same as with an API key, and calls spend the workspace's credits. Revoke the app there to cut it off; its next request answers `401` and the client asks you to sign in again.

## With an API key

API keys work exactly as before. Send `Authorization: Bearer pa_live_…` (or `X-API-Key`) from clients that can't sign in, from scripts, and from agents that [signed themselves up](/docs/agent-signup) and hold a trial key. [Authentication](/docs/authentication) covers access levels, spend limits and rotation.

## What changed on 2026-11-17

- You can connect with the URL alone and sign in. There is no key to copy.
- Every request needs a sign-in or a key. Before, `search_apis`, `list_apis` and `get_api` also answered requests that carried neither; such requests now answer `401`. If you connected that way, sign in or add a key.
- API keys, prices and tools are unchanged.

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

## Connected accounts: access rules and approvals

On the APIs that run as a [connected account](/docs/connected-accounts), each connection has agent access rules that apply to calls through this server only. Your API keys and the REST API always have full access. By default, APIs that only read run, and APIs that change something at the provider ask a person first. The rules can be changed per capability and per API, any time, without reconnecting: [Agent access rules](/docs/connected-accounts#agent-access-rules).

- **Off**: `run_api` answers `connection_access_off`, with `details.settingsUrl`, the dashboard page where a person can change the rule. Don't retry.
- **Ask**: `run_api` answers `approval_required`. Give your human `details.approvalUrl`. Once they approve, run the same call again with `approval` set to `details.approvalId`. Add a short `reason` to the call so the person sees what you are doing; it is shown as your words and never trusted for anything.
- An approval runs one call with the same input, within 24 hours. A declined, used or expired approval answers `approval_unavailable`: run the call without `approval` for a new link, and if it was declined, ask before trying again.

```json title="run_api arguments, after approval"
{
  "sku": "cloudflare.create_dns_record",
  "input": { "connection": "cust_1042", "zone": "example.com", "type": "A", "name": "api", "content": "198.51.100.4" },
  "approval": "apr_01JD…"
}
```

Two tools work on the rules themselves:

| Tool | What it does |
|---|---|
| `get_connection_access` | One connection's rules: each capability and API, the rule that applies and where it comes from, and whether the account was connected with full access. |
| `set_connection_access` | Change rules. A change that only tightens them applies at once. One that loosens any rule (from Off to Ask, or from Ask to Allowed) needs a person: nothing changes, and you get an approval link for your human instead. |

Neither refusal, nor an approval, is ever charged.

## Debugging with raw HTTP

The server speaks JSON-RPC 2.0 over plain `POST`. List the tools with your key:

```bash
curl -sS -X POST "https://api.primaryapi.com/mcp" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Leave out the `Authorization` header and add `-i` to see the `401` and the `WWW-Authenticate` header a client signs in from. Every response carries an `X-Request-Id` header; include it when you report a problem.

## Limits and safety

- 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. A sign-in counts as its own key. Refused requests (no or bad credentials) are limited per network, then answer `429`.
- The server never asks a model to reveal its key, and tool results never contain it. Never paste a key into a prompt: sign in, or configure the key in the client as shown above.
- Agents that run calls should have a known ceiling: a dedicated `run` key with a spend limit in credits, or a sign-in with a spend limit, so a runaway loop stops there.
