MCPInstall

agentmail-mcp

by agentmail-toAI & Agents

Configure or troubleshoot the hosted AgentMail MCP server for Codex, Claude Code, Cursor, Claude.ai, ChatGPT, 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, check, or manage mail — use the sibling action skills for that.

Installs
1.1K
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/agentmail-to/agentmail-skills --skill agentmail-mcp
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads agentmail-mcp automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

AgentMail MCP

Prefer the hosted Streamable HTTP server:

https://mcp.agentmail.to/mcp

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.

{
  "mcpServers": {
    "agentmail": {
      "type": "http",
      "url": "https://mcp.agentmail.to/mcp"
    }
  }
}

Claude Code can also install it directly:

claude mcp add --transport http agentmail https://mcp.agentmail.to/mcp

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:

{
  "mcpServers": {
    "agentmail": {
      "type": "http",
      "url": "https://mcp.agentmail.to/mcp",
      "headers": {
        "x-api-key": "${env:AGENTMAIL_API_KEY}"
      }
    }
  }
}

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.

FAQ

What does the agentmail-mcp skill do?

Configure or troubleshoot the hosted AgentMail MCP server for Codex, Claude Code, Cursor, Claude.ai, ChatGPT, 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, check, or manage mail — use the sibling action skills for that.

How do I install agentmail-mcp?

Run npx skills add https://github.com/agentmail-to/agentmail-skills --skill agentmail-mcp in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/agentmail-mcp/ (personal) or .claude/skills/agentmail-mcp/ (project).

Which AI agents can use agentmail-mcp?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is agentmail-mcp safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains agentmail-mcp?

It is published by agentmail-to in agentmail-to/agentmail-skills. It has 1,146 recorded installs.

More from agentmail-to/agentmail-skills

View all →

agentmail

agentmail-to/agentmail-skills

Build with the AgentMail TypeScript or Python SDK for inbox, message, thread, draft, attachment, domain, allow/block list, pod, webhook, and WebSocket workflows, including programmatic agent sign-up, domain/DNS administration, and deliverability triage (bounces, spam, blocked mail). Use when implementing or reviewing AgentMail API code; do not use for direct mailbox operations, CLI usage, MCP setup, or framework-toolkit integration.

Backend & APIs2.9K installs

agentmail-cli

agentmail-to/agentmail-skills

Operate AgentMail from a shell with the official CLI. Use when the user wants commands for listing or creating inboxes, reading or searching mail, sending or replying, managing drafts, or scripting JSON/YAML output; do not use for SDK code, MCP setup, or framework adapters.

AI & Agents1.7K installs

agentmail-toolkit

agentmail-to/agentmail-skills

Add AgentMail tools to agent frameworks with the TypeScript or Python AgentMail Toolkit. Use for Vercel AI SDK, LangChain, OpenAI Agents SDK, LiveKit Agents, or MCP adapters; do not use for direct mailbox operations, raw SDK implementation, CLI usage, or MCP client setup.

AI & Agents1K installs

agent-email-patterns

agentmail-to/agentmail-skills

Architecture patterns for AI agents that communicate over email -- why agents need dedicated inboxes rather than human email accounts, infrastructure/provider tradeoffs, one-inbox-per-agent, two-way conversation loops, human-in-the-loop drafts, WebSocket vs webhook event design, multi-agent topologies, OTP flows, and the threat model (prompt injection, webhook spoofing, credential exposure, data leakage). Use when designing how agents send, receive, and manage email conversations, evaluating whether an agent needs email, or choosing an email provider; do not use for AgentMail SDK method calls or basic send/receive implementation.

Productivity & Automation856 installs

email-for-ai-agents

agentmail-to/agentmail-skills

Deprecated alias of the agent-email-patterns skill, kept so existing installs and pinned URLs keep resolving. Prefer installing agent-email-patterns; this is an identical generated copy covering agent email architecture, security, and provider tradeoffs.

Productivity & Automation805 installs

agentmail-sdk

agentmail-to/agentmail-skills

Deprecated alias of the agentmail skill, kept so existing installs and pinned URLs keep resolving. Prefer installing agentmail; this is an identical generated copy covering AgentMail SDK usage in TypeScript and Python.

Code Quality & Workflow750 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs