# MCP server

> Connect EmailVerify Pro to Claude, Cursor, Windsurf or any Model Context Protocol client. Email verification tools with read-only and destructive annotations.

Source: https://emailverifypro.com/docs/mcp

The Model Context Protocol lets an AI assistant call real tools instead of guessing. This
server exposes **144 tools** — every endpoint except the 8
inbound ESP webhooks, which exist for SendGrid, SES, Postmark and Stripe to call *you*.

Once connected, an assistant can verify addresses, clean lists, resolve catch-all domains
and check your quota, all without you writing any code.

## Install

Node — nothing to install ahead of time:

```json
{
  "mcpServers": {
    "emailverify": {
      "command": "npx",
      "args": ["-y", "@emailverifypro/mcp"],
      "env": { "EMAILVERIFY_API_KEY": "evp_your_key" }
    }
  }
}
```

Python:

```json
{
  "mcpServers": {
    "emailverify": {
      "command": "uvx",
      "args": ["--from", "emailverify[mcp]", "emailverify-mcp"],
      "env": { "EMAILVERIFY_API_KEY": "evp_your_key" }
    }
  }
}
```

### Where that config goes

| Client | Location |
|---|---|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code | `claude mcp add emailverify -- npx -y @emailverifypro/mcp` |
| Cursor | Settings → MCP → Add new server |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Zed | `~/.config/zed/settings.json` under `context_servers` |

In Claude Desktop the file is reachable via Settings → Developer → Edit Config. Restart
the app after editing.

## Try it

Ask in plain language:

- *“Verify brandon@seamlessai.com and tell me whether it will bounce.”*
- *“Here are 40 addresses — which are safe to email?”*
- *“Is acme.com a catch-all domain?”*
- *“What email format does stripe.com use? Then work out Jane Doe's address.”*
- *“How much of my verification quota is left this month?”*
- *“Add these five addresses to my suppression list.”*
- *“This address came back unknown — dig into why.”*

## What the assistant sees

Each tool carries the endpoint's summary, its method and path, and an annotation saying
how dangerous it is.

| Annotation | Tools | Meaning |
|---|---|---|
| `readOnlyHint` | 90 | `GET` — no side effects, safe to call freely |
| `destructiveHint` | 20 | Deletes or overwrites. Well-behaved clients confirm first |
| `idempotentHint` | — | Repeating the call is safe |

Tools are named after the endpoint: `get_validate`, `post_validate_bulk`,
`post_find_email`, `delete_gdpr_erase`.

### Coverage by category

| Category | Tools |
|---|---|
| Verification | 15 |
| Signals | 14 |
| Infrastructure | 9 |
| Admin | 8 |
| Feedback | 8 |
| Integrations | 8 |
| Auth | 6 |
| Account | 6 |
| Bulk | 5 |
| GDPR / CCPA | 5 |
| System | 5 |
| API Keys | 5 |
| Billing | 4 |
| Database | 4 |

## Narrowing the tool list

144 tools is a large surface, and most clients choose more accurately from a
smaller set. Two environment variables trim it:

```bash
EMAILVERIFY_MCP_READONLY=1
```

Publishes only the 90 read-only tools — nothing can delete or overwrite. This is the
safest setting for a shared or autonomous assistant.

```bash
EMAILVERIFY_MCP_TAGS="Verification,Bulk,Account"
```

Publishes only those categories. Combine both for a minimal, read-only verification
surface.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `EMAILVERIFY_API_KEY` | — | Your key. Without it, only public endpoints work |
| `EMAILVERIFY_BASE_URL` | `https://emailverifypro.com` | Staging or self-hosted instance |
| `EMAILVERIFY_MCP_READONLY` | off | `1` publishes only read-only tools |
| `EMAILVERIFY_MCP_TAGS` | all | Comma-separated category allowlist |
| `EMAILVERIFY_TIMEOUT` | `60` | Per-request timeout in seconds |

A read-only, verification-only setup:

```json
{
  "mcpServers": {
    "emailverify": {
      "command": "npx",
      "args": ["-y", "@emailverifypro/mcp"],
      "env": {
        "EMAILVERIFY_API_KEY": "evp_your_key",
        "EMAILVERIFY_MCP_READONLY": "1",
        "EMAILVERIFY_MCP_TAGS": "Verification,Bulk"
      }
    }
  }
}
```

## Checking it works

Run the server by hand. It speaks JSON-RPC over stdio and prints a banner to stderr:

```bash
EMAILVERIFY_API_KEY=evp_your_key npx -y @emailverifypro/mcp
```

```
emailverify MCP server v1.0.0 — 144 tools (API v6.0.0)
```

If you see that line, the server is healthy and the problem is in your client config.

## Troubleshooting

**The server doesn't appear.** JSON config files are unforgiving — a trailing comma or a
missing brace silently breaks the whole file. Validate it, then fully restart the client.

**Tools appear but every call fails with 401.** `EMAILVERIFY_API_KEY` is missing or
wrong. It must sit in the `env` block of the server entry, not in your shell — MCP
servers do not inherit your interactive environment.

**Calls time out.** Some verifications legitimately take 30 seconds or more while SMTP
probes run. Raise `EMAILVERIFY_TIMEOUT`, or ask the assistant to use the async bulk
endpoint and poll the job.

**`npx` is slow the first time.** It downloads the package on first run. Install it
globally (`npm i -g @emailverifypro/mcp`) and use `emailverify-mcp` as the command to
avoid the delay.

**The assistant picks the wrong tool.** Narrow the surface with
`EMAILVERIFY_MCP_TAGS`, and name the operation you want in your prompt.