MCP setup

The eMailPlane MCP server exposes the email API to MCP clients such as Claude, ChatGPT, Cursor and Codex, with the same token scopes as the REST API. It runs on your server.

Tools

GroupTools
Sendsend, send_preflight, send_readiness, message_get, events_query
Receive and replyreceive, message_read, thread_list, thread_get, thread_await, thread_handoff
Agentswhoami, send_policy_get, agent_pause, draft_create, draft_list, draft_get, draft_withdraw, agent_activity, agent_activity_summary
Inboxes for agentsaddress_create, address_list, address_burn
Deliverability and usagesuppression_list, suppression_check, reputation_status, enforcement_list, plan_usage
Templatestemplate_list, template_get, template_create, template_update, template_diff, template_render, template_promote
Domains and mailboxesmail_domain_claim, mail_domain_list, mail_domain_verify, mailbox_create, mailbox_list, mailbox_credential_issue, mailbox_credential_revoke
Domain setupsetup_context, domain_operation_start, domain_operation_get, domain_operation_list, domain_operation_review, domain_operation_resume, domain_operation_cancel
Apps and API keysapp_bootstrap (a whole app with email in one call: 10 minutes once your server is running), app_create, app_get, app_list, app_credential_issue, app_credential_list, app_credential_rotate, app_credential_revoke

A tool only works if your token has the scope it needs, and every decision is made by the API on your server, never by the MCP layer. Have your agent call whoami first: it answers with the inbox the token is limited to, what it may send and what is left of today's budgets.

Mail an agent sends through MCP says it was written by an AI: an EMP-Agent-Disclosure header, covered by the DKIM signature, and one plain sentence at the end of the message. Errors carry the same fields as the API's (error codes).

Connect over HTTP

Every eMailPlane server runs its MCP endpoint at /mcp on its own address, using the streamable HTTP transport. It is the same address as your app's EMAILPLANE_API_URL, with /mcp added:

https://mail.<your-domain>/mcp

Your server's own guide, $EMAILPLANE_API_URL/llms.txt, prints the exact address and a ready configuration. The agent uses a key from emailplane connect on your server, with only the scopes this agent needs (Install, step 6).

The endpoint holds no credentials of its own. Each request must carry your token, which it passes to the API on your server, so a request with no token is refused. It is stateless and answers request/response only.

A typical client configuration:

{
  "mcpServers": {
    "emailplane": {
      "type": "http",
      "url": "https://mail.example.com/mcp",
      "headers": { "Authorization": "Bearer ${EMAILPLANE_API_KEY}" }
    }
  }
}

In Claude Code:

claude mcp add --transport http emailplane https://mail.example.com/mcp \
  --header "Authorization: Bearer $EMAILPLANE_API_KEY"

MCP Registry

eMailPlane is listed in the official MCP Registry as com.emailplane/mail. Its remote URL is https://{emailplane_host}/mcp: your MCP client asks you for emailplane_host, your own server's address (for example mail.example.com), and for your token, so every agent connects to your server and nobody else's. The entry is also published at /mcp/server.json.

Good practice for agents