Connect with MCP

UnwrapEmail’s Model Context Protocol (MCP) server lets your AI client validate emails, manage contacts, run bulk jobs, and inspect usage. It uses Streamable HTTP and your existing API token.

Before you connect

1. Activate a subscription.
2. Create an API token. Copy its secret when it is created; you cannot retrieve the secret later.
3. Set UNWRAP_EMAIL_API_TOKEN in the environment used to launch your client. Restart an already running client after changing its environment. For desktop clients, the variable must be available to the app process, not just another terminal session.

Connect to https://api.unwrap.email/mcp. Settings → API Tokens includes a Connect with MCP panel with the endpoint and copyable configuration.

Configure your client

The examples reference an environment variable and contain no token secret. Merge the server entry into your existing configuration.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.unwrap_email]
url = "https://api.unwrap.email/mcp"
bearer_token_env_var = "UNWRAP_EMAIL_API_TOKEN"

Alternatively, use the CLI:

codex mcp add unwrap_email --url https://api.unwrap.email/mcp --bearer-token-env-var UNWRAP_EMAIL_API_TOKEN

See the Codex MCP documentation.

Claude Code

Add this to your project’s .mcp.json:

{
  "mcpServers": {
    "unwrap_email": {
      "type": "http",
      "url": "https://api.unwrap.email/mcp",
      "headers": {
        "Authorization": "Bearer ${UNWRAP_EMAIL_API_TOKEN}"
      }
    }
  }
}

Use /mcp to inspect the connection. This server uses your API token; it does not provide an OAuth browser-login flow. See the Claude Code MCP documentation.

Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "unwrap_email": {
      "url": "https://api.unwrap.email/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UNWRAP_EMAIL_API_TOKEN}"
      }
    }
  }
}

Check the server in Cursor’s MCP settings. See the Cursor MCP documentation.

Tools and permissions

Every request requires an API token associated with an active subscription. Read-only tokens discover the tools they can use. Full-access tokens also discover submission and mutation tools.

Capability	Tools	Access
Single email	validate_email	Read or full
JSON bulk submission	submit_bulk_validation	Full
JSON bulk progress/results	list_bulk_validations, get_bulk_validation, get_bulk_validation_download	Read or full
CSV submission	prepare_bulk_csv_upload, submit_bulk_csv_validation	Full
CSV progress/downloads	list_bulk_csv_groups, get_bulk_csv_group, get_bulk_csv_download	Read or full
Read contacts	list_contacts, get_contact	Read or full
Change contacts	update_contact, delete_contact	Full
Request an export	create_contact_export	Full
Export history/downloads	list_contact_exports, get_contact_export_download	Read or full
Read custom blacklist	get_domain_blacklist	Read or full
Replace custom blacklist	set_domain_blacklist	Full
Account and subscription	get_account, get_subscription, get_usage	Read or full
Usage analytics	get_analytics	Read or full

Validation uses the same billing and accounting as the REST API. Single-email validation records usage and may create or update contacts even with a read-only token. Discovery and ordinary lookups do not validate emails or create usage. Set validate_domain to true to include MX and registry checks; it defaults to false.

set_domain_blacklist replaces the entire list. Read the current list first to preserve entries; an empty array clears it. delete_contact permanently deletes a contact. update_contact requires the email, first name, and last name; use null to clear a name.

Account deletion, profile editing, API-token management, and billing actions remain in the dashboard. MCP does not offer arbitrary API requests.

Bulk validation and exports

Bulk jobs continue asynchronously after a tool returns. Submit once, keep the returned identifier, and poll the corresponding progress tool at five-second intervals while active. Stop polling at a terminal status. Lists and JSON results are paginated with page and take; use smaller pages when inspecting results in a conversation.

JSON submissions accept up to 10,000 email strings and retain the REST API’s 5 MiB body limit. Malformed email strings produce individual row errors. Use the same optional idempotency_key when retrying an identical bulk submission or upload preparation. Do not automatically retry contact export creation, which has no idempotency key.

For CSV validation:

1. Call prepare_bulk_csv_upload with filename and exact size_bytes (up to 50 MiB).
2. Use your client’s HTTP/file tools to PUT the file bytes to upload_url, preserving the returned upload headers. CSV bytes are not sent through MCP.
3. Call submit_bulk_csv_validation with upload_id, the case-sensitive email_column, and optional validate_domain and idempotency_key.
4. Poll get_bulk_csv_group, then call get_bulk_csv_download when ready.

CSVs support up to 100,000 rows. Bulk jobs expire after 30 days. Downloads use temporary signed public CDN URLs. Preserve their complete query strings and request a fresh link when necessary. The MCP server returns links rather than loading whole files into your conversation.

For contacts, call create_contact_export, poll list_contact_exports for the returned job, then call get_contact_export_download. Feature flags behave as they do in the REST API: disabled bulk features reject new submissions while accepted jobs remain accessible; disabled contact exports retain pending jobs.

Troubleshooting

• 401 / connection rejected: check that your client process can read the environment variable and that the API token is valid. Both Authorization: Bearer <token> and UNWRAP-EMAIL-API-TOKEN are supported; supplying different tokens in both headers is rejected. Dashboard cookies and anonymous playground credentials are not accepted.
• 403 / subscription or permission: confirm an active subscription and use a full-access token for submissions or changes. Token authorization follows the REST API’s cache lifetime; entitlement changes can take effect after that cache expires.
• Missing tool: reconnect after changing token permissions. Account administration tools are deliberately unavailable.
• Invalid inputs: inspect the tool’s schema. Analytics requires ISO timestamps with timezones and an end time on or after the start time.
• Job unavailable: identifiers belong to the authenticated account. Download tools require ready, unexpired results; poll progress first.
• Payload too large: the MCP envelope is limited to 6 MiB, in addition to the underlying API limits. Use the CSV upload flow for larger lists.
• Browser Origin rejected: use a native MCP client or the UnwrapEmail dashboard/API origin. Origin-less native clients are supported.

This server supports Codex, Claude Code, and Cursor; OAuth-only hosted connectors are not supported.