CarlyEmail docs

MCP

Drive your mail from Claude, ChatGPT or any MCP client.

CarlyEmail serves a Model Context Protocol endpoint at:

https://api.carlyemail.com/mcp

29 tools — inboxes, threads, messages, drafts, attachments, search — the same operations as the REST API, exposed so a model can call them directly.

For Cursor, Windsurf, Codex, Claude Code and most other coding agents, one command writes the config wherever that tool keeps it:

npx add-mcp https://api.carlyemail.com/mcp

Connect from Claude Code

Claude Code takes a header, so an API key is enough:

claude mcp add --transport http carlyemail https://api.carlyemail.com/mcp \
  --header "Authorization: Bearer $CARLYEMAIL_API_KEY"

Connect from claude.ai or ChatGPT

Add https://api.carlyemail.com/mcp as a custom connector. The client discovers the authorization server and walks you through a login — no key to paste.

Once connected you can just ask:

  • "What inboxes do I have?"
  • "Create an inbox called pepsi with display name Pepsi"
  • "Send an email from pepsi@carlyemail.com to jane@example.org about the invoice"
  • "Any unread mail in pepsi? Summarise it."
  • "Reply to the last message in that thread saying we'll follow up Monday."

Protocol support

Both eras are served from one endpoint.

Revision Notes
2026-07-28 Stateless. No initialize handshake; per-request _meta and an Mcp-Method header.
2025-11-25 and earlier, back to 2024-11-05 The legacy initialize handshake, which current chat connectors still speak.

An era is chosen per request, so a client does not have to be upgraded in step with the server.

Authorization

The endpoint is an OAuth 2.1 protected resource. An unauthenticated call answers:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.carlyemail.com/.well-known/oauth-protected-resource",
                         scope="openid profile email"

The client follows that to the protected-resource metadata, finds the authorization server, registers itself and completes an authorization-code flow with PKCE. Both Client ID Metadata Documents and Dynamic Client Registration are supported.

Access tokens are audience-bound: a token is only accepted if its aud is exactly https://api.carlyemail.com/mcp. A token minted for a different service by the same authorization server is refused, which is the confused-deputy attack the resource parameter exists to prevent.

Note

API keys keep working on the MCP endpoint and remain the primary credential. The two are told apart by shape, so nothing changes for existing callers.

What a connection creates

The first authorized call binds your identity to an organization and mints an API key named "MCP connection". It shows up in GET /v0/api-keys like any other key and can be revoked there — revoking it ends the connection rather than silently minting a replacement.

If the email on your identity already matches an organization, the connection links to that organization rather than creating a second one.

Tool annotations

Every tool declares whether it is read-only, so a client can require confirmation only for the ones that actually send mail or delete things.