How to Use MCP with an Email API

How to use MCP with an email API: point Claude Code, Cursor, or Codex at a hosted email MCP server, authenticate with OAuth or an API key header, then let the agent call typed tools to create an inbox, send mail, list threads, and reply.

AgentMail hosts that server at https://mcp.agentmail.to/mcp. The client discovers the tool catalog, currently 39 tools for inboxes, threads, messages, drafts, attachments, allow and block lists, and agent sign-up. Free includes MCP with 3 inboxes. OAuth sessions also get list_organizations and select_organization. You do not wire SMTP, MIME parsers, or a human Gmail OAuth flow into the agent loop.

Resend hosts a send-platform MCP at https://mcp.resend.com/mcp, and Gmail MCP and community mail bridges exist too. Those paths fit send APIs or a person mailbox. This tutorial is the inbox-first path: install in three coding agents, read the tool catalog, run one create-send-list-reply loop, then decide when Resend, Mailtrap, or Gmail MCP fits better. We wrote separately about giving a coding agent an email inbox and about Hermes-only wiring.

Prerequisites

You need an AgentMail account or a programmatic agent.sign_up, an MCP-capable client, and either OAuth or an am_ API key.

Create a console account at console.agentmail.to, or let the agent call agent.sign_up then agent.verify with the OTP from agent onboarding. Store the key as AGENTMAIL_API_KEY. Keys start with am_.

Pick one client you already use:

• Claude Code with the claude CLI that supports claude mcp add
• Cursor with MCP settings that accept a remote URL and custom headers
• Codex with an mcp_servers table in ~/.codex/config.toml

The MCP server is on every plan, Free included (pricing). Free gives you 3 inboxes, 3,000 emails a month, 100 emails a day and no custom domains, which is enough to finish this tutorial.

Verify the client can open the hosted URL before you ask it to send mail. A quick check is: after install, ask the agent to list inboxes. If auth fails, fix the key or OAuth consent before the first loop.

What an email MCP server does

An email MCP server exposes inbox and message operations as typed tools the client discovers at runtime.

MCP, the Model Context Protocol, is the open standard that lets a client discover tools at runtime and call them by name. Your client here is Claude Code, Cursor, or Codex, and the server is hosted at https://mcp.agentmail.to/mcp. Tools are the verbs: create an inbox, send a message, search threads, reply, manage drafts, fetch an attachment.

Two auth paths, both in the MCP docs:

• OAuth for Claude Desktop, Claude.ai, and Claude Code. The client signs in through console.agentmail.to. No API key in config.
• API key via the x-api-key header for Cursor, Windsurf, and clients without MCP OAuth. Do not put the key in the query string. Query-string keys end up in logs and history.

The agent never sees SMTP credentials. It calls tools by name.

Install AgentMail MCP with claude mcp add

Add the hosted HTTP transport with claude mcp add, then complete OAuth on first use.

# add the hosted AgentMail MCP server over HTTP
claude mcp add --transport http agentmail https://mcp.agentmail.to/mcp

Claude Code runs the OAuth flow the first time it connects. Connectors you install on Claude.ai do not sync to Claude Code. Install again in the CLI.

After OAuth, ask Claude Code to list your inboxes. If the connector is missing, the agent will say it cannot access AgentMail. Re-run the add command and finish consent.

Claude Desktop and Claude.ai use Settings, then Connectors, then Add custom connector with the same URL. That path is also documented on the MCP page. This tutorial focuses on the coding-agent installs.

Install AgentMail MCP with a Cursor config

Cursor uses the remote URL plus an x-api-key header because it does not implement the MCP OAuth flow the same way Claude products do.

Generate a key under Settings, then API Keys, in the console. Open Cursor settings, go to MCP, and add a server with this shape:

{
  "agentmail": {
    "url": "https://mcp.agentmail.to/mcp",
    "headers": {
      "x-api-key": "${AGENTMAIL_API_KEY}"
    }
  }
}

Windsurf and other header-capable clients use the same URL and header pattern. If a client cannot send custom headers, use the stdio compatibility bridge and pass AGENTMAIL_API_KEY in the subprocess environment (MCP docs).

Confirm the server shows as connected, then ask Cursor to call list_inboxes.

Install AgentMail MCP with a Codex config

Codex reads MCP servers from ~/.codex/config.toml, one mcp_servers table per server, and the Codex MCP docs list the fields. A remote server takes a url. The key goes in a header read from an environment variable, so the file never holds the secret:

# ~/.codex/config.toml: the hosted AgentMail server, key read from the environment
[mcp_servers.agentmail]
url = "https://mcp.agentmail.to/mcp"
env_http_headers = { "x-api-key" = "AGENTMAIL_API_KEY" }

