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

The server exposes 17 tools, grouped by resource.

Inboxes

ToolDescription
list_inboxesList inboxes in the organization.
get_inboxGet a single inbox by ID.
create_inboxCreate a new inbox.
delete_inboxDelete an inbox.

Threads

ToolDescription
list_threadsList threads in an inbox.
get_threadGet a thread and its messages.

Messages

ToolDescription
send_messageSend a new message from an inbox.
reply_to_messageReply to an existing message.
forward_messageForward a message to another recipient.
update_messageUpdate a message, for example to change its labels.

Drafts

ToolDescription
create_draftCreate a draft. Set send_at (ISO 8601) to schedule it.
list_draftsList drafts in an inbox. Filter by label, for example scheduled.
get_draftGet a draft, including its content and scheduled send time.
update_draftUpdate a draft. Use send_at to reschedule a scheduled draft.
send_draftSend a draft immediately.
delete_draftDelete a draft. Also cancels a scheduled send.

Attachments

ToolDescription
get_attachmentGet an attachment by ID.

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