Integrations

MCP

Connect AgentMail to Claude, 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.

The server supports two authentication paths:

  • OAuth (default, recommended for Claude Desktop and Claude.ai). 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 a ?apiKey= query parameter or an x-api-key header.

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.

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:
1{
2  "agentmail": {
3    "url": "https://mcp.agentmail.to/mcp?apiKey=YOUR_API_KEY"
4  }
5}

If your client supports custom headers, you can pass the key as a header instead of a query parameter:

x-api-key: YOUR_API_KEY

Windsurf and other MCP clients

Use the same URL and API key pattern as Cursor. Most clients accept either the ?apiKey=YOUR_API_KEY query form or the x-api-key header.

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.

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 24 tools, grouped by resource. OAuth sessions also receive 2 organization-selection tools.

Inboxes

ToolDescription
list_inboxesList email inboxes, paginated.
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.

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).

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.

Auth

ToolDescription
auth_meGet the identity and scope of the authenticated credential (organization, pod, inbox IDs).

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.

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