Configure or troubleshoot the hosted AgentMail MCP server for Codex, Claude Code, Cursor, or another Streamable HTTP MCP client. Use for installation, OAuth, API-key headers, connection failures, or MCP tool discovery. Do not use when the connection already works and the user just wants to send, che

AgentMail MCP Prefer the hosted Streamable HTTP server: It avoids a local Node.js process and the slower release cadence of the published local MCP package. Claude Code, Codex, and Cursor Use OAuth. Do not put an empty API key in the configuration. Claude Code can also install it directly: Complete the browser sign in on first connection. Multi organization OAuth sessions can use the server's organization selection tools. Claude.ai, Claude Desktop, and ChatGPT connectors These apps add the server as a connector and complete OAuth in the browser. No API key is needed. Claude.ai and Claude Desktop: Settings → Connectors → Add custom connector. Name it AgentMail , set the URL to https://mcp.agentmail.to/mcp , then click Connect and sign in at console.agentmail.to . ChatGPT: turn on Settings → Security and login → Developer mode (on a workspace plan, an admin must allow it first). Then open ChatGPT Plugins, click +, set the URL to https://mcp.agentmail.to/mcp , choose OAuth, and sign in at console.agentmail.to . In a chat, pick AgentMail from the + menu under Developer mode. Connectors added on Claude.ai do not sync to Claude Code; add it there separately. Per client configuration Add the same type: http server entry to the client's MCP config file: Cursor: .cursor/mcp.json VS Code: .vscode/mcp.json Windsurf: its MCP config file Claude Desktop: ~/Library/Application Support/Claude/claude desktop config.json (macOS) or %APPDATA%/Claude/claude desktop config.json (Windows) Auth options OAuth — browser based sign in, for clients that support remote MCP OAuth. Use the bare URL with no credentials. x api key header — recommended for clients without OAuth support (see below). Authorization: Bearer <am ... header — an alternative header form some clients require. apiKey query param — supported but not recommended; prefer a header so the key doesn't end up in logs or history. For a Streamable HTTP client that cannot complete OAuth, export AGENTMAIL API KEY and send it as a header: Avoid query string credentials when header authentication is available. Tool Discovery MCP clients get the tool catalog and schemas live from the hosted runtime; do not rely on a copied tool count. The same generated contract is published at https://github.com/agentmail to/agentmail mcp/blob/main/mcp manifest.json — treat the hosted runtime plus that manifest as the authoritative catalog. OAuth sessions can surface extra organization selection tools beyond the base set. The catalog covers more than mail. Point users at these groups when they ask what the connector can do: Inboxes, threads, messages, drafts, attachments, and allow/block lists — the mail workflows in the sibling action skills. AgentID apps and accounts — list apps , search apps , get app , connect app , authorize inbox , and list accounts create accounts for an agent at third party apps (for example "create an account at Firecrawl") and show where each inbox already has one. authorize inbox finishes a sign in that an app's Sign in with AgentID page started, using the auth token the page shows, including at apps not registered with AgentID. Catalog apps can be named by slug ( firecrawl ), and list apps filters by category. Use the agentmail agentid skill for that workflow. Agent sign up — agent attach human and agent verify lift an unverified agent organization's limits. Stdio Compatibility For a stdio only client, use the supported npm or PyPI agentmail mcp package. Both are thin stdio bridges to the same hosted runtime: they discover tools dynamically and carry no separate AgentMail tool logic of their own. Verify 1. Restart the client or open a new session after installing the plugin. 2. Inspect MCP status in the client and complete authentication. 3. Call list inboxes as a read only smoke test. Call list apps to confirm the AgentID tools are exposed. 4. Confirm that read, write, and destructive tool annotations produce the expected approval behavior. Troubleshoot A 404 usually means the URL is missing /mcp . A tool or parameter in the published manifest is missing from the session (for example list apps has no category ): the hosted server does not announce catalog changes, so a session keeps the tool list it had at connect. Start a new session or reconnect the connector. "Invalid API key" or a 401 with API key auth usually means the key is wrong, revoked, lacks the necessary permissions, or AGENTMAIL API KEY was not available to the client process. "Unauthorized" or a 401 with OAuth usually means the sign in is incomplete or the session expired — drop any apiKey query param and let the client complete the browser based OAuth flow instead. Use the full am key value and prefer the narrowest suitable organization, pod, or inbox scope. For a stdio only client, see Stdio Compatibility above.

agentmail-mcp