Phone Validation for AI Agents: MCP Server Integration Guide (2026)

Why AI agents need phone validation

Agents increasingly sit at the front of revenue workflows: they capture leads from forms, draft follow-ups, and update CRMs. Phone numbers are the least reliable field they touch. A mistyped digit, a landline entered where a mobile was requested, or a disposable VoIP number quietly redirects the whole pipeline toward unreachable contacts.

Pointing an agent at raw phone data is not enough — it needs a contract it can call. The Model Context Protocol gives every client one standard way to discover and invoke tools, so validation, carrier detection, and enrichment become first-class abilities of the agent rather than brittle custom functions you maintain per integration.

What the Phone-Check MCP server exposes

Phone-Check.app hosts an MCP server at https://api.phone-check.app/mcp using the Streamable HTTP transport: every call is a POST of a JSON-RPC 2.0 message with the Accept header set to application/json, text/event-stream. Authentication uses the x-api-key header with a Phone-Check API key; a limited demo path accepts the demo-key value plus a TOTP code in the x-ct header.

Three tools are exposed: account_whoami for a free identity probe, phone_validate for format, country, line type, carrier, and disposable status, and phone_lookup_npa_nxx for US/CA carrier and geographic enrichment. Discovery metadata is published at /llms.txt and /.well-known/mcp/server-card.json, and the Scalar API reference on /open-api includes an MCP panel for interactive testing.

Connect Claude or any MCP client

Remote MCP servers use the http type. Paste your API key into the headers block of the client configuration and restart the client; the tool list appears on the next initialize.

{
  "mcpServers": {
    "phone-check": {
      "type": "http",
      "url": "https://api.phone-check.app/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Connect Claude Code in one line

Claude Code registers remote MCP servers straight from the terminal — no config file needed. Replace YOUR_API_KEY with a Phone-Check API key and the three phone tools are available in your next session:

claude mcp add --transport http phone-check https://api.phone-check.app/mcp --header "x-api-key: YOUR_API_KEY"

Tool walkthrough: account_whoami

Before the agent spends credits, it can verify which account the key belongs to. account_whoami is free, which makes it a safe health check to run at the start of a session or after rotating keys.

curl -X POST https://api.phone-check.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"account_whoami","arguments":{}}}'

# Response (1 credit NOT charged):
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"email\":\"you@example.com\",\"creditsRemaining\":250}" }
    ]
  }
}

Tool walkthrough: phone_validate

The core tool returns validity plus the signals an agent needs to route a contact: country, line type, carrier, and whether the number is disposable. Here is a call for +14155552671 with the response an agent receives.

curl -X POST https://api.phone-check.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"phone_validate","arguments":{"phone":"+14155552671"}}}'

# Response:
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"valid\":true,\"country\":\"US\",\"carrier\":\"AT&T\",\"type\":\"MOBILE\",\"disposable\":false}"
      }
    ]
  }
}

Tool walkthrough: phone_lookup_npa_nxx

For US and CA numbers, the NPA-NXX lookup adds carrier and geographic enrichment from North American numbering plan data. Agents use it to attach place and carrier context to a lead record that phone_validate already confirmed as valid.

curl -X POST https://api.phone-check.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"phone_lookup_npa_nxx","arguments":{"phone":"+14155552671"}}}'

# Response:
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"npa\":\"415\",\"nxx\":\"555\",\"carrier\":\"AT&T\",\"country\":\"US\",\"place\":\"San Francisco, CA\"}"
      }
    ]
  }
}

Agent workflow: a lead enrichment pipeline

A practical agent combines the tools into one pipeline. The table below shows the stages a lead enrichment agent can run end to end, with the Phone-Check signal that drives each decision.

Because the server sends agent instructions in the initialize result, the model knows the credit cost of each call before it acts, and a 402 response tells it the account needs a top-up instead of retrying blindly.

Billing, credits, and error handling

Every tool call costs 1 credit, and account_whoami is free. There are no per-tool tiers, so budgeting an agent run is arithmetic: one credit per number you validate or enrich, nothing for the identity probe.

When the account runs out of credits the server responds with HTTP 402. Treat it as a billing signal, not a validation failure: top up at https://phone-check.app/pricing and let the agent resume. Keep the API key in the client configuration or a server-side secret, and rotate it from Account → API keys if it leaks.

Discovery surfaces and where to go next

Beyond the client configuration, three surfaces describe the server: /llms.txt for agent-readable site discovery, /.well-known/mcp/server-card.json for the machine-readable server card, and the Scalar API reference with an MCP panel on /open-api where you can inspect the REST endpoints behind each tool.

The hosted MCP server is aimed at agents, but every tool maps to the same documented REST API your existing services use, so results stay consistent across human and automated callers.

Frequently asked questions

Put the workflow into practice

Use these guides to register the server, review the REST contract, and budget your credits.

• MCP server integration guide
• Phone validation API guide
• Phone intelligence for autonomous sales agents
• Automate phone validation with AI agents and no-code tools