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.
Two 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?
Answer the check above to continue.
Troubleshooting
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.
Full 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.
Next
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.