# MailVeri MCP Server Docs | Email Verification for AI Agents > MailVeri MCP Documentation - Integrate email deliverability verification directly into AI assistants like Claude, Cursor, Windsurf, Antigravity, and VS Code. - **Source**: https://mailveri.com/docs/mcp - **AI Reference**: https://mailveri.com/llms-full.txt --- Official Model Context Protocol (MCP) v2 server for MailVeri. Connect your AI assistants (Claude Desktop, Claude Code, Codex, Cursor, Windsurf, Antigravity, OpenCode, Pi, Oh My Pi, VS Code Cline) via instant Hosted Streamable HTTP (`/mcp`), local `uvx` (`stdio`), or legacy SSE (`/sse`). Package: `mailveri-mcp v2.0.0` Protocol: `MCP 2025-11-25` MCP Registry: [com.mailveri/mailveri-mcp](https://registry.modelcontextprotocol.io/?q=com.mailveri/mailveri-mcp) PyPI: [pypi.org/project/mailveri-mcp](https://pypi.org/project/mailveri-mcp/) GitHub: [github.com/mailveri/mailveri-mcp](https://github.com/mailveri/mailveri-mcp) Dashboard: [app.mailveri.com/mcp/](https://app.mailveri.com/mcp/) AI / Markdown: [View as Markdown (.md)](https://mailveri.com/docs/mcp.md) ## 1. Overview The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that lets LLMs and AI Agents securely invoke external tools and query live data. The MailVeri MCP Server bridges LLMs directly with MailVeri's infrastructure without requiring manual API calls. ### ⚡ Real-Time Email Validation Verify mailbox deliverability, catch-all domains, role accounts, and 100,000+ disposable providers in real time with zero credits charged on unknowns. ### 📦 Asynchronous Bulk Verification Submit lists of emails from within chat sessions, monitor batch completion percentages, and retrieve filtered CSV or ZIP download URLs. ### 🛡️ Native MCP v2 ToolAnnotations Every tool declares explicit read-only, idempotent, and destructive safety hints so AI clients auto-approve safe balance/status checks while guarding billed or delete actions. ### 🚀 Hosted HTTP & Local uvx Connect instantly over Streamable HTTP (`https://mcp.mailveri.com/mcp`) with zero local setup, or run locally via `uvx mailveri-mcp` directly from PyPI. ## 2. Prerequisites & Authentication Connect instantly to our hosted remote Streamable HTTP endpoint using only your MailVeri API key, or install `uv` to run the local `stdio` server on your workstation. **MailVeri API Key:** Retrieve or create your key in the MailVeri Console at [app.mailveri.com/api-keys/](https://app.mailveri.com/api-keys/) or visit [app.mailveri.com/mcp/](https://app.mailveri.com/mcp/) for interactive configuration. ### Option A: Hosted Streamable HTTP (Zero Install — MCP v2) Point any Streamable HTTP MCP client directly to `https://mcp.mailveri.com/mcp` with your API key in the `Authorization: Bearer` or `X-API-Key` header (in Claude Code `.mcp.json` / `~/.claude.json`, also include `"type": "http"`; legacy SSE clients remain supported at `https://mcp.mailveri.com/sse`): Hosted Remote MCP Configuration (Streamable HTTP) ```json { "mcpServers": { "mailveri": { "url": "https://mcp.mailveri.com/mcp", "headers": { "Authorization": "Bearer YOUR_MAILVERI_API_KEY" } } } } ``` ### Option B: Install uv (Local CLI Runner) `uv` enables instantaneous tool execution without creating global Python environments: Install uv (macOS / Linux / Windows) ```bash # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows PowerShell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` ## 3. One-Click AI Setup Prompt Paste this prompt directly into your AI assistant (e.g. Claude Desktop, Claude Code, Codex, Cursor, OpenCode, Pi, Oh My Pi, Antigravity) to let it automatically set up MailVeri MCP for you. Prompt for AI Assistant ```markdown Please configure the MailVeri MCP (Model Context Protocol) email verification tool for me. Configuration JSON (Hosted Streamable HTTP — no local install required): { "mcpServers": { "mailveri": { "url": "https://mcp.mailveri.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } (In Claude Code `.mcp.json` / `~/.claude.json`, include `"type": "http"` inside `"mailveri"` or run `claude mcp add --transport http mailveri https://mcp.mailveri.com/mcp --header "Authorization: Bearer YOUR_API_KEY"`. For stdio-only clients like `claude_desktop_config.json`, run `uvx mailveri-mcp` with `MAILVERI_API_KEY=YOUR_API_KEY` instead.) Once configured, verify single emails using mailveri_verify_email or check balance using mailveri_get_balance. ``` ## 4. Client Configurations Configure MailVeri MCP across your favorite AI assistants and IDEs. CLIENT Claude Desktop macOS & Windows Add the server definition to your Claude Desktop configuration file: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` claude_desktop_config.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" } } } } ``` CLIENT Claude Code CLI Agent Add MailVeri MCP to Anthropic's Claude Code CLI via Hosted Streamable HTTP (recommended, zero local install) or local `uvx`: - **Project-scoped (shared via repo):** `.mcp.json` (at project root) - **User-scoped (global for all projects):** `~/.claude.json` CLI Command — Hosted Streamable HTTP (Recommended) ```bash claude mcp add --transport http --scope project \ mailveri https://mcp.mailveri.com/mcp \ --header "Authorization: Bearer YOUR_MAILVERI_API_KEY" ``` Or configure Hosted Streamable HTTP directly in `.mcp.json` / `~/.claude.json` (include `"type": "http"`): .mcp.json / ~/.claude.json (Hosted HTTP) ```json { "mcpServers": { "mailveri": { "type": "http", "url": "https://mcp.mailveri.com/mcp", "headers": { "Authorization": "Bearer YOUR_MAILVERI_API_KEY" } } } } ``` Alternatively, run locally via `uvx` (`stdio`): CLI Command — Local uvx (stdio) ```bash claude mcp add \ --scope project \ --env MAILVERI_API_KEY=YOUR_MAILVERI_API_KEY \ mailveri -- \ uvx mailveri-mcp ``` CLIENT Codex CLI & Agent Configure MailVeri MCP in your Codex assistant or agent configuration file. The official Codex CLI uses TOML format: - **Global CLI config:** `~/.codex/config.toml` - **Project CLI config:** `.codex/config.toml` - **Alternative / GUI integrations:** `~/.codex/config.json` ~/.codex/config.toml ```toml [mcp_servers.mailveri] command = "uvx" args = ["mailveri-mcp"] [mcp_servers.mailveri.env] MAILVERI_API_KEY = "YOUR_MAILVERI_API_KEY" ``` If using JSON configuration: ~/.codex/config.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" } } } } ``` CLIENT Cursor IDE Project & Global Add MailVeri MCP via GUI under **Cursor Settings > Features > MCP**, or add directly to your configuration files: - **Project-level:** `.cursor/mcp.json` - **Global user-level:** `~/.cursor/mcp.json` .cursor/mcp.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" } } } } ``` CLIENT Windsurf (Codeium) mcp_config.json Configure via GUI in **Windsurf Settings > Cascade > MCP Servers**, or directly edit the configuration file: - **Configuration path:** `~/.codeium/windsurf/mcp_config.json` ~/.codeium/windsurf/mcp_config.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" } } } } ``` CLIENT Google Antigravity mcp_config.json / settings Configure under global user settings or per-workspace settings: - **Global config:** `~/.gemini/antigravity/mcp_config.json` - **Workspace config:** `.gemini/antigravity/mcp_config.json` mcp_config.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" } } } } ``` CLIENT OpenCode CLI Terminal OpenCode discovers configuration files in the following precedence order: - **Global (Home):** `~/.opencode.json` - **Global (XDG):** `~/.config/opencode/.opencode.json` - **Project directory:** `./.opencode.json` .opencode.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" } } } } ``` CLIENT Pi CLI & Agent Configure MailVeri MCP in your Pi AI assistant settings: - **Global Agent config:** `~/.pi/agent/mcp.json` or `~/.pi/config.json` - **Project config:** `.pi/mcp.json` ~/.pi/agent/mcp.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" } } } } ``` CLIENT Oh My Pi CLI Terminal Configure in Oh My Pi MCP registry: - **Global config:** `~/.omp/mcp.json` - **Project config:** `./.omp/mcp.json` ~/.omp/mcp.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" } } } } ``` CLIENT VS Code / Cline / Roo-Code Extension Config Configure via the Cline extension MCP settings tab, or edit `cline_mcp_settings.json` directly: - **macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - **Windows:** `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` - **Linux:** `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` cline_mcp_settings.json ```json { "mcpServers": { "mailveri": { "command": "uvx", "args": [ "mailveri-mcp" ], "env": { "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY" }, "disabled": false, "autoApprove": [ "mailveri_verify_email", "mailveri_get_balance" ] } } } ``` ## 5. MCP Tools Reference Detailed parameter definitions, response schemas, deliverability status indicators, and MCP v2 `ToolAnnotations` safety hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) for all 6 tools exposed by the MailVeri MCP Server. TOOL mailveri_verify_email 1 Credit Verifies the existence and deliverability of a single target email address. Checks MX existence, connects to the destination mail exchanger via SMTP handshake, evaluates catch-all configurations, disposable email providers, and role accounts. ### Input Arguments | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | Required | Target email address (e.g. `alex@example.com`). | ### Output JSON Schema Tool Result Response ```json { "mail": "alex@example.com", "email": "alex@example.com", "status": "VALID", "is_deliverable": true, "balance": 999, "credits_used": 1, "quality_score": 98, "is_forwarding": false, "message": "Verified alex@example.com successfully" } ``` ### Deliverability Status Enum | Status | Meaning | Deliverability Advice | | --- | --- | --- | | VALID | Mailbox verified successfully. SMTP 250 OK accepted. | Safe to send. Lowest bounce probability. | | INVALID | Recipient address does not exist, syntax is invalid, or domain has no MX. | Do not send. Hard bounce guaranteed. | | DISPOSABLE | Temporary, burnable email provider (e.g. GuerrillaMail, 10MinuteMail). | Block or filter out to preserve sender reputation. | | ROLE_ACCOUNT | Functional company address (e.g. `support@`, `info@`, `sales@`). | Higher complaint risk; proceed with care. | | CATCH_ALL | Domain server accepts all incoming emails regardless of username. | Proceed cautiously; deliverability cannot be guaranteed. | | FULL_INBOX | Recipient mailbox storage quota is exceeded. | Do not send. Soft bounce expected. | | UNKNOWN | Remote mail server greylisted, timed out, or connection refused. | Temporary issue. Retry verification later. | TOOL mailveri_get_balance Free Checks the current verification credits remaining in your MailVeri account. Takes no arguments. ### Output JSON Schema Tool Result Response ```json { "balance": 4820, "message": "You have 4820 credits" } ``` TOOL mailveri_verify_batch 1 Credit / Email Queues a list of emails (minimum 2 unique email addresses) for asynchronous, distributed bulk verification. Returns an identifier `id` to monitor job progress. ### Input Arguments | Field | Type | Required | Description | | --- | --- | --- | --- | | `emails` | array | Required | Array of email strings (at least 2 unique items). | | `filename` | string | Optional | Optional label filename for the batch archive (default: `batch.csv`). | ### Output JSON Schema Tool Result Response ```json { "id": "sample_batch_id_9x8y7z", "job_id": "sample_batch_id_9x8y7z", "count": 250, "status": "QUEUED", "message": "Batch submitted successfully" } ``` TOOL mailveri_get_batch_status Free Polls progress percentage, status state, and download links for an active or completed bulk verification job. ### Input Arguments | Field | Type | Required | Description | | --- | --- | --- | --- | | `job_id` | string | Required | The batch identifier returned from `mailveri_verify_batch`. | ### Output JSON Schema Tool Result Response ```json { "id": "sample_batch_id_9x8y7z", "job_id": "sample_batch_id_9x8y7z", "status": "DONE", "percent": 100, "download_link": "https://api.mailveri.com/v1/download-zip/?id=sample_batch_id_9x8y7z", "is_finished": true } ``` TOOL mailveri_download_batch_result Free Returns the direct authenticated download URL for batch verification results. Supports downloading the full ZIP archive (via `/v1/download-zip/`) or a custom filtered CSV file (via `/v1/download-result/?format=csv`). ### Input Arguments | Field | Type | Required | Description | | --- | --- | --- | --- | | `job_id` | string | Required | The completed batch ID. | | `format` | string | Optional | Result file format: `zip` (default) or `csv`. | | `status` | string | Optional | Comma-separated deliverability statuses for CSV export (e.g. `VALID,ROLE_ACCOUNT`, `VALID`, `INVALID`). | | `columns` | string | Optional | Column layout for CSV export: `original` (default), `compact` (Email, Status), or `email` (Email only). | ### Output JSON Schema (ZIP Archive - Default) Tool Result Response (ZIP) ```json { "id": "bX9K3LwZqP2YtR8vN4mQ", "job_id": "bX9K3LwZqP2YtR8vN4mQ", "format": "zip", "download_url": "https://api.mailveri.com/v1/download-zip/?id=bX9K3LwZqP2YtR8vN4mQ", "message": "Download result ZIP archive at: https://api.mailveri.com/v1/download-zip/?id=bX9K3LwZqP2YtR8vN4mQ (requires API key header)" } ``` ### Output JSON Schema (Filtered CSV Export) Tool Result Response (Filtered CSV) ```json { "id": "bX9K3LwZqP2YtR8vN4mQ", "job_id": "bX9K3LwZqP2YtR8vN4mQ", "format": "csv", "download_url": "https://api.mailveri.com/v1/download-result/?id=bX9K3LwZqP2YtR8vN4mQ&format=csv&status=VALID%2CROLE_ACCOUNT&columns=original", "message": "Download result CSV (VALID,ROLE_ACCOUNT) at: https://api.mailveri.com/v1/download-result/?id=bX9K3LwZqP2YtR8vN4mQ&format=csv&status=VALID%2CROLE_ACCOUNT&columns=original (requires API key header)" } ``` TOOL mailveri_delete_batch Free • Destructive Deletes a finished or canceled verification batch and its associated result files (`destructiveHint: true`). Batches that are still queued or processing cannot be deleted; wait for completion or cancel them from the MailVeri Dashboard first. ### Input Arguments | Field | Type | Required | Description | | --- | --- | --- | --- | | `job_id` | string | Required | Completed or canceled batch ID to delete. | ### Output JSON Schema Tool Result Response ```json { "id": "bX9K3LwZqP2YtR8vN4mQ", "job_id": "bX9K3LwZqP2YtR8vN4mQ", "message": "List leads.csv was deleted successfully" } ``` ## 6. Transports & Execution Modes MailVeri MCP v2 supports Hosted Streamable HTTP (`/mcp`), standard I/O (`stdio`), and backward-compatible Server-Sent Events (`/sse`). | Transport | Endpoint / CLI Flag | Best Used For | | --- | --- | --- | | `streamable-http` (Hosted) | `https://mcp.mailveri.com/mcp` | Instant zero-install cloud agents, IDEs, and web MCP clients authenticating via `Authorization: Bearer` or `X-API-Key`. | | `stdio` (Default CLI) | `--transport stdio` | Desktop and CLI clients like Claude Desktop, Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity where the host process manages the local server lifecycle. | | `streamable-http` / `sse` (Self-Hosted) | `--transport streamable-http --port 8000` | Self-hosted local HTTP deployments serving both `/mcp` (Streamable HTTP) and `/sse` (legacy SSE) on `127.0.0.1`. | ### Environment Variables | Variable | Default | Description | | --- | --- | --- | | `MAILVERI_API_KEY` | *None* | Required for local CLI execution. Your MailVeri API key. | | `MAILVERI_BASE_URL` | `https://api.mailveri.com` | Optional custom MailVeri REST API base URL. | ## 7. Troubleshooting & FAQ ### Q: `uvx: command not found` error Make sure `uv` is installed and available in your shell's `PATH`, or switch to the zero-install hosted Streamable HTTP endpoint (`https://mcp.mailveri.com/mcp`). If Claude Desktop doesn't find `uvx`, provide the full absolute path in your config (e.g. `/usr/local/bin/uvx` or `/Users//.local/bin/uvx`). ### Q: Rate limit warnings on single verification Single email verification (`mailveri_verify_email`) allows up to 10 requests per second (up to 5 concurrent checks) per account. For lists containing 50 or more emails, instruct your AI agent to use `mailveri_verify_batch` for asynchronous bulk processing. ### Q: Tool call returns `{"error": 1, "message": "Invalid API key"}` Verify that your `MAILVERI_API_KEY` environment variable is correctly set in your client's config file and that your key is active in your [MailVeri Dashboard](https://app.mailveri.com/api-keys/). © 2026 MailVeri. All rights reserved. [Website](https://mailveri.com/) • [Docs Hub](https://mailveri.com/docs) • [Pricing ($59/100K)](https://mailveri.com/pricing) • [Compare 36 Verifiers](https://mailveri.com/compare) • [Integrations](https://mailveri.com/integrations) • [Wholesale API](https://mailveri.com/wholesale-api) • [Dashboard](https://app.mailveri.com) • [REST API Reference](https://mailveri.com/docs/api) • [MCP for AI](https://mailveri.com/docs/mcp) • [API Keys](https://app.mailveri.com/api-keys/) • [Webhooks](https://app.mailveri.com/webhooks/) • [MCP Registry](https://registry.modelcontextprotocol.io/?q=com.mailveri/mailveri-mcp) • [PyPI MCP](https://pypi.org/project/mailveri-mcp/) • [GitHub MCP](https://github.com/mailveri/mailveri-mcp) ## Frequently Asked Questions ### Which tools are exposed by the MailVeri MCP server (mailveri-mcp)? The official mailveri-mcp server exposes 6 tools for AI agents: mailveri_verify_email, mailveri_verify_batch, mailveri_get_batch_status, mailveri_download_batch_result, mailveri_get_balance, and mailveri_delete_batch. ### Which AI coding clients and assistants support mailveri-mcp? mailveri-mcp works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any Model Context Protocol compatible AI agent.