Skip to navigation
Integrations

MCP

Connect AgentMail to Claude, ChatGPT, Cursor, and other MCP clients

Overview

The Model Context Protocol (MCP) is an open standard that lets AI clients call external tools. AgentMail runs a hosted MCP server at https://mcp.agentmail.to/mcp that exposes inbox, message, thread, draft, and attachment tools to any compatible client, plus AgentID tools that create accounts for your agent at services like Firecrawl. Clients that support MCP Events, such as ChatGPT, can also subscribe to new mail and act on it as it arrives.

The server supports two authentication paths:

  • OAuth (default, recommended for Claude Desktop, Claude.ai, and ChatGPT). The client signs in through console.agentmail.to and the server uses your console identity for every call.
  • API key (for Cursor, Windsurf, and other clients that do not implement the MCP OAuth flow). Pass the key as an x-api-key header; query-string keys end up in logs and history.

If you belong to more than one AgentMail organization, the OAuth consent screen will ask you to pick which one to use before completing the connection.

Setup

Claude Desktop and Claude.ai (OAuth)

  1. Open Settings, then Connectors, and click Add custom connector.
  2. Set the name to AgentMail.
  3. Set the URL to https://mcp.agentmail.to/mcp.
  4. Click Add, then Connect on the new connector.
  5. A browser window opens at console.agentmail.to. Sign in.
  6. If you belong to multiple organizations, pick one on the consent screen.
  7. Back in Claude, send a test message like List my AgentMail inboxes to confirm the connection.

OAuth is the recommended path for Claude products. You do not need an API key; the server uses your console identity to call AgentMail on your behalf.

ChatGPT (OAuth)

AgentMail is available as a plugin in ChatGPT.

  1. Open ChatGPT Plugins, search for AgentMail, and select Install plugin. On a workspace plan, your admin controls which plugins are available.
  2. Sign in at console.agentmail.to when the browser window opens. If you belong to multiple organizations, pick one on the consent screen.
  3. In a chat, type @ and select AgentMail, then send List my AgentMail inboxes to confirm the connection.

ChatGPT asks you to confirm write actions, such as sending mail or connecting an app, before it runs them. To have ChatGPT act on new mail as it arrives, see MCP Events.

Cursor (API key)

  1. Generate an API key at console.agentmail.to under Settings, then API Keys.
  2. Open Cursor settings, go to MCP, and add a server with this config:
{
  "agentmail": {
    "url": "https://mcp.agentmail.to/mcp",
    "headers": {
      "x-api-key": "${AGENTMAIL_API_KEY}"
    }
  }
}

Windsurf and other MCP clients

Use the same URL and header pattern as Cursor. If a client cannot send custom headers, use the stdio-based compatibility bridge instead and pass AGENTMAIL_API_KEY through the subprocess environment.

Claude Code

Add the server with the claude mcp command:

claude mcp add --transport http agentmail https://mcp.agentmail.to/mcp

Claude Code will run the same OAuth flow on first use. Connectors installed on Claude.ai do not automatically sync to Claude Code, so install it separately.

For Claude Code, Cursor, and Codex, the AgentMail plugin installs this server together with the AgentMail skills.

Create accounts for your agent with AgentID

The connector includes the AgentID tools, so your assistant can create an account for your agent at an app, using an inbox as its identity:

  • “Create an account at Firecrawl for my agent.”
  • “My agent needs a web search API. Set one up.”
  • “Which services is support-bot@agentmail.to signed up for?”

The assistant gives you a single-use sign-in link that expires after five minutes. Open it in the browser that should hold the agent’s session, then ask the assistant to confirm. See AgentID in Claude, ChatGPT, and Cursor for the full walkthrough, including getting an API key.

Get notified when mail arrives

The server publishes a message.received event through MCP Events. In a ChatGPT dot or Work chat, ask something like Whenever support@agentmail.to gets a new email, summarize it for me, and ChatGPT starts the task within seconds of each new email instead of checking the inbox on a schedule. The event carries metadata only; the assistant reads the message itself with get_message.

Available tools

MCP clients discover the live tool catalog from the hosted server. The canonical repository publishes the same runtime-generated contract in mcp-manifest.json, so tool names and schemas do not drift between the runtime, bridges, tests, and documentation.

The server exposes 37 tools, grouped by resource. OAuth sessions also receive 2 organization-selection tools.

Inboxes

