# MCP server setup

URL: https://email-validation.org/docs/mcp/
Updated: 2026-10-20

> Documentation index: https://email-validation.org/llms.txt

The email-validation.org MCP server lets AI agents and MCP clients validate email addresses and run bulk jobs with your API
key. It uses the same credits, limits and rules as the REST API: `unknown` results are free, and so are errors.

- **Endpoint:** `https://api.email-validation.org/mcp` (remote, Streamable HTTP, stateless)
- **Authentication:** `Authorization: Bearer <your API key>`
- **Protocol revisions:** 2026-07-28, plus the 2025 revisions for older clients

## Tools

| Tool | What it does | Arguments | Credits |
|---|---|---|---|
| `validate_email` | Validate an email address | `email`, `ip_address` (optional), `timeout` (optional), `fresh` (optional) | 1 credit per result; unknown results, malformed and sandbox addresses are free. |
| `get_credits` | Get the credit balance | none | Free. |
| `create_bulk_job` | Create a bulk validation job | `emails`, `start` (optional), `webhook_endpoint_id` (optional) | 1 credit per unique address that needs a check; unknown results are refunded. |
| `get_bulk_job` | Get a bulk job | `job_id` | Free. |

Each tool returns structured content with the same fields as the REST API, plus a one-line summary for the model.
`validate_email` returns the [validation result](https://email-validation.org/docs/api/validate/#response); the bulk tools return the
[job object](https://email-validation.org/docs/api/bulk/#job). Bulk results are downloaded as CSV in the dashboard or with the
[bulk API](https://email-validation.org/docs/api/bulk/#results).

## Connect a client

1. Create an API key in the dashboard. For an agent, consider a dedicated key with a
   [daily credit cap](https://email-validation.org/docs/authentication/#limits) (it also covers the bulk jobs the key creates), and the `bulk`
   scope only if it should run bulk jobs.
2. Add the server to your client with the endpoint URL and the `Authorization` header. Most clients that support
   remote servers accept a configuration like this:

**JSON**

```json
{
  "mcpServers": {
    "email-validation": {
      "type": "http",
      "url": "https://api.email-validation.org/mcp",
      "headers": {
        "Authorization": "Bearer ${EV_API_KEY}"
      }
    }
  }
}
```

**curl**

```bash
# Check the connection by listing the tools (2025-06-18 protocol revision).
curl https://api.email-validation.org/mcp \
  -H "Authorization: Bearer $EV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

Keep the key in an environment variable or your client's secret store rather than in a shared configuration file.

## Example prompts

- "Check whether jane@example.com is a valid address before I add it to the CRM."
- "Here are 300 sign-ups from last week: create a bulk job, wait for it, and tell me how many are risky."
- "How many credits do I have left, and when do the next ones expire?"

To try the tools without spending credits, ask the agent to check
[test addresses](https://email-validation.org/docs/test-addresses/) such as `catch_all@sandbox.email-validation.org`.

## Limits and credits

- `validate_email` costs 1 credit per result, except `unknown` results, which are free.
- `create_bulk_job` takes up to 10,000 addresses in one call. For bigger lists use the
  [bulk API](https://email-validation.org/docs/api/bulk/) or the dashboard.
- Tool calls count against your account's [rate limit](https://email-validation.org/docs/rate-limits/).
- Errors come back as tool errors with the same codes as the REST API (for example `insufficient_credits`), and
  no credit is used.

## Discovery

The server is described in our [MCP server card](https://email-validation.org/.well-known/mcp/server-card.json) and
[AI catalog](https://email-validation.org/.well-known/ai-catalog.json), so directories and clients that read these files can find it.
The same key also works with the [A2A endpoint and the Agent Skill](https://email-validation.org/docs/ai-agents/).