MobileValidate

@mobilevalidate/mcp

Model Context Protocol server for MobileValidate. It lets AI agents (Claude Desktop, Claude Code, Cursor, VS Code and any other MCP client) check phone numbers — registration on WhatsApp, Telegram, Viber, Signal and other platforms, carrier and line type, report-based spam reputation — and e-mail addresses (mailbox exists; account on Gmail, Outlook, Apple and others; yes / no / unknown only, never names or profiles). Several services can be checked in one call (checks); list_services shows what the key can use.

It is a thin client of the public MobileValidate API, built on the mobilevalidate SDK. It holds no credentials of its own: your key is only forwarded to api.mobilevalidate.com.

Two ways to use it:

Both run the same tools with the same spend safeguards. Try either with a test key: the documented test values return fixed answers and nothing is billed.

Keys: an agent key (mv_agent_…, scoped, daily spend cap) or a test key (mv_test_…, free, never billed). Live keys (mv_live_…) are refused by the MCP server on purpose. Get a personal test key at https://mobilevalidate.com/get-test-key; agent keys come with an approved account.

Docs: https://mobilevalidate.com/docs/mcp

Quick start (hosted, test key)

export MOBILEVALIDATE_API_KEY=mv_test_...     # your personal test key

claude mcp add --transport http mobilevalidate https://mcp.mobilevalidate.com/mcp \ --header "Authorization: Bearer $MOBILEVALIDATE_API_KEY"

Then ask: *"Check +447700900001, +447700900002 and +447700900003 on WhatsApp."* You get registered, not registered and unknown. Test keys never reach a real network and are never billed: the magic values below give fixed answers, and any other number gets a made-up but stable answer.

Just looking? The public sandbox key mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym works too, but it answers only the magic values below (anything else is refused with sandbox_magic_only), has low shared rate limits and cannot run large jobs. Use your own test key for anything more.

Test e-mail addresses: registered@test.mobilevalidate.com, not-registered@…, unknown@… (same domain). Full list: https://mobilevalidate.com/docs/test-values.

Client configuration

Claude Code

# hosted

claude mcp add --transport http mobilevalidate https://mcp.mobilevalidate.com/mcp \ --header "Authorization: Bearer $MOBILEVALIDATE_API_KEY"

local stdio

claude mcp add mobilevalidate --env MOBILEVALIDATE_API_KEY=mv_agent_... -- npx -y @mobilevalidate/mcp

.mcp.json equivalent of the hosted setup:

{

"mcpServers": { "mobilevalidate": { "type": "http", "url": "https://mcp.mobilevalidate.com/mcp", "headers": { "Authorization": "Bearer ${MOBILEVALIDATE_API_KEY}" } } } }

Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

Hosted (live):

{

"mcpServers": { "mobilevalidate": { "url": "https://mcp.mobilevalidate.com/mcp", "headers": { "Authorization": "Bearer ${env:MOBILEVALIDATE_API_KEY}" } } } }

Local stdio: { "mcpServers": { "mobilevalidate": { "command": "npx", "args": ["-y", "@mobilevalidate/mcp"], "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." } } } }

VS Code (.vscode/mcp.json)

{

"servers": { "mobilevalidate": { "type": "http", "url": "https://mcp.mobilevalidate.com/mcp", "headers": { "Authorization": "Bearer ${input:mobilevalidate-key}" } } }, "inputs": [ { "id": "mobilevalidate-key", "type": "promptString", "description": "MobileValidate agent or test key", "password": true } ] }

Claude Desktop (claude_desktop_config.json)

Claude Desktop connects to remote servers with a key through a stdio bridge such as the community mcp-remote package (hosted server, live):

