# MCP Server (Model Context Protocol)

> Docs index for AI agents: [https://mailvalid.io/llms.txt](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:

```bash
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

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

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

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

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

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

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

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

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

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

stdio (via the launcher):

```json
{
  "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](https://mailvalid.io/.well-known/mcp.json) and [/.well-known/mcp/server-card.json](https://mailvalid.io/.well-known/mcp/server-card.json).

For a single self-contained reference that covers both REST and MCP, see the [full agent integration guide](https://mailvalid.io/llms-full.txt).