# MCP server for AI agents

> Connect Claude, Cursor and other MCP clients to MobileValidate: tools, remote and local setup, agent keys and spend confirmation.

Canonical: https://mobilevalidate.com/docs/mcp · Last updated: 2026-09-25

Machine-readable: [MCP server card (JSON)](https://mobilevalidate.com/.well-known/mcp/server-card.json)

**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`](https://www.npmjs.com/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?

| Tool | What it does | Spends credit |
|---|---|---|
| `normalize_numbers` | Formats numbers as E.164 locally; flags ambiguous inputs and duplicates | no |
| `estimate_cost` | Free pre-flight for numbers and/or e-mails: valid, invalid, duplicate and cached counts plus maximum cost | no |
| `lookup_numbers` | Checks up to 100 numbers (optionally with e-mails) against one or more real-time services | yes |
| `lookup_emails` | Checks up to 100 e-mail addresses in real time (default check `email`) | yes |
| `check_spam_reputation` | Spam reputation for up to 100 US, CA or DE numbers: level, score, reasons, counts per level | yes |
| `create_lookup_job` | Bulk job with up to 50,000 numbers and/or e-mails, for any active service including bulk-only ones | yes |
| `get_lookup_job` | Job status plus a filtered, paginated page of results | no |
| `list_services` | Services the key can use: input type, real time or bulk only, attributes, countries, prices | no |
| `get_account` | Balance, reserved credit, today's usage, limits | no |

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.

```bash tabs=off
claude mcp add --transport http mobilevalidate https://mcp.mobilevalidate.com/mcp \
  --header "Authorization: Bearer $MOBILEVALIDATE_API_KEY"
```

`.mcp.json` / Cursor equivalent:

```json
{
  "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`](https://www.npmjs.com/package/@mobilevalidate/mcp) package with `npx`:

```bash tabs=off
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:

```json
{
  "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.

## Frequently asked questions

### Can I use my live key with the MCP server?

No. The MCP server accepts only agent keys (mv_agent_…, scoped and spend-capped) and test keys. Live keys are rejected so an agent can never spend without a cap.

### Can an agent spend a lot of credit by mistake?

Calls above the confirmation threshold (default USD 1.00) or with more than 100 numbers are refused until the agent repeats them with the confirmed amount, and the API enforces that amount as max_cost. The agent key's daily spend cap is the hard limit.

### Does the agent get names or profiles?

No. Tools return yes/no/unknown per service, carrier and line type, or spam-reputation attributes. They never return names, photos or profiles.