{

"mcpServers": { "mobilevalidate": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.mobilevalidate.com/mcp", "--header", "Authorization:Bearer ${MOBILEVALIDATE_API_KEY}"], "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." } } } }

Local stdio:

{

"mcpServers": { "mobilevalidate": { "command": "npx", "args": ["-y", "@mobilevalidate/mcp"], "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." } } } }

Any other MCP client

• Streamable HTTP: URL https://mcp.mobilevalidate.com/mcp, header Authorization: Bearer mv_agent_…. The server is stateless: POST only, JSON responses, no session id.
• stdio: command npx, args ["-y", "@mobilevalidate/mcp"], env MOBILEVALIDATE_API_KEY=mv_agent_…. To pin a version use @mobilevalidate/mcp@1.2.0. After npm install -g @mobilevalidate/mcp the command is mobilevalidate-mcp.

Protocol versions

Both transports speak MCP 2026-07-28 and the handshake-based revisions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 and 2024-10-07 (from 1.1.0; 1.0.x stopped at 2025-11-25). Nothing to configure: the client's opening message picks the revision.

• 2026-07-28: no initialize; every request carries _meta (io.modelcontextprotocol/protocolVersion, client info and capabilities) and, over HTTP, the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers (checked against the body; mismatch → 400, -32020). server/discover returns the supported versions, capabilities, server identity and instructions. tools/list and server/discover carry ttlMs: 3600000, cacheScope: "public" (the list is the same for every key), and tools come back in a fixed order. An unsupported version gets 400 with UnsupportedProtocolVersion (-32022) listing the supported ones. Tool calls return JSON (no SSE).
• 2025-era clients: initialize as before; the hosted server stays stateless (POST only, JSON responses, no session id; GET → 405). On stdio the connection stays on the negotiated revision.
• The server uses no server→client requests (sampling, elicitation, roots) and no protocol logging, so nothing deprecated in 2026-07-28 is involved. Bulk jobs use an explicit job_id handle, the pattern the spec recommends now that sessions are gone.
• The server card's supportedProtocolVersions lists the same versions (newest first).

Tools

Every tool declares a title, annotations, inputSchema and outputSchema. Each one returns structuredContent plus a one-line text summary. checks takes service codes or aliases (e.g. whatsapp, telegram, viber, carrier, spam); its description lists the real-time and bulk-only codes known to this build (from the SDK's generated catalog), and list_services gives the live list. Result items keep the v1 top-level fields (WhatsApp if requested, otherwise the first service) and add a checks map per service when more than one service (or a non-WhatsApp service) was requested. Tool descriptions state the anti-enumeration limits (≥ 20 consecutive numbers refused, daily caps).

E-mails. Phone services run on numbers, e-mail services on emails; send at least one check of each kind you send. Result items carry kind (phone/email); e-mail items have email (normalized, null if invalid), email_status (valid, invalid_email, duplicate, suppressed) and number_status: null. Descriptions state the e-mail rules: ≥ 20 addresses on one domain differing only by digits are refused as enumeration, and answers are yes/no/unknown only — no names, photos or profiles. Test keys use registered@test.mobilevalidate.com, not-registered@…, unknown@… (same domain).

Spam reputation. check_spam_reputation (or checks: ["spam"] on the other tools) answers from spam and nuisance-call reports: regulator actions, government complaint data, community reports and recently-unassigned numbers. All countries except sanctioned ones (Cuba, Iran, North Korea, Syria, Russia, Belarus, Venezuela and sanctioned regions → unsupported_country, free). no_reports means no reports are known — not that the number is safe; it is still a conclusive, billed answer. Limits: ≤ 100 numbers per call, the same spend confirmation and anti-enumeration rules as lookup_numbers. Test keys: +447700900001 high, …002 no_reports, …003 unknown, …004 pending then medium, …005 unsupported_country. Attribute values may be integers (risk_score, sources).

Network checks. checks: ["hlr"] returns live network status (status reachable / unreachable / invalid, ported, roaming, mcc_mnc, country); checks: ["mnp"] returns number portability (porting ported / not_ported, mcc_mnc, country). Unknown answers are free.

Spend safety

Before lookup_numbers, lookup_emails, check_spam_reputation or create_lookup_job spends anything, the server calls the free estimate. Real-time tools quote the maximum at the key's real-time prices (from list_services), create_lookup_job at bulk prices. The call is refused with a confirmation_required error result when either of these is true:

• the maximum cost is above MCP_CONFIRM_ABOVE_USD (default 1.00), or
• a job has more than 100 numbers and e-mails.

Scopes (agent keys): the real-time tools need lookup:write and jobs:write (the estimate is POST /v1/jobs/estimate); estimate_cost and create_lookup_job need jobs:write; get_lookup_job needs jobs:read; get_account needs account:read. list_services