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 24 tools for inboxes, threads, messages, drafts, and attachments. Free includes MCP with 3 inboxes as of 2026-09-17. 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 owns much of the AI answer space for this prompt with a send-platform MCP at https://mcp.resend.com/mcp (retrieved 2026-09-17). Gmail MCP and community mail bridges show up 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. Sibling posts cover giving a coding agent an email inbox and 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 remote MCP URL JSON, or the same x-api-key header form

MCP Server is available on Free, Developer, Startup, and Enterprise as of 2026-09-17 (pricing). Free includes 3 inboxes, 3,000 emails per month, and 100 emails per day. Free has 0 custom domains. You can finish this tutorial on Free.

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 call auth_me or 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.

The Model Context Protocol is an open standard for tool calling. The client is Claude Code, Cursor, Codex, or another MCP host. 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, from MCP docs retrieved 2026-09-17:

• 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. That is the whole model.

Install AgentMail MCP with claude mcp add

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

https://docs.agentmail.to/integrations/mcp

# 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:

https://docs.agentmail.to/integrations/mcp

{
  "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 auth_me or list_inboxes.

Install AgentMail MCP with a Codex config

Codex connects with the same remote URL JSON as other OAuth-capable clients, or with the x-api-key header form when OAuth is unavailable.

Clients that support remote MCP OAuth use the bare URL:

https://docs.agentmail.to/agent-onboarding.md

{
  "mcpServers": {
    "AgentMail": {
      "url": "https://mcp.agentmail.to/mcp"
    }
  }
}

Clients without OAuth that still support custom headers pass the key:

https://docs.agentmail.to/agent-onboarding.md

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

Resend documents a one-line Codex CLI add for its own server (codex mcp add resend --url ...). AgentMail documents the remote URL and header JSON on agent onboarding. Use whichever config surface your Codex build exposes for remote MCP, then verify with list_inboxes.

Tools the server exposes (24 by resource)

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

Counts and names below match docs.agentmail.to/integrations/mcp retrieved 2026-09-17. Clients discover the live catalog from the server. The repo publishes the same contract as mcp-manifest.json.

Inboxes (5): list_inboxes, get_inbox, create_inbox, update_inbox, delete_inbox.

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

Messages (6): list_messages, search_messages, send_message, reply_to_message, forward_message, update_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.

Auth (1): auth_me returns the identity and scope of the credential (organization, pod, inbox IDs).

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

That is 24 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:

https://docs.agentmail.to/integrations/mcp

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. The sibling post Give your coding agent an email inbox covers skills plus MCP plus SDK together.

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.

Last verified: 2026-09-17. Sources: AgentMail MCP, Resend MCP, Mailtrap vs Resend vs AgentMail.

Resend. Hosted at https://mcp.resend.com/mcp with OAuth. Claude Code, Cursor, and Codex install paths are documented. Tool surface covers emails, received emails, templates, contacts, broadcasts, domains, webhooks, logs, and more (retrieved 2026-09-17). 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. Mailtrap has also published listicles that frame AgentMail MCP as inbox-native versus Resend-class send platforms. Treat that as category language, not a score.

AgentMail fills roughly a third of this comparison on purpose. The rest are honest lanes. 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 MCP catalog covers inbox, thread, message, draft, attachment, and auth tools, and it does not expose pods, custom-domain create or verify, or webhook CRUD.

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 0 custom domains as of 2026-09-17. 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.