# MCP and Skills (/integrations/mcp-and-skills) Related: [SDKs and CLI](/integrations/sdks-and-cli.md), [Marketplaces and provisioning](/integrations/marketplaces.md), [Send & Receive Emails with Claude Cowork](/integrations/frameworks/claude-cowork.md) # Connect an MCP client to AgentMail's hosted email tools AgentMail runs a hosted MCP server that gives any MCP-capable client tools over inboxes, threads, messages, drafts, and attachments, and ships a skill for hosts that read `SKILL.md` files. Use the server when an agent should operate email as tools rather than through code. ## Do this Add the hosted server to the client's MCP configuration. Field names vary a little by client: ```json { "mcpServers": { "agentmail": { "url": "https://mcp.agentmail.to/mcp", "headers": { "x-api-key": "${env:AGENTMAIL_API_KEY}" } } } } ``` Omit the `headers` block to use OAuth instead, in which case the client opens the AgentMail sign-in on first connect. In Claude Code, run `claude mcp add --transport http agentmail https://mcp.agentmail.to/mcp`. Then ask the client to list AgentMail inboxes. A connected server returns the inbox list. ## Facts * The hosted server is a Streamable HTTP endpoint at exactly `https://mcp.agentmail.to/mcp`. * Accepted credentials: OAuth (browser sign-in on first use, nothing to configure, no key to store), or an API key sent as an `x-api-key` header, or as `Authorization: Bearer am_...` when the client only supports authorization headers. * API keys start with `am_` and must be configured complete, prefix included. * Keep the key in a header or an `${env:...}` reference, never in the server URL, where it would end up in logs. * Clients with a connector UI, such as Claude Desktop, take `https://mcp.agentmail.to/mcp` as a custom connector. * Inbox tools: `list_inboxes`, `get_inbox`, `create_inbox`, `update_inbox`, `delete_inbox`. * Thread tools: `list_threads`, `search_threads`, `get_thread`, `update_thread`, `delete_thread`. * Message tools: `list_messages`, `search_messages`, `send_message`, `reply_to_message`, `forward_message`, `update_message`. * Draft tools: `create_draft`, `list_drafts`, `get_draft`, `update_draft`, `send_draft`, `delete_draft`. * Attachment tool: `get_attachment`. Agent sign-up tool: `agent_verify`. Organization tools: `list_organizations`, `select_organization`. * `search_threads` and `search_messages` rank results by relevance and exclude spam and trash. * `update_thread` and `update_message` add and remove labels. * `send_draft` sends immediately, converting the draft to a sent message and deleting it. `delete_draft` on a scheduled draft cancels the scheduled send. * `get_attachment` returns the attachment's metadata and a download URL, plus extracted text for PDF and DOCX files. * `agent_verify` finishes agent self sign-up. When a plan-cap error asks for verification, submit the 6-digit code emailed at sign-up to lift the unverified organization's limits. * `list_organizations` and `select_organization` apply to OAuth sessions. A user in several organizations uses them to pick which one every other tool acts on. * Local stdio bridge, for clients that launch a local process but cannot reach a remote server or send custom headers: `npx -y agentmail-mcp` (Node) or `uvx agentmail-mcp` (Python), with `AGENTMAIL_API_KEY` in the bridge's process environment. * The bridge is a transport, not a second implementation. It discovers the tool catalog from the hosted server and forwards every call there, so local and remote behave the same. * To expose only some tools through the bridge, append `--tools` with a comma-separated list, for example `"args": ["-y", "agentmail-mcp", "--tools", "list_inboxes,get_thread"]`. The bridge then filters the catalog and rejects calls outside it. * Skill install on any host that reads `SKILL.md` files: `npx skills add agentmail-to/agentmail-skills`. The installer lists the repository's skills and the agents it detects, and naming both skips the prompts: `npx skills add agentmail-to/agentmail-skills --skill agentmail --agent claude-code` installs the core skill for Claude Code. * The skill's workflows authenticate with `AGENTMAIL_API_KEY` set in that host's environment. * The OpenClaw plugin installs the skill along with an inbound email channel. The Codex and Claude Cowork plugin installs bundle the skill through the plugin marketplace. ## Not supported * No MCP tools exist for webhooks, domains, pods, or API keys. Use the CLI or an SDK for those. * System labels such as `sent` and `received` cannot be modified by `update_thread` or `update_message`. * The tool catalog has no sign-up tool. `agent_verify` only finishes a sign-up started elsewhere. * The stdio bridge adds no behavior of its own. Every call is forwarded to the hosted server. ## Errors | Error | HTTP status | Cause | Fix | | ------------------------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | | Not found | 404 | The server URL is incorrect. | The endpoint is exactly `https://mcp.agentmail.to/mcp`. | | Connection test fails with OAuth | - | The browser sign-in was not finished. | Finish the sign-in, and pick an organization if you belong to more than one. | | Connection test fails with an API key | - | The configured process holds an incomplete key. | Configure the complete key, including its `am_` prefix. | ## Verify Ask the client to list your AgentMail inboxes. A connected server returns the inbox list. ## Related * `/quickstart` - get an API key first. * `/integrations/sdks-and-cli` - typed SDK calls and CLI commands for everything beyond the MCP catalog, including webhooks, domains, pods, and API keys. * `/advanced/webhooks` - get called the moment new mail arrives instead of polling. * Platform setup pages with real config variants: `/integrations/frameworks/codex`, `/integrations/frameworks/claude-cowork`, `/integrations/frameworks/cursor`, `/integrations/frameworks/devin`, `/integrations/frameworks/openclaw`, `/integrations/frameworks/grok`, `/integrations/frameworks/hermes`, `/integrations/frameworks/replit`, `/integrations/frameworks/sim`.