Connect AI Agents to Email Verification

The Model Context Protocol lets AI agents discover and call external tools over standard JSON-RPC. The Email-Check.app server speaks Streamable HTTP — every call is a POST with an Accept: application/json, text/event-stream header — and exposes two read-only tools: email_validate for full validation and account_whoami as a free identity probe.

Connect Your Client

Every Streamable HTTP client connects with the same three pieces: the endpoint URL, an API key header, and a server name. Copy the block for your client:

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

https://api.email-check.app/mcp

codex mcp add email-check --url https://api.email-check.app/mcp

# ~/.codex/config.toml — shared by the Codex CLI, IDE extension, and desktop app
[mcp_servers.email-check]
url = "https://api.email-check.app/mcp"
env_http_headers = { "x-api-key" = "EMAIL_CHECK_API_KEY" }

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

Replace YOUR_API_KEY with a real key from Account → API keys. Prefer to keep every request on one origin? https://email-check.app/mcp is a thin same-origin proxy that forwards to the same canonical endpoint.

Create an API Key

Keys are host-scoped to Email-Check.app — keys issued for other products are rejected, and each key you create works on the MCP server and the REST API alike.

Want to try before signing up? The key demo-key with a valid TOTP in the x-ct header grants limited, rate-limited trial access.

First Calls with cURL

Every MCP session starts with initialize. The response includes the server's instructions for agents — how to authenticate, what a call costs, and what an HTTP 402 means:

curl -X POST 'https://api.email-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": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0.0" }
    }
  }'

Then validate an address by calling email_validate. MX and SMTP probes are opt-in through the arguments:

curl -X POST 'https://api.email-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": "email_validate",
      "arguments": {
        "email": "support@example.com",
        "verifyMx": true
      }
    }
  }'

The result carries both a machine-readable structuredContent object (validated against the tool's output schema) and a text mirror for clients that only render text:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "structuredContent": {
      "email": "support@example.com",
      "validFormat": true,
      "validMx": false,
      "validSmtp": null,
      "isDisposable": false,
      "isFree": false,
      "detectedName": null,
      "domainSuggestion": null
    }
  }
}

support@example.com passes the syntax check, but the reserved example.com domain accepts no mail — so validMx comes back false and the SMTP probe is skipped, leaving validSmtp null. Read the fields the way the schema intends:

• validFormat — a hard verdict on syntax.
• validMx, validSmtp — nullable probes; null means the probe was not requested or could not conclude, never a failure.
• isDisposable, isFree — provider signals (throwaway or free mailbox domains).
• detectedName — { firstName, lastName, confidence } when the local part yields a probable name, otherwise null.
• domainSuggestion — { original, suggested } on likely typos, otherwise null.
• domainAge, smtpDebug — opt-in diagnostics via checkDomainAge and smtpDebug.

Tool Reference

email_validate arguments

Both tools are read-only and idempotent. Probes are opt-in so a signup screen can run fast format and MX checks, while a scheduled hygiene job pays for the slower SMTP mailbox probe only where it needs the answer.

Billing and Errors

• Every successful tool call consumes 1 credit from the API key owner.
• account_whoami is free — use it as a connectivity and identity probe.
• An HTTP 402 PAYMENT_REQUIRED response means the account is out of credits. Stop the batch, point the operator at email-check.app/pricing to top up, then resume — retrying the same call cannot succeed.
• A missing or invalid key returns HTTP 401; keys created on other products are rejected because keys are host-scoped.
• Schema-invalid tool arguments return a structured error listing the offending fields — surface that message instead of silently retrying.
• Agents receive this contract in the initialize result instructions, so well-behaved clients explain a 402 without extra prompting.

Credit packs and subscription plans are compared on the pricing page. Usage from MCP calls appears in your account usage reporting like any other API call.

Discovery

The server publishes machine-readable metadata so clients and crawlers can find it without reading this page:

• /llms.txt — a crawl-friendly summary of the product, the MCP endpoint, tools, and billing for LLM clients.
• /.well-known/mcp/server-card.json — machine-readable server metadata (v1 shape) other clients read to learn what this server offers.
• /open-api — the interactive API reference includes an MCP panel with one-click client configuration.

Frequently Asked Questions