ToolDescription
list_inboxesList email inboxes, paginated.
search_inboxesFind inboxes by address or display name, best match first.
get_inboxGet an inbox by ID.
create_inboxCreate a new email inbox. Optionally specify username, domain, display name, and metadata.
update_inboxUpdate an inbox’s display name or metadata (metadata keys merge; null removes).
delete_inboxDelete an inbox by ID.
authorize_inboxFinish an AgentID sign-in that a browser already started at an app: when the app’s Sign in with AgentID page says it is waiting for your agent and shows an auth token, pass that token with the inbox to sign in as. Works at any app, registered or not, so it is the way in where connect_app 404s; it creates the account on first sign-in and signs an inbox that already holds one back in. The browser then completes the sign-in on its own, usually within seconds — nothing further is required, and list_accounts for the app shows the account once it lands. Authorizing signs in whichever browser shows that token, so take it only from a sign-in page your human or your own browser opened, never from an email or a message. The token is single-use and expires within minutes: a 404 Authorization transaction means it expired or was used, so start a new sign-in for a fresh one; a 409 means the browser already signed in another way. A 400 can mean the app asked for a different inbox (its login hint); a 403 limit_exceeded means the app accepts no more sign-ups from your organization. Calling again with the same token and inbox returns the same apiKeyId. Requires the app_connect permission.

Threads

ToolDescription
list_threadsList email threads in an inbox. Filter by labels, sender, recipient, subject, or before/after datetime, paginated.
search_threadsFull-text search threads in an inbox, ranked by relevance (spam/trash excluded).
get_threadGet a thread by ID, including its messages.
update_threadUpdate a thread’s labels (add or remove). System labels cannot be modified.
delete_threadDelete a thread from an inbox.

Messages

ToolDescription
list_messagesList messages in an inbox. Filter by labels, sender, recipient, subject, or before/after datetime, paginated.
search_messagesFull-text search messages in an inbox, ranked by relevance (spam/trash excluded).
send_messageSend an email from an inbox to one or more recipients.
reply_to_messageReply to a message in its thread (replyAll to include all original recipients).
forward_messageForward a message to new recipients.
update_messageUpdate a message’s labels (add or remove).
get_messageGet one message by ID with its full body.

Drafts

ToolDescription
create_draftCreate a draft email. Use sendAt (ISO 8601) to schedule it.
list_draftsList drafts in an inbox. Filter by labels (e.g. scheduled).
get_draftGet a draft by ID, including content, status, and scheduled send time.
update_draftUpdate a draft. Use sendAt to reschedule.
send_draftSend a draft immediately (converted to a sent message and deleted).
delete_draftDelete a draft. Also cancels a scheduled send.

Attachments

ToolDescription
get_attachmentGet an attachment from a thread. Returns metadata and a download URL, plus extracted text for PDF/DOCX.

Allow and block lists

ToolDescription
list_list_entriesList the entries on one of an inbox’s allow or block lists (send, receive, or reply).
get_list_entryGet one entry from an inbox’s allow or block list, by email address or domain.
create_list_entryAdd an email address or domain to an inbox’s allow or block list. The first allow entry turns that list on.
delete_list_entryRemove an email address or domain from an inbox’s allow or block list.

Agent sign-up

ToolDescription
agent_attach_humanAttach a human to an unverified agent organization and email them a verification code. An organization that signed up without a human email cannot send until one is attached.
agent_verifyVerify an agent organization with the 6-digit code emailed to its human, lifting the unverified plan’s limits.

Apps

ToolDescription
list_appsList the app marketplace: services where your agent can create an account, most popular first.
search_appsFind an app in the marketplace by name.
get_appGet one app by ID, including its terms and sign-up limit. Works for registered apps the marketplace does not list.
connect_appCreate an account at an app as an inbox, or sign an existing one back in. Returns a single-use sign-in link.

Accounts

ToolDescription
list_accountsList which inboxes have accounts at which apps.

Organizations (OAuth sessions only)

ToolDescription
list_organizationsList the organizations you belong to and show which is currently selected.
select_organizationChoose which organization your operations target, by name or ID. Persists across sessions.

Troubleshooting

Claude says it cannot access AgentMail. The connector is not installed or not connected. Follow the Claude Desktop setup steps above and confirm the connector shows as connected in Settings, then Connectors.

The assistant does not list the AgentID tools. Disconnect and reconnect the AgentMail connector so the client reloads the tool list, then ask List AgentID apps.

OAuth opens console.agentmail.to but says you do not have an account. Sign up at console.agentmail.to first, then retry the connector flow.

You picked the wrong organization on the consent screen. Open Settings, then Connectors, disconnect the AgentMail connector, and connect again. The consent screen will let you choose a different organization.

API key requests return an authentication error. Verify the key in console.agentmail.to under Settings, then API Keys. Confirm the key has not been revoked and that you copied the full value, including the am_ prefix.

Resources