MCP server for AI agents

Status: the hosted MCP server at https://mcp.mobilevalidate.com/mcp is live for customers with an agent key or a test key. The local package @mobilevalidate/mcp runs the same tools over stdio.

The MobileValidate MCP server lets AI agents run checks on phone numbers and e-mail addresses through the Model Context Protocol. Agents can check registration on messaging apps, carrier and line type, spam reputation, and mailbox or account existence. It is a thin client of the public API with its own spend safeguards, and it accepts only agent keys and test keys.

#Which tools does it offer?

Each tool declares a title, annotations (read-only, idempotent), an input schema and an output schema. It returns structured content plus a one-line summary. checks takes codes or aliases such as whatsapp, telegram, carrier or spam. Live network status (hlr) is coming soon and not offered yet.

#How do I connect a remote client?

The hosted server speaks Streamable HTTP at https://mcp.mobilevalidate.com/mcp. Send your agent or test key as a bearer token. The key is passed on to the API for that request only and is never stored.

One-click install links for Cursor and VS Code are in the Copy page menu at the top of every docs page.

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

.mcp.json / Cursor equivalent:

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

#How do I run it locally (stdio)?

Run the @mobilevalidate/mcp package with npx:

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

For Claude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json), use:

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

Then ask: "Check +447700900001, +447700900002 and +447700900003 on WhatsApp." With a test key, you get registered, not registered and unknown, at no cost.

#How does spend confirmation work?

Before any tool that spends credit (lookup_numbers, lookup_emails, check_spam_reputation, create_lookup_job) runs, the server gets the free estimate. The real-time tools price it at your key's real-time prices, and create_lookup_job at bulk prices. Because the estimate is POST /v1/jobs/estimate, an agent key needs jobs:write for every spending tool, plus lookup:write for the three real-time tools. It refuses the call with confirmation_required if the maximum cost is above the threshold (default USD 1.00), or if a job has more than 100 numbers and e-mails. The message states the amount. The agent should ask the user, then call again with confirm_max_cost set to that amount. The confirmed amount is sent to the API as max_cost, so the request can never cost more.

This confirmation goes through the agent, so the server can't prove a human approved it. The hard limits are the agent key's daily spend cap and its scopes, which is why live keys (mv_live_…) are rejected. Other safeguards: tools have no webhook URL parameter, request metadata is never echoed into tool output, and the anti-enumeration rules (20 or more consecutive numbers, generated e-mail lists) apply exactly as in the API.