The Model Context Protocol is how an AI client — Claude, Cursor, VS Code, or anything else that speaks MCP — discovers and calls external tools. The APIVerve MCP server exposes 367 endpoints as tools, so an agent can look up weather, validate an email or decode a VIN by calling the real API rather than guessing from training data.
It is a hosted server. There is no package to keep updated: new endpoints appear as tools the day they ship, because the server generates its tool list from the same catalog the API runs on.
https://api.apiverve.com/v1/mcp
Connecting
The installer
The fastest path writes the config for you:
npx @apiverve/mcp-serverIt configures VS Code and Cursor in place, and tells you what to do for Claude Desktop.
Pass a target to narrow it — claude, vscode, cursor or all — and --api-key KEY to write
a key into the config instead of using OAuth.
npx @apiverve/mcp-server cursor --api-key YOUR_API_KEYRestart the client afterwards to pick up the change.
By hand
VS Code — mcp.json:
{ "servers": { "apiverve": { "type": "http", "url": "https://api.apiverve.com/v1/mcp" } } }Cursor — ~/.cursor/mcp.json:
{ "mcpServers": { "apiverve": { "url": "https://api.apiverve.com/v1/mcp" } } }Claude Desktop — Settings → Connectors → Add custom connector, with the same URL. This one
cannot be done from a file: claude_desktop_config.json only accepts stdio servers, so config
written there for a remote server is silently ignored.
Some clients still require a local stdio process. The official Docker image bridges the two — it speaks stdio to the client and forwards to the hosted endpoint, so there is still nothing to update locally:
{
"mcpServers": {
"apiverve": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "APIVERVE_API_KEY", "apiverve/mcp"]
}
}
}Authentication
Two ways in, and the server negotiates rather than requiring you to choose in advance.
OAuth (default). Connect with no credentials and the server answers 401 with a
WWW-Authenticate challenge pointing at its resource metadata. Your client runs the OAuth flow,
you sign in, and no key is ever written to a config file. This is the right choice on a machine
you share or a config you commit.
API key. Send your key in the x-api-key header — how the installer's --api-key flag and
headless setups work. Simpler to automate, but the key is at rest in a config file, so treat that
file the way you would any secret. A scoped sub-key is a better thing
to put there than your primary key.
Either way, the key is checked against your account on every call. Rotating or revoking it takes effect immediately, even if an OAuth token issued earlier has not expired.
What the agent sees
Tools are generated from the catalog, one per endpoint:
| Field | Where it comes from |
|---|---|
name | The endpoint's title, stripped to [a-zA-Z0-9_-] — GUID Generator becomes GUIDGenerator |
title | The human-readable name, for clients that render one |
description | The endpoint's description, with its credit cost appended |
inputSchema | JSON Schema built from the endpoint's published parameters |
outputSchema | JSON Schema for the response envelope, on protocol 2025-06-18 and newer |
annotations | readOnlyHint: true, openWorldHint: true |
Two of those rows do real work.
The credit cost in the description means the agent can see what a call costs before it makes it. An agent choosing between two ways to answer a question has the information to choose the cheap one.
outputSchema is why results come back as data rather than as a paragraph the model wrote
about the data. Clients on the newer protocol get structuredContent — the response object
itself — alongside the text block older clients read. Both carry the same envelope, so they cannot
disagree.
The readOnlyHint annotation says every tool here is a lookup or a generator: nothing mutates
state on your side. Clients may use that to skip a confirmation prompt, which is what makes a
multi-step agent run bearable.
The briefing the server sends
Alongside the tool list, the server returns an instructions string on initialize, which most
clients inject into the model's context once per session. It tells the agent the things an SDK
would normally put in a README and a model would otherwise have to infer:
- that every call costs credits, and the cost is in each tool's description
- that results arrive as
structuredContentmatching the output schema, and anullfield means not available for this input or plan rather than zero - that fields marked premium may simply be absent on lower plans
- what each error status actually means, and which ones are worth retrying
That last point is the one that changes agent behaviour most. An agent that knows a 429 might be
an empty balance rather than a busy moment stops retrying into a wall.
What a call costs
tools/list is free. Discovery costs nothing, however often a client re-lists.
tools/call costs exactly what the endpoint costs over HTTP — one credit for most, more for
the heavier ones, taken from the same monthly allowance. There is no MCP surcharge and no separate
plan. See plans.
That matters for how you brief an agent. A loop that calls a tool per row in a spreadsheet spends a credit per row, and the agent will not think to ask whether that was your intention.
Errors
A failed call comes back as tool content with isError: true and the API's own message, not as a
JSON-RPC protocol error. That is deliberate: the agent can read what went wrong and correct
itself — a missing parameter, an invalid value — instead of the client surfacing an opaque
failure.
The statuses behave exactly as they do over HTTP: 401 for a key problem, 403 for a
key restriction, 429 for a rate limit or an exhausted balance.
See error handling.
Individual calls time out at 60 seconds.
One endpoint as its own server
Appending an endpoint id gives you an MCP server that exposes exactly that tool:
https://api.apiverve.com/v1/mcp/emailvalidator
Same authentication, same billing, a catalog of one. This is the right shape when an agent has a single job and a list of 367 tools is noise it has to reason past — a support bot that only ever validates addresses, a build step that only ever decodes a VIN.
An id that does not exist, or that this product does not carry, is simply absent.
What is not exposed
The server implements initialize, tools/list and tools/call. There are no MCP resources and
no prompts — the catalog is a set of callable tools, and there is nothing static to mount as a
resource.
Requests must be POST; anything else is refused. Protocol versions 2025-06-18, 2025-03-26
and 2024-11-05 are supported, and the server echoes back the version your client asked for, so
an older client negotiates down rather than breaking.
Keeping an agent's spend bounded
An agent is the one caller that will happily make three hundred requests because a prompt was ambiguous. Three things bound that, and they are worth setting up before you hand it the catalog rather than after.
Give it a sub-key, never your primary key. It is going into a config file on a workstation, which is exactly the credential you want to be able to revoke on its own.
Scope that key to what the agent's job needs. Blocking is a deny-list, so it needs revisiting as the catalog grows — but an agent that only ever validates addresses does not need the endpoint that renders web pages.
Cap its rate, on Mega, so a runaway loop cannot consume the month in an afternoon.
The single-tool server below is the fourth lever, and often the most effective: an agent cannot misuse a tool it was never given.
Full catalog or one tool
Handing an agent 367 tools is not free even though tools/list is. Every tool definition
occupies context, and a long list makes tool selection harder — the model has more to reason past
before it picks. Which shape to use depends on what the agent is for:
| Use the full catalog | Use a single-tool server | |
|---|---|---|
| The agent is | general-purpose, exploratory | doing one job repeatedly |
| Tool choice is | part of the problem | already decided |
| You care most about | reach | precision and context budget |
A middle path worth knowing: mount several single-tool servers rather than one catalog. The agent sees exactly the four tools its job needs, each labelled as its own server, and nothing else. That is usually the right shape for a production agent, and the full catalog is the right shape for a person exploring in a chat window.
Troubleshooting
The tools do not appear. The client was not restarted, which is the cause more often than
anything else. After that: config written into claude_desktop_config.json for what is a remote
server — that file only accepts stdio, and remote entries in it are ignored silently rather than
reported.
Everything returns 401. The key in the config is wrong, or it was rotated — rotation is instant and no grace period applies to MCP either. If you connected over OAuth instead, re-run the flow; the key check happens per call regardless of token age.
A specific tool returns 403. A key restriction blocking that
endpoint, or an IP allow-list that does not include the machine the agent runs on. It is never a
sign the key itself is bad — that is 401, and only 401.
A tool the docs mention is missing from the list. Each product serves its own subset of the catalog, so a tool outside the door you connected to is simply absent rather than erroring. Check you are on the host that carries it.
Calls hang and then fail. Individual calls time out at 60 seconds. The endpoints that render or convert are the ones that get near it — see the reference page for the typical latency of the one you are calling.
Trying it
Once connected, ask the assistant something it cannot know:
- Validate this email: test@apiverve.com
- What time is it in Tokyo right now?
- Look up the WHOIS and SSL status for example.com
- Convert 250 USD to EUR at today's rate
You will see the tool call happen in the transcript. If nothing happens, the usual causes are a client that was not restarted, or a config file written for a stdio server when the endpoint is remote.
Next
All endpoints is the catalog these tools are generated from — each reference
page documents the parameters that become a tool's inputSchema.
Authentication covers keys, and rate limits covers what happens
when an agent gets enthusiastic.
LangChain is the alternative for an agent framework that does not speak MCP.