MCP and Skills

Configure the MCP server

The hosted server is a Streamable HTTP endpoint at https://mcp.agentmail.to/mcp. It accepts two credentials:

• OAuth: the client opens the AgentMail sign-in the first time it connects. Nothing to configure and no key to store.
• API key: the client sends your key as an x-api-key header, or as Authorization: Bearer am_... if it only supports authorization headers.

Most JSON-configured clients take an entry like one of these. Field names vary a little by client, and the platform pages above show real variants:

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

Clients with a connector UI, such as Claude Desktop, take https://mcp.agentmail.to/mcp as a custom connector instead. Keep the API key in a header or an ${env:...} reference rather than in the server URL, where it would end up in logs.

To test the connection, ask the client to list your AgentMail inboxes. A connected server returns the inbox list.

MCP tool reference

A few behaviors to know before your agent relies on these tools:

• search_threads and search_messages rank results by relevance and exclude spam and trash.
• update_thread and update_message add and remove labels. System labels such as sent and received cannot be modified.
• 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, the agent submits 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.

For webhooks, domains, pods, and API keys, use the CLI or an SDK.

Run a local MCP server

The stdio bridge is for clients that launch a local process but cannot reach a remote server or send custom headers. Run it with npx -y agentmail-mcp (Node) or uvx agentmail-mcp (Python), with your API key in the bridge’s process environment:

{
  "mcpServers": {
    "agentmail": {
      "command": "npx",
      "args": ["-y", "agentmail-mcp"],
      "env": {
        "AGENTMAIL_API_KEY": "am_..."
      }
    }
  }
}

The bridge is a transport, not a second implementation. It discovers the tool catalog above from the hosted server and forwards every call there, so local and remote behave the same. To expose only some tools to the client, 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.

Skills

The AgentMail skill packages email workflows as instructions your coding agent discovers and follows. You may already have it:

• The OpenClaw plugin installs it along with an inbound email channel. That page covers the channel setup.
• The plugin marketplace bundles it, so the Codex and Claude Cowork plugin installs come with the skill.

On any other host that reads SKILL.md files, install it with skills.sh:

npx skills add agentmail-to/agentmail-skills

The installer lists the repository’s skills and the agents it detects on your machine. Name both to skip the prompts. This form installs the core skill for Claude Code:

npx skills add agentmail-to/agentmail-skills --skill agentmail --agent claude-code

Set AGENTMAIL_API_KEY in that host’s environment. The skill’s workflows authenticate with it.

Next Steps