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.
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 | Sign in from your MCP client: add the URL with no headers and the client opens the browser (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": "[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 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.
Sign in
claude mcp add --transport http primaryapi https://api.primaryapi.com/mcpThen 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:
{
"mcpServers": {
"primaryapi": {
"type": "http",
"url": "https://api.primaryapi.com/mcp"
}
}
}With an API key
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:
{
"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), then restart Claude Desktop.
Sign in
mcp-remote opens the browser for you to sign in:
{
"mcpServers": {
"primaryapi": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://api.primaryapi.com/mcp"]
}
}
}With an API key
{
"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.
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:
{
"mcpServers": {
"primaryapi": {
"url": "https://api.primaryapi.com/mcp"
}
}
}With an API key
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.
Sign in
[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:
[mcp_servers.primaryapi]
url = "https://api.primaryapi.com/mcp"
bearer_token_env_var = "PRIMARYAPI_API_KEY"Add the server to .vscode/mcp.json.
Sign in
{
"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:
{
"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:
- The client sends a request with no credentials. The server answers
401with aWWW-Authenticate: Bearerheader whoseresource_metadatapoints tohttps://api.primaryapi.com/.well-known/oauth-protected-resource/mcp(RFC 9728). - The client reads that document, finds where to sign in and opens that page in your browser.
- 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.
- 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 and hold a trial key. 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_apisandget_apialso answered requests that carried neither; such requests now answer401. If you connected that way, sign in or add a key. - API keys, prices and tools are unchanged.
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.
Connected accounts: access rules and approvals
On the APIs that run as a connected account, 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.
- Off:
run_apianswersconnection_access_off, withdetails.settingsUrl, the dashboard page where a person can change the rule. Don't retry. - Ask:
run_apianswersapproval_required. Give your humandetails.approvalUrl. Once they approve, run the same call again withapprovalset todetails.approvalId. Add a shortreasonto 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 withoutapprovalfor a new link, and if it was declined, ask before trying again.
{
"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:
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 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
runkey with a spend limit in credits, or a sign-in with a spend limit, so a runaway loop stops there.