@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 Agent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from 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_agent
from 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, Runner
from 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 78 tools spanning agents, messages, human-in-the-loop approval, attachments, domains, events, webhooks, API keys, contacts/outreach, email templates (beta), and suppressions. 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 57 admin/setup tools (agent/domain/webhook/event/template/API-key/contact/ suppression management — and HITL review discovery plus approve/reject, which is an account-owner action, never agent self-approval) — all 78. 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.

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:

  code

  mcp_http_requests_total{route="mcp",status_class="2xx"} 1523
  mcp_http_request_duration_seconds_bucket{route="mcp",le="0.5"} 1480
  mcp_auth_resolutions_total{result="cache_hit"} 1490
  mcp_tool_executions_total{tool="list_messages",outcome="ok"} 412
  mcp_readyz_checks_total{result="ok"} 60
  mcp_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