e2a — email for AI agents

@e2a/mcp-server

Model Context Protocol server for e2a — gives any MCP-aware AI agent its own email inbox to send, receive, reply, and (optionally) review held outbound mail before it ships.

Works with Google ADK, LangChain, OpenAI Agents SDK, Claude Desktop, Cursor, Cline, and any other MCP host.

Connect

e2a's MCP server is hosted. Point your MCP host at the Streamable HTTP endpoint:

https://api.e2a.dev/mcp

Two ways to authenticate:

• OAuth 2.1 (recommended for interactive hosts) — add e2a as a connector and authorize in the browser. No key is pasted into config.
• Bearer API key (programmatic / self-host) — send your e2a dashboard API key in the Authorization: Bearer <e2a API key> header.

An agent-scoped credential resolves its agent server-side. Account-scoped callers pass the agent email per tool call.

Quick start

Google ADK (Python)

import os
from google.adk.agents import Agentfrom google.adk.tools.mcp_tool.mcp_toolset import McpToolsetfrom google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
root_agent = Agent(    model="gemini-flash-latest",    name="e2a_agent",    instruction="Help the user manage their email. Reply to threads with `reply_to_message` to preserve threading headers.",    tools=[        McpToolset(            connection_params=StreamableHTTPConnectionParams(                url="https://api.e2a.dev/mcp",                headers={                    "Authorization": f"Bearer {os.environ['E2A_API_KEY']}",                },                timeout=30,            ),        ),    ],)

LangChain (Python)

Using langchain-mcp-adapters:

import os
from langchain.agents import create_agentfrom langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient({    "e2a": {        "transport": "http",        "url": os.getenv("E2A_MCP_URL", "https://api.e2a.dev/mcp"),        "headers": {            "Authorization": f"Bearer {os.environ['E2A_API_KEY']}",        },    },})
tools = await client.get_tools()agent = create_agent(    "anthropic:claude-sonnet-4-6",    tools=tools,    system_prompt="Reply with reply_to_message; pending_review is accepted, so do not retry it.",)

OpenAI Agents SDK (Python)

import os
from agents import Agent, Runnerfrom agents.mcp import MCPServerStreamableHttp
async with MCPServerStreamableHttp(    name="e2a",    params={        "url": os.getenv("E2A_MCP_URL", "https://api.e2a.dev/mcp"),        "headers": {            "Authorization": f"Bearer {os.environ['E2A_API_KEY']}",        },        "timeout": 30,    },    cache_tools_list=True,    max_retry_attempts=3,) as e2a:    agent = Agent(name="e2a_agent", mcp_servers=[e2a])    result = await Runner.run(agent, "Reply to the latest unread email politely.")

Claude Desktop / Cline / Cursor

Add e2a as a remote MCP server in the host's config (claude_desktop_config.json, cline_mcp_settings.json, etc.):

{  "mcpServers": {    "e2a": {      "url": "https://api.e2a.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_E2A_API_KEY"      }    }  }}

Hosts that support OAuth connectors can instead add https://api.e2a.dev/mcp as a connector and authorize in the browser — no key pasted.

Tools

The server exposes up to 80 tools spanning agents, messages, human-in-the-loop approval, attachments, domains, events, webhooks, API keys, contacts/outreach, email templates (beta), suppressions, and external sending access requests (beta). The visible set depends on your credential's scope: an agent-scoped credential sees the 21 runtime/inbox tools (read, send, reply, restore messages, per-agent outreach); an account-scoped credential also sees the 59 admin/setup tools (agent/domain/webhook/event/template/API-key/contact/ suppression/sending-access management — and HITL review discovery plus approve/reject, which is an account-owner action, never agent self-approval) — all 80. Every tool carries MCP annotations (readOnlyHint/destructiveHint/ idempotentHint) so hosts can auto-approve reads and flag destructive actions. The tables below highlight the most commonly used ones — your MCP host's tool list shows the set your scope allows, with per-tool descriptions.

Identity