codex mcp add agentmail --url https://mcp.agentmail.to/mcp writes the same table from the command line; add the header line to the file afterwards. Restart Codex, then verify with list_inboxes.

Tools the server exposes (39 by resource)

The hosted server currently exposes 39 tools grouped by resource, plus 2 organization tools on OAuth sessions.

The names below match the MCP docs. Clients discover the live catalog from the server, so the count grows as tools are added.

Inboxes (7): list_inboxes, search_inboxes, get_inbox, create_inbox, update_inbox, delete_inbox, authorize_inbox.

Threads (5): list_threads, search_threads, get_thread, update_thread, delete_thread.

Messages (7): list_messages, search_messages, send_message, reply_to_message, forward_message, update_message, get_message.

Drafts (6): create_draft, list_drafts, get_draft, update_draft, send_draft, delete_draft. Drafts support sendAt (ISO 8601) for scheduled send.

Attachments (1): get_attachment returns metadata, a download URL, and extracted text for PDF and DOCX.

Allow and block lists (4): list_list_entries, get_list_entry, create_list_entry, delete_list_entry.

Agent sign-up (2): agent_attach_human, agent_verify.

Apps and accounts (5): list_apps, search_apps, get_app, connect_app, list_accounts.

AgentMail Labs (2): get_labs, join_labs.

Organizations (OAuth only, 2): list_organizations, select_organization. Persist the selected org across sessions.

That is 39 resource tools plus 2 org tools on OAuth. Pods, custom-domain create and verify, and webhook CRUD are not in this catalog. Use the REST API or SDK for those.

First loop: create_inbox, send_message, list_threads, reply_to_message

Run one conversation that creates an inbox, sends mail, lists threads, and replies to prove the MCP path end to end.

After install, give the agent a single prompt. Keep the username disposable so you can delete the inbox later.

Example prompt (natural language to the agent, not an SDK call). Tool names match the MCP catalog:

Using AgentMail MCP:
1. Call create_inbox with username mcp-lab and a display name MCP lab.
2. Call send_message from that inbox to you@example.com with subject MCP lab ping and a short text body.
3. Call list_threads on the inbox.
4. When a reply arrives, call reply_to_message on the latest message.
Print inbox_id, message ids, and thread ids as you go.

What each tool does in that loop, per the MCP catalog:

• create_inbox provisions an address on @agentmail.to (or a verified custom domain on paid plans). Optional username, domain, display name, metadata.
• send_message sends from the inbox to one or more recipients.
• list_threads returns threads for the inbox, with filters for labels, sender, recipient, subject, and datetime.
• reply_to_message replies in the existing thread. Use reply-all when you need every original recipient.

If you prefer the SDK instead of MCP for the same loop, the Python and Node paths are in agent onboarding: inboxes.create, messages.send, threads.list, messages.reply. MCP is for the coding agent. The SDK is for your application code. We cover skills plus MCP plus SDK together in Give your coding agent an email inbox.

Delete the lab inbox with delete_inbox when you are done so Free-tier slots stay free.

When another email MCP fits instead

Pick the MCP that matches the mailbox primitive you need: send platform, inbox API, or a person Gmail account.

Resend. Hosted at https://mcp.resend.com/mcp with OAuth, and its MCP docs cover the Claude Code, Cursor, and Codex install paths. Tool surface covers emails, received emails, templates, contacts, broadcasts, domains, webhooks, logs, and more. Use it when the agent should operate a send and audience platform, not provision a new agent identity.

Gmail MCP. Fits when the mailbox already belongs to a human and the agent should read or send as that person. AgentMail does not OAuth a Gmail account. It provisions its own inboxes.

Mailtrap and similar send/test stacks. Fit QA and transactional send experiments.

For a longer vendor table, see Mailtrap vs Resend vs AgentMail. For ADK wiring rather than MCP install, see Build an email agent with Google ADK.

Limitations

The catalog stops at inboxes, threads, messages, drafts, attachments, lists, apps, and sign-up; pod management, domain setup, and webhook registration are not in it.

Those operations stay on the REST API and SDKs. If your agent needs multi-tenant pod isolation, domain setup, or message.received webhook registration, call the SDK from application code or a skill, not from the MCP tool list alone.

Free has no custom domains. Custom domains start on Developer ($20/month, 10 domains). MCP itself is on Free, so you can install and run the first loop without paying. You cannot put the lab inbox on your own domain until you upgrade.

OAuth consent picks one organization. If you chose the wrong org, disconnect the connector and connect again so the consent screen can offer a different org (MCP troubleshooting).

API key errors usually mean a revoked key or a missing am_ prefix. Regenerate under console Settings, then API Keys.

Unverified programmatic signups can only send to the signup address until agent.verify succeeds (agent onboarding). Complete OTP before you ask the agent to mail external recipients.