MCP Server (Model Context Protocol)

Docs index for AI agents: https://mailvalid.io/llms.txt. Every docs page is also available as Markdown: add .md to its URL.

Connect Claude, Cursor or any other MCP-compatible client directly to MailValid. The MCP server is a hosted remote endpoint that uses the Streamable HTTP transport. Its tools run on the same verification engine and credit system as the REST API, so billing is identical.

Setting	Value
Endpoint	`https://mailvalid.io/mcp/`
Transport	Streamable HTTP (use the `http` transport in your client)
Authentication	Your API key in the `X-API-Key` header (or `Authorization: Bearer mv_live_...`)
Billing	Identical to the REST API: a single verification costs 1 credit, bulk reserves credits, reads are free

Every tool requires the X-API-Key header and bills your account. Follow the instructions for your client below.

Claude Code

Run this command in your terminal:

claude mcp add --transport http mailvalid https://mailvalid.io/mcp/ \
  --header "X-API-Key: mv_live_your_key_here"

Then run /mcp in Claude Code to confirm the connection and manage installed servers. Run /context to see token usage per server.

Cursor

Open Cursor Settings → MCP → Add new global MCP server
Paste the configuration below, then save and restart Cursor

{
  "mcpServers": {
    "mailvalid": {
      "url": "https://mailvalid.io/mcp/",
      "headers": { "X-API-Key": "mv_live_your_key_here" }
    }
  }
}

The verify_email tool and the others are available right away. Auth uses your API key, so there's no separate OAuth step.

VS Code (GitHub Copilot)

Create a .vscode/mcp.json file in your workspace with the config below
Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run MCP: List Servers
Start the MailValid server. Its tools are available right away.

{
  "servers": {
    "mailvalid": {
      "type": "http",
      "url": "https://mailvalid.io/mcp/",
      "headers": { "X-API-Key": "mv_live_your_key_here" }
    }
  }
}

Claude Desktop

Claude Desktop only supports local (stdio) MCP servers. Use the @mailvalid/mcp launcher instead of connecting directly over HTTP:

Open Settings → Developer → Edit Config
Add the MailValid server below to your config
Restart Claude Desktop

{
  "mcpServers": {
    "mailvalid": {
      "command": "npx",
      "args": ["-y", "@mailvalid/mcp"],
      "env": { "MAILVALID_API_KEY": "mv_live_your_key_here" }
    }
  }
}

The launcher reads your key from MAILVALID_API_KEY and bridges to the hosted server. You don't manage a URL or header by hand.

Windsurf

Open Windsurf Settings (Cmd+, on Mac) and search for MCP
Select View raw config to open mcp_config.json
Add the MailValid server below, then save and restart Windsurf

{
  "mcpServers": {
    "mailvalid": {
      "serverUrl": "https://mailvalid.io/mcp/",
      "headers": { "X-API-Key": "mv_live_your_key_here" }
    }
  }
}

Other MCP clients

If your client isn't listed above, use one of these transports:

Transport	URL	Notes
Streamable HTTP (recommended)	`https://mailvalid.io/mcp/`	Include the trailing slash to avoid a redirect
`@mailvalid/mcp` launcher	via `npx -y @mailvalid/mcp`	For stdio-only clients (Claude Desktop and similar)

Streamable HTTP (direct connection):

{
  "mcpServers": {
    "mailvalid": {
      "url": "https://mailvalid.io/mcp/",
      "headers": { "X-API-Key": "mv_live_your_key_here" }
    }
  }
}

stdio (via the launcher):

{
  "mcpServers": {
    "mailvalid": {
      "command": "npx",
      "args": ["-y", "@mailvalid/mcp"],
      "env": { "MAILVALID_API_KEY": "mv_live_your_key_here" }
    }
  }
}

Field names vary slightly between clients. Some use servers instead of mcpServers, so check your client's MCP documentation for the expected key names.

Available tools

All tools require your API key:

Tool	Cost	Description
`verify_email`	1 credit*	Verify one address: syntax, DNS/MX, SMTP mailbox, disposable/role/catch-all, confidence. Args: `email`.
`submit_bulk_verification`	Reserves N	Queue a list for asynchronous verification. Args: `emails` (array), optional `webhook_url`.
`get_bulk_job`	Free	Status, progress, and (when complete) results of a bulk job. Args: `job_id`.
`list_bulk_jobs`	Free	List your recent bulk jobs (paginated). Args: `page`, `page_size`, `status`.
`cancel_bulk_job`	Free	Cancel a pending/processing job and release reserved credits. Args: `job_id`.
`get_credit_balance`	Free	Your current credit balance and lifetime usage.

* verify_email is free for unknown results. This is the same billing rule the REST API uses.

Troubleshooting

My MCP client doesn't support remote HTTP servers. Use the @mailvalid/mcp launcher instead. It works over stdio in any client, including Claude Desktop.

I'm getting a 307 redirect or connection errors. Make sure your endpoint URL has a trailing slash: https://mailvalid.io/mcp/, not https://mailvalid.io/mcp.

401 / authentication errors. Check that your API key is passed as X-API-Key (or Authorization: Bearer mv_live_...) and hasn't been revoked in your dashboard. Call get_credit_balance first. It's free, so it confirms the connection and the key without spending credits.

FAQ

Does billing work the same as the REST API? Yes. The MCP tools call the same verification engine and draw from the same credit balance as the REST API and web dashboard. A verify_email call costs exactly what a POST /api/v1/verify/single call costs.

What's the difference between the launcher and connecting directly? The @mailvalid/mcp launcher runs locally over stdio. It's the only option for clients that don't support remote HTTP servers, like Claude Desktop. If your client supports Streamable HTTP directly (Claude Code, Cursor, VS Code), connect straight to https://mailvalid.io/mcp/. That setup is simpler and skips the extra process.

Is there a discovery endpoint for agents? Yes: /.well-known/mcp.json and /.well-known/mcp/server-card.json.

For a single self-contained reference that covers both REST and MCP, see the full agent integration guide.