Webhook deliveries are signed — verify them. Push delivery is a top-level resource (create_webhook), not a per-agent mode. e2a HMAC-signs every webhook delivery against the webhook's signing secret (returned once from create_webhook / rotate_webhook_secret). Your handler must verify the signature on every request — the e2a SDK exposes constructEvent(rawBody, signatureHeader, secret) which verifies and returns a typed event in one call (throws on a bad signature). Or skip webhooks entirely and poll via list_messages.

Messages

Scheduled sending via send_at / scheduled_at is beta and may change before it is declared stable.

External sending access (beta). On a deployment that restricts it, an account may be limited to sending through the shared identity only to its verified account email and to agent inboxes in the same account. A send_message / reply_to_message / forward_message (or the deprecated send_email) call with any other To/Cc/Bcc recipient refuses the WHOLE send with external_sending_not_enabled (403) — nothing is queued, and the identical call will not succeed on retry. whoami's sending_access object reports the current state (enforcement_applies, shared_external_approved, paid_external_sending_entitled, owner_recipient_verified) and available_unlocks — what can lift the restriction on this deployment: operator_approval always; verified_domain (send from your own verified domain) and paid_entitlement (a paid plan) only where listed. The hosted service lists only operator_approval. To ask for approval, call request_sending_access once (account scope; also available in the dashboard at the error's recovery_url): resubmitting while a request is pending returns the same request, and rate_limited (3 requests per 30 days) must not be retried. An operator decides and the decision is emailed to the account owner; get_sending_access_request shows the current state. No MCP tool can grant approval.

Tool	Description
request_sending_access	Beta. File one request for an operator to review external sending access (use_case, recipients, expected_daily_volume). Mutating: refused with account_read_only on a frozen account. (Admin/account-scoped.)
get_sending_access_request	Beta. The account's latest request and its state (pending / approved / declined). Read-only. (Admin/account-scoped.)

MCP message output intentionally omits the REST message-read beta thread_id field and adds no thread filter or endpoint. list_conversations / get_conversation remain caller-owned conversation_id application views, not RFC email-thread enumeration. Use reply_to_message with the original message ID to preserve wire topology.

Human-in-the-loop approval

list_reviews/get_review surface every account-scoped hold: outbound drafts awaiting send approval and inbound messages held by a screening gate. The email.review_requested webhook is an additional push notification for either direction and carries the same message_id. The approve_review/reject_review tools branch on direction: approving an inbound hold releases it to the agent's inbox (no send, no draft, override fields ignored); rejecting one drops it so it never reaches the agent.

Domains

API keys

All admin/account-scoped. create_api_key mints agent-scoped keys only — the key is bound to one inbox and can act only as that agent. Account-scoped (workspace-admin) keys cannot be created over MCP; mint those from the dashboard or the raw API, where a human is in the loop.

Contacts (beta)

The people an account corresponds with (list_contacts / get_contact / create_contact / update_contact / delete_contact, admin/account-scoped) and one agent's per-contact outreach state — stage, next action, reply/ suppression facts (list_outreach_contacts / get_outreach_contact / set_outreach_contact / delete_outreach_contact, available to account scope or an agent-scoped credential for its bound inbox). Import is inert — it records identity and enrolls outreach without sending anything.

Suppressions

Recipient block lists at two scopes, all admin/account-scoped (the server rejects agent-scoped credentials on every one — an agent must not read or edit blocklists). The account list is auto-populated by hard bounces and complaints and applies to sends from every agent; the agent list (beta) holds unsubscribe/manual blocks for one exact sending agent.

Templates (beta)

Reusable email templates with {{variable}} interpolation (a flat Mustache subset — no loops/sections; missing variables render as empty strings), plus a read-only catalog of pre-built starters (welcome, verify-code, password-reset, receipt, agent-status, daily-digest, approval-request). Send with a template via send_message's template_id / template_alias + template_data (mutually exclusive with literal subject/body). All template management tools are admin/account-scoped. Beta — shapes may change before templates are declared stable.

Errors

Every failed tool call returns an MCP result with isError: true and two representations of the error:

