Authentication
Every request needs an API key in the x-api-key header — the same key used for the REST API. Generate one from Settings → API keys in your dashboard.
Endpoint
https://wavalid.com/api/mcp
A single Streamable HTTP endpoint (POST). It speaks standard MCP JSON-RPC — connect any MCP-compatible client to it, no SDK required on your side.
Set it up with your AI agent
If you're working in an agentic coding tool (Claude Code, Cursor, Windsurf, etc.), paste this and let it edit the config for you:
Add the wavalid MCP server to this project. It's a Streamable HTTP server at https://wavalid.com/api/mcp that needs an "x-api-key" header for auth — add my API key there once I give it to you. Add it to whatever MCP config file this tool uses.Otherwise, configure it manually below.
Claude Desktop
Add this to your MCP client config:
{
"mcpServers": {
"wavalid": {
"url": "https://wavalid.com/api/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}Claude Code
claude mcp add --transport http wavalid https://wavalid.com/api/mcp --header "x-api-key: YOUR_API_KEY"Cursor
Add this to ~/.cursor/mcp.json (or your project's .cursor/mcp.json):
{
"mcpServers": {
"wavalid": {
"url": "https://wavalid.com/api/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}VS Code
Add this to .vscode/mcp.json:
{
"servers": {
"wavalid": {
"type": "http",
"url": "https://wavalid.com/api/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}Tools
validate_number
Checks a single phone number and deducts one credit if the check completes.
| Argument | Type | Required | Description |
|---|---|---|---|
phoneNumber | string | Yes | E.164 international format, e.g. +14155551234. Must include the country code. |
batchId | number | No | Group this check under an existing batch. Omit it and a default batch is used. |
Returns:
{
"phoneNumber": "+14155551234",
"status": "valid",
"creditsRemaining": 482
}status is one of valid, invalid, or limit (the check hit a provider limit — no credit deducted).
validate_bulk
Checks up to 100 numbers in one call and deducts one credit per number checked.
| Argument | Type | Required | Description |
|---|---|---|---|
phoneNumbers | string[] | Yes | 1 to 100 numbers, each in E.164 format. |
batchId | number | No | Group these checks under an existing batch. Omit it and a default batch is used. |
Returns:
{
"results": [
{ "phoneNumber": "+14155551234", "status": "valid" },
{ "phoneNumber": "+442071838750", "status": "invalid" }
],
"creditsUsed": 2,
"creditsRemaining": 480
}Rate limits
Each API key allows 60 requests per minute, shared with the REST API — the limit is per key, not per surface, so REST and MCP calls against the same key draw from the same budget.
A rate-limited request is rejected before it reaches the MCP protocol layer: you get a plain 429 Too Many Requests HTTP response (with a Retry-After header, in seconds), not an MCP tool result. If your client surfaces the raw transport error, check the HTTP status rather than looking for an isError tool result.
Credits are a separate limit from rate limiting: running out of credits fails a tool call even if you're well under the rate limit.
Errors
A failed tool call comes back as a normal MCP tool result with isError: true and the same human-readable message the REST API returns — for example, running out of credits or passing an unknown batchId. The one exception is rate limiting, which is rejected at the HTTP layer before any MCP tool call happens — see Rate limits.