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

Select the workspace you want the client to use and confirm it has an active subscription. Its owner can activate one if needed.
As an owner or admin, create an API token in that workspace. Copy its secret when it is created; you cannot retrieve the secret later.
Follow your client’s token setup below. Most clients read UNWRAP_EMAIL_API_TOKEN from their launch environment; Continue’s IDE integration reads a local .env file. Restart your client after changing it.

Connect to https://api.unwrap.email/mcp. Open Integrations → MCP in the dashboard for client search, the endpoint, native configuration, and supported commands. Settings → API Tokens also links to this setup page beside the token form. Installation commands and manual configuration are alternatives; verification commands run after saving the configuration.

Configure your client

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

Codex

Set UNWRAP_EMAIL_API_TOKEN in the environment used to launch your client, then restart it. For desktop apps, the variable must be available to the app process, not just another terminal.

Install with CLI (Bash/zsh)

Adds the server to your Codex user configuration.

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

Configuration: ~/.codex/config.toml

Merge this server entry into your user configuration.

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

See the Codex MCP documentation.

Claude Code

Set UNWRAP_EMAIL_API_TOKEN in the environment used to launch your client, then restart it. For desktop apps, the variable must be available to the app process, not just another terminal.

Install with CLI (Bash/zsh)

Run from your project directory. The token reference is saved in .mcp.json.

claude mcp add --transport http --scope project unwrap_email 'https://api.unwrap.email/mcp' --header 'Authorization: Bearer ${UNWRAP_EMAIL_API_TOKEN}'

Configuration: .mcp.json

Run the command in your project, or merge this entry into its .mcp.json file.

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

See the Claude Code MCP documentation.

Cursor

Set UNWRAP_EMAIL_API_TOKEN in the environment used to launch your client, then restart it. For desktop apps, the variable must be available to the app process, not just another terminal.

Verify after configuration (Bash/zsh)

Save the configuration below first, then inspect the connection with the Cursor CLI.

agent mcp list

Configuration: ~/.cursor/mcp.json

Merge this entry into your user configuration. The editor and Cursor CLI share this file.

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

See the Cursor MCP documentation.

VS Code

Set UNWRAP_EMAIL_API_TOKEN in the environment used to launch your client, then restart it. For desktop apps, the variable must be available to the app process, not just another terminal.

Install with CLI (Bash/zsh)

Requires the code command on your PATH. Adds the server to your VS Code user profile.

code --add-mcp '{"name":"unwrap_email","type":"http","url":"https://api.unwrap.email/mcp","headers":{"Authorization":"Bearer ${env:UNWRAP_EMAIL_API_TOKEN}"}}'

Configuration: MCP: Open User Configuration → mcp.json

The command adds the server to your user profile. Alternatively, open MCP: Open User Configuration from the Command Palette and merge this entry.

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

See the VS Code / Copilot MCP documentation.

Windsurf

Set UNWRAP_EMAIL_API_TOKEN in the environment used to launch your client, then restart it. For desktop apps, the variable must be available to the app process, not just another terminal.

Configuration: Cascade → Open MCP config file → mcp_config.json

Open the Cascade Actions menu, then Open MCP config file, and merge this entry. In newer Devin Desktop releases this is the legacy Cascade configuration; on macOS/Linux it lives in ~/.config/devin/mcp_config.json.

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

See the Windsurf MCP documentation.

Gemini CLI

Set UNWRAP_EMAIL_API_TOKEN in the environment used to launch your client, then restart it. For desktop apps, the variable must be available to the app process, not just another terminal.

Install with CLI (Bash/zsh)

Adds the server to your Gemini CLI user settings.

gemini mcp add --transport http --scope user --header 'Authorization: Bearer ${UNWRAP_EMAIL_API_TOKEN}' unwrap_email 'https://api.unwrap.email/mcp'

Configuration: ~/.gemini/settings.json

The command uses user scope. Alternatively, merge this entry into your user settings.

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

See the Gemini CLI MCP documentation.

OpenCode

Set UNWRAP_EMAIL_API_TOKEN in the environment used to launch your client, then restart it. For desktop apps, the variable must be available to the app process, not just another terminal.

Interactive setup wizard (Bash/zsh)

Choose a remote server and enter the endpoint above. Complete token authentication using the configuration below.

opencode mcp add

Configuration: opencode.json

Merge this entry into your project configuration. With the wizard, choose a remote server named unwrap_email and the endpoint above, then add the headers and oauth: false shown below.

{
  "mcp": {
    "unwrap_email": {
      "type": "remote",
      "url": "https://api.unwrap.email/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:UNWRAP_EMAIL_API_TOKEN}"
      }
    }
  }
}

See the OpenCode MCP documentation.

Continue

Set UNWRAP_EMAIL_API_TOKEN in ~/.continue/.env, then restart your IDE. The YAML references this local secret; keep the token out of config.yaml and source control.

Configuration: ~/.continue/config.yaml

Merge this MCP server into your existing config.yaml, preserving your models and other settings. Use Agent mode to access MCP tools.

mcpServers:
  - name: unwrap_email
    type: streamable-http
    url: "https://api.unwrap.email/mcp"
    requestOptions:
      headers:
        Authorization: "Bearer ${{ secrets.UNWRAP_EMAIL_API_TOKEN }}"

See the Continue 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
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. Single-email, JSON bulk, and CSV bulk validation include MX and registry checks by default (validate_domain: true). Set validate_domain to false to skip domain lookups.

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:

Call prepare_bulk_csv_upload with filename and exact size_bytes (up to 50 MiB).
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.
Call submit_bulk_csv_validation with upload_id, the case-sensitive email_column, and optional validate_domain and idempotency_key.
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 token’s workspace. Confirm the token was created in the workspace that owns the job. 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.

The clients above connect directly with your API token. OAuth-only hosted connectors are not supported.

Workspace membership, account settings, API-token management, and billing require a signed-in dashboard session. API tokens and MCP tools operate only on the workspace that issued the token. Switching workspaces in the dashboard does not change a token’s scope.