> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.agentmail.to/llms.txt. For full content including API reference and SDK examples, see https://docs.agentmail.to/llms-full.txt.

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

### Cursor (API key)

1. Generate an API key at [console.agentmail.to](https://console.agentmail.to) under **Settings**, then **API Keys**.
2. Open Cursor settings, go to **MCP**, and add a server with this config:

```json
{
  "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](https://github.com/agentmail-to/agentmail-mcp) instead and pass `AGENTMAIL_API_KEY` through the subprocess environment.

### Claude Code

Add the server with the `claude mcp` command:

```bash
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`](https://github.com/agentmail-to/agentmail-mcp/blob/main/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

| Tool           | Description                                                                                |
| -------------- | ------------------------------------------------------------------------------------------ |
| `list_inboxes` | List email inboxes, paginated.                                                             |
| `get_inbox`    | Get an inbox by ID.                                                                        |
| `create_inbox` | Create a new email inbox. Optionally specify username, domain, display name, and metadata. |
| `update_inbox` | Update an inbox's display name or metadata (metadata keys merge; null removes).            |
| `delete_inbox` | Delete an inbox by ID.                                                                     |

### Threads

| Tool             | Description                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `list_threads`   | List email threads in an inbox. Filter by labels, sender, recipient, subject, or before/after datetime, paginated. |
| `search_threads` | Full-text search threads in an inbox, ranked by relevance (spam/trash excluded).                                   |
| `get_thread`     | Get a thread by ID, including its messages.                                                                        |
| `update_thread`  | Update a thread's labels (add or remove). System labels cannot be modified.                                        |
| `delete_thread`  | Delete a thread from an inbox.                                                                                     |

### Messages

| Tool               | Description                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `list_messages`    | List messages in an inbox. Filter by labels, sender, recipient, subject, or before/after datetime, paginated. |
| `search_messages`  | Full-text search messages in an inbox, ranked by relevance (spam/trash excluded).                             |
| `send_message`     | Send an email from an inbox to one or more recipients.                                                        |
| `reply_to_message` | Reply to a message in its thread (replyAll to include all original recipients).                               |
| `forward_message`  | Forward a message to new recipients.                                                                          |
| `update_message`   | Update a message's labels (add or remove).                                                                    |

### Drafts

| Tool           | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `create_draft` | Create a draft email. Use `sendAt` (ISO 8601) to schedule it.          |
| `list_drafts`  | List drafts in an inbox. Filter by labels (e.g. `scheduled`).          |
| `get_draft`    | Get a draft by ID, including content, status, and scheduled send time. |
| `update_draft` | Update a draft. Use `sendAt` to reschedule.                            |
| `send_draft`   | Send a draft immediately (converted to a sent message and deleted).    |
| `delete_draft` | Delete a draft. Also cancels a scheduled send.                         |

### Attachments

| Tool             | Description                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `get_attachment` | Get an attachment from a thread. Returns metadata and a download URL, plus extracted text for PDF/DOCX. |

### Auth

| Tool      | Description                                                                                |
| --------- | ------------------------------------------------------------------------------------------ |
| `auth_me` | Get the identity and scope of the authenticated credential (organization, pod, inbox IDs). |

### Organizations (OAuth sessions only)

| Tool                  | Description                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `list_organizations`  | List the organizations you belong to and show which is currently selected.                 |
| `select_organization` | Choose 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](https://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](https://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

* [AgentMail Console](https://console.agentmail.to) to manage API keys and organizations.
* [Support](/support) for help with installation or auth issues.
* [agentmail-mcp on GitHub](https://github.com/agentmail-to/agentmail-mcp) for the hosted server, compatibility bridges, and generated contract.