• structuredContent — the machine-branchable form. Branch on this, not the text:

  json

  {  "code": "domain_not_verified",  "retryable": false,  "status": 403,  "request_id": "req_abc123",  "retry_after_seconds": 30,  "details": { "field": "…" }}

  Field	Presence	Meaning
  code	always	Stable snake_case token from the API error envelope (e.g. domain_not_verified, rate_limited, message_not_pending). Errors raised by the MCP layer itself (bad/missing arguments, confirm:true guards) carry invalid_request.
  retryable	always	true when a retry could plausibly succeed (rate limit, 5xx, connection failure).
  status	API errors only	HTTP status of the API response (0 = connection-level failure). Absent when no request was made (MCP-layer validation).
  request_id	when available	Server request id — quote it in support requests.
  retry_after_seconds	when available	Back-off hint for retryable errors.
  details	when available	Structured field-level detail from the envelope (omitted if oversized).

• content (text) — the human-readable form, unchanged and stable: e2a error [<code>] (retryable)?: <message> for API errors, e2a error: <message> for MCP-layer errors. Existing agents that parse this text keep working, but new integrations should read structuredContent instead.

Successful results are unaffected (JSON in a text block; list tools return a domain-named array plus next_cursor while more pages remain).

Operating the HTTP server

Self-hosters run the HTTP transport via mcp/Dockerfile or the mcp service in the repo's docker-compose.yaml. Day-2 operations (SLOs, failure classes, correlation) are covered by docs/runbooks/mcp-server.md; this section is the reference for configuration and surface.

Environment variables

Health endpoints

All three are unauthenticated:

• GET /healthz — process liveness only, never touches the backend: { "ok": true }. Wire to your liveness probe.

• GET /readyz — readiness: probes {E2A_API_URL}/api/health (2s timeout, result cached 10s so a scraping fleet can't cause a probe storm). 200 { "ok": true, "checks": { "api": "ok" } } when reachable; 503 { "ok": false, "checks": { "api": "unreachable" }, "request_id": "…" }

  • Retry-After: 10 (the failure-cache TTL) when not. Wire to your readiness probe.

• GET /metrics — Prometheus text exposition. Example lines:

  mcp_http_requests_total{route="mcp",status_class="2xx"} 1523mcp_http_request_duration_seconds_bucket{route="mcp",le="0.5"} 1480mcp_auth_resolutions_total{result="cache_hit"} 1490mcp_tool_executions_total{tool="list_messages",outcome="ok"} 412mcp_readyz_checks_total{result="ok"} 60mcp_resolve_cache_entries 7

  Route labels are bounded: mcp | healthz | readyz | metrics | discovery | other.

Structured logs

Single-line JSON on stderr (GCE-shaped severity / event / message plus fields). Request-scoped events carry request_id (the response's X-Request-Id): auth_resolution (result, duration_ms, scope?; invalid/fallback at WARNING), http_request (route, method, status, duration_ms; successful probe/scrape traffic on healthz/readyz/metrics is metered but not logged), tool_execution (tool, outcome, duration_ms, error_code?), terminal_error. Bearer tokens are never logged; the resolve cache is keyed by SHA-256 fingerprints. An inbound X-Request-Id matching ^[A-Za-z0-9_-]{1,64}$ is honored; otherwise the server mints mcpreq_<12hex>. The id is echoed on every response but is not forwarded to the backend API.

Client retry policy

Failed tool calls return structuredContent (see Errors): branch on code / retryable / retry_after_seconds. Retry only retryable: true errors with exponential backoff + jitter, ~3 attempts max. Never retry 4xx (401 → re-authenticate; 421 → fix the URL). accepted, scheduled, and pending_review on send tools are success outcomes — do not retry them. A future send_at to the sending agent's own address returns 400 invalid_request when direct loopback applies; review holds take precedence and drop the schedule. The transport is stateless, so "reconnect" after an interruption is simply re-POSTing; MCP clients do this automatically.

Links

• e2a docs
• Source
• Issues
• Model Context Protocol

License

Apache-2.0