The APIVerve MCP server is hosted. There is no package to install or keep current: you point a client at one URL, give it a credential, and the client receives a tool for every endpoint in the catalog. New endpoints appear as tools the day they ship, because the server builds its tool list from the same catalog the REST API runs on.
https://api.apiverve.com/v1/mcpThe decisions you actually have to make are small but they matter: which transport your client speaks, how it authenticates, and where the config lives. Get those right and the rest is copy and paste.
01Two decisions before you paste anything
Transport: hosted HTTP or the stdio bridge
Most current clients can talk to a remote MCP server over Streamable HTTP, and that is the default here. Some clients, or some versions of them, can only launch a local process and talk to it over stdio. For those, APIVerve publishes an official Docker image, apiverve/mcp, that speaks stdio to the client and forwards every request to the hosted endpoint. Because it is only a bridge, there is still nothing to update locally when the catalog changes.
Use the hosted endpoint whenever your client supports it. The bridge adds a dependency on Docker being installed and running, and a container start on every session.
Authentication: OAuth or a key in the config
The server negotiates rather than making you choose up front.
- OAuth is the default. Connect with no credentials and the server answers
401with aWWW-Authenticateheader pointing at its protected-resource metadata. A client that supports MCP authorization runs the sign-in flow, you approve it in a browser, and no key is ever written to a file. This is the right choice for a config you commit or a machine you share. - A key in the
x-api-keyheader is simpler to automate and is what headless setups and CI use. The cost is that a credential now sits in a file on disk. If you go this way, put a sub-key there, never your primary key. Lesson 4 explains why in detail.
Either way, the credential is checked against your account on every call, so rotating or revoking a key takes effect immediately, even against an OAuth token issued earlier.
You can see the negotiation for yourself. An unauthenticated request gets the challenge a client needs to start OAuth:
curl -si -X POST https://api.apiverve.com/v1/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
# HTTP/1.1 401 Unauthorized
# WWW-Authenticate: Bearer resource_metadata="https://api.apiverve.com/.well-known/oauth-protected-resource"You are adding the APIVerve server to a .vscode/mcp.json that the whole team commits to the repository. Which authentication approach fits best?
02Configs for real clients
Every block below uses the placeholder YOUR_API_KEY_HERE. If your client supports OAuth, you can delete the headers object entirely and sign in when prompted. A one-command installer also exists: npx @apiverve/mcp-server writes the config for VS Code and Cursor in place and tells you what to do for the desktop app; pass cursor, vscode, claude or all to narrow it, and --api-key KEY to write a key instead of using OAuth. Restart the client afterwards either way.
Cursor
Open Settings → MCP → Add new server, or edit ~/.cursor/mcp.json directly (a project-level .cursor/mcp.json also works):
{
"mcpServers": {
"apiverve": {
"url": "https://api.apiverve.com/v1/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY_HERE"
}
}
}
}
VS Code with GitHub Copilot
VS Code uses a servers map, not mcpServers, and wants the transport stated explicitly. Run MCP: Add Server from the command palette, or create .vscode/mcp.json:
{
"servers": {
"apiverve": {
"type": "http",
"url": "https://api.apiverve.com/v1/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY_HERE"
}
}
}
}
Then enable APIVerve in the Copilot tools picker in agent mode. Copying a Cursor block into this file is the most common VS Code mistake: the top-level key is wrong, so the server is silently not there.
Windsurf
Open Settings → Cascade → MCP servers → Add server and paste the same block Cursor uses into mcp_config.json. Windsurf's own documentation shows serverUrl as the key for a remote server and also accepts url; if the server does not appear after a refresh, renaming url to serverUrl is the first thing to try.
Claude Code
Claude Code registers servers from the terminal:
claude mcp add --transport http apiverve \
https://api.apiverve.com/v1/mcp \
--header "x-api-key: YOUR_API_KEY_HERE"claude mcp list shows what is registered, and /mcp inside a session shows each server's connection status. Be deliberate about scope: a server added for a project and saved to a shared project file carries its header with it, so use OAuth there rather than a key.
Claude Desktop
Add it as a remote connector: Settings → Connectors → Add custom connector, with the URL above, and sign in when asked. Do not paste the remote block into claude_desktop_config.json. That file only accepts stdio servers, and a remote entry written there is ignored silently: no error, just no tools. If you must use the file, use the Docker bridge below.
The Docker bridge, for stdio-only clients
{
"mcpServers": {
"apiverve": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "APIVERVE_API_KEY", "apiverve/mcp"],
"env": {
"APIVERVE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
Read the args carefully, because each flag is doing a job. -i keeps standard input open, which is the whole stdio transport. --rm removes the container when the session ends, so you do not accumulate dead containers. -e APIVERVE_API_KEY with no value tells Docker to pass the variable through from the environment the client sets in env, so the key never appears in the process arguments where other users on the machine could see it.
03Prove it works with a one-credit call
A green dot in a settings panel is not proof, and neither is a tool list. When we sent tools/list with a well-formed but made-up key, the server returned the full list anyway; the failure only appeared on the first tools/call, as a result with isError: true saying authentication failed. Discovery is free and the tool list is the same for everyone, so the real test is a call that has to touch your account.
Pick the cheapest deterministic tool you can find and ask for something the model cannot fake. Number to Words costs one credit:
curl "https://api.apiverve.com/v1/numbertowords?number=1204" \
-H "x-api-key: YOUR_API_KEY"words is "one thousand, two hundred four". afterDecimal is null because 1204 has no fractional part.
Then check three things:
- A tool call appears in the transcript. If the model answered without one, the tools were not offered to it. Go to troubleshooting.
- The result matches the response above. The answer is deterministic, so any difference means the model answered from memory.
- The call shows in your dashboard analytics. That confirms the credential belongs to the account you think it does, which matters once you have several sub-keys.
Once that passes, try something that exercises a heavier tool, such as asking the agent to validate an address. Email Validator costs 20 credits, and the cost is printed in its description, so a well-briefed agent knows it is not a casual call:
curl "https://api.apiverve.com/v1/emailvalidator?email=support%40myspace.com" \
-H "x-api-key: YOUR_API_KEY"isRoleAccount is true for support@ addresses. canReceiveMail reflects live DNS.
Your client lists all the APIVerve tools, but the first tool call returns isError with an authentication message. What does that tell you?
04Troubleshooting
Nearly every failed setup is one of a handful of causes, and they look different from each other once you know what to read.
| Symptom | Most likely cause | Fix |
|---|---|---|
| No APIVerve tools at all | The client was not restarted after the config change | Restart it fully, not just the chat window |
| No tools, desktop app | Remote block written into claude_desktop_config.json | Use Settings → Connectors, or the Docker bridge |
| No tools, VS Code | mcpServers used instead of servers, or no "type": "http" | Use the VS Code block exactly |
| Tools listed, every call fails with an auth message | Wrong key, a leftover placeholder, or a key that was rotated | Update the config and restart; rotation has no grace period |
| One tool returns 403 | Key scoping or an IP allow-list blocks that endpoint | Check the key's restrictions; the key itself is fine |
| Calls fail with 429 | Rate limit, or the month's credits are spent | Check remaining credits in the dashboard before retrying |
| A call hangs, then fails | The 60-second per-call timeout | Usually a render or conversion tool; check its typical latency |
| A tool from the docs is missing | Each product serves its own subset of the catalog | Confirm you connected to the host that carries it |
Two of those deserve a sentence more. A 403 on one tool is never a verdict on the key; only a 401 means the credential is bad. And a key in a header does not survive rotation: if you rotate, every client with that key in its config breaks on the next call until you update it and restart. OAuth connections survive rotation of the underlying key.
05Full catalog or one tool
Connecting to https://api.apiverve.com/v1/mcp gives the agent the whole catalog. That is the right shape when a person is exploring in a chat window and choosing the tool is part of the problem.
For an agent with one job, append the endpoint id and you get a server with exactly one tool:
{
"mcpServers": {
"apiverve-email": {
"url": "https://api.apiverve.com/v1/mcp/emailvalidator",
"headers": { "x-api-key": "YOUR_API_KEY_HERE" }
},
"apiverve-phone": {
"url": "https://api.apiverve.com/v1/mcp/phonenumbervalidator",
"headers": { "x-api-key": "YOUR_API_KEY_HERE" }
}
}
}
Same authentication and same billing, but the model sees two tool definitions instead of hundreds. Mounting several single-tool servers like this is usually the right shape for a production agent: less context spent on definitions it will never use, fewer chances to pick the wrong tool, and a hard limit on what it can reach. An id the product does not carry is simply absent, so check the tool list after adding one.
06Next
Your client is connected and you have watched a call go through. Next, look closely at what the model sees when it reads a tool definition, and why the quality of a schema decides how well an agent behaves: Tool schemas and structured output.