Agenticmail MCP

@agenticmail/mcp

The MCP (Model Context Protocol) server for AgenticMail — gives any MCP-compatible AI client full email and SMS capabilities.

When connected, your AI agent can send emails and texts, check inboxes, reply to messages, receive verification codes, manage contacts, schedule emails, assign tasks to other agents, and more — all through natural language. The server provides 100 tools that cover every email, SMS, and agent management operation.

✨ Security — 0.9.27

Fixes [GHSA-63gr-g7jc-v8rg](https://github.com/agenticmail/agenticmail/security/advisories/GHSA-63gr-g7jc-v8rg) — missing authentication on the optional Streamable HTTP transport (--http / MCP_HTTP=1).

• --http mode now binds to `127.0.0.1` by default and requires `Authorization: Bearer ` on every /mcp request.
• The bearer token is auto-minted on first start and persisted to ~/.agenticmail/mcp-http-token (chmod 600). Override with MCP_HTTP_TOKEN env or --token= .
• Bind to other interfaces with --host=0.0.0.0 or MCP_HTTP_HOST=... — startup logs an explicit warning when the endpoint is reachable from the network.
• --insecure brings back the old no-auth behavior for sandboxed test environments only. Startup prints a loud warning.
• Stdio mode (the default) was never affected.

If you weren't using --http / MCP_HTTP=1, no action is needed.

✨ What's new in 0.9.0

• 🧠 `get_thread_id` + `save_thread_memory` — two new tools in the multi_agent_extras tier. Workers call get_thread_id({uid}) once after reading a new message, then save_thread_memory({threadId, summary, commitments?, openQuestions?, lastAction?, lastUid?}) at end-of-wake. The dispatcher reads the memory back into the next wake's prompt automatically. Pairs with the dispatcher-side ThreadCache to flatten wake cost — agents no longer have to re-read 10 prior messages every time.
• 🎯 `send_email` / `reply_email` / `forward_email` / `template_send` docs updated for the new wake defaults. CC'd local agents no longer wake by default; wake: 'all' opts back into the pre-0.9.0 behaviour.

✨ Earlier — 0.7.9

• 📐 `call_agent` accepts `outputSchema` — pass a JSON Schema (draft-7 subset) describing the deliverable shape and the API validates submit_result against it; mismatches come back as validator errors so the worker can retry with a correct shape instead of returning free-form prose. The schema is rendered into the worker's wake prompt up-front. Example:

  await call_agent({

target: 'vesper', task: 'Audit row 34 of the YAML patch.', outputSchema: { type: 'object', required: ['summary', 'findings', 'recommendation'], properties: { summary: { type: 'string' }, findings: { type: 'array', items: { type: 'string' } }, recommendation: { type: 'string', enum: ['proceed', 'block'] }, }, }, });

- **📥 `tail_worker(workerId, lines?)`** — paired with `check_activity`. When a worker shows up as long-running or stale, `tail_worker` returns the trailing N lines of its log (every tool call, result, and assistant chunk as a one-liner). Master-key only. Lives in the `multi_agent_extras` tier so it ships in the default toolbelt for hosts that delegate work.

• 📊 `check_activity` shows live progress — output now includes last tool used, tool-call count, duration in Xh Ym Zs, and a stale flag derived from heartbeat age. Workers are no longer auto-evicted from the registry; staleness is diagnostic.

✨ Earlier — 0.7.7

• `wake` parameter on every send tool — send_email, reply_email, forward_email, template_send, manage_drafts(send) all accept wake: ["alice", "bob"] (or comma-separated string). The dispatcher gives a Claude turn only to listed agents; the rest still receive the mail but stay asleep. Single biggest token saver on multi-agent threads.
• `check_activity` tool (in the essential set) — see which agents the dispatcher has woken right now, what they're working on, how long they've been running, plus a preview of recently-finished work. Answers "did the agent I just emailed actually start working?" without waiting for a reply.
• Thread-close markers — put [FINAL], [DONE], [CLOSED], or [WRAP] in a subject to tell the dispatcher this thread is sealed; no more wakes on any reply to it. The wake prompt teaches agents to add these markers when they sign off the work.
• LLM-tolerant input coercion — batch_mark_read({ uids: "[1,2,3,4]" }), wait_for_email({ timeout: "120" }), manage_drafts({ where: '{"id":"abc"}' }), manage_pending({ allowSensitive: "true" }) all now just work. Strings get parsed before zod validates. No more "expected array, received string" retries.
• Server `instructions` field sent on initialize — every connecting MCP client (Claude Code, ChatGPT, Cursor, Grok…) gets the coordination protocol in context before they touch any tool. Provider-agnostic.
• `wait_for_email` filters — block on a specific reply, not just "any new event". Supports from, subject, inReplyTo, participants, includeTasks.

Install

npm install -g @agenticmail/mcp

Requirements: Node.js 22+, AgenticMail API server running

---

What This Package Does

This is the bridge between your AI client and the AgenticMail system. It runs as a subprocess that the AI communicates with through standard input/output (no network ports opened). Every tool call gets translated into an API request to the AgenticMail server, and the response comes back as formatted text the AI can understand.

Think of it this way: your AI agent doesn't know how to send email natively. This MCP server teaches it how by giving it a set of tools — "send_email", "list_inbox", "reply_email", and so on — that the AI can call when you ask it to do email-related tasks.

---

Setup

MCP Client Setup (CLI-Based)

Add to your MCP client configuration (e.g., .mcp.json or project settings):

{

"mcpServers": { "agenticmail": { "command": "npx", "args": ["-y", "@agenticmail/mcp"], "env": { "AGENTICMAIL_API_URL": "http://127.0.0.1:3829", "AGENTICMAIL_API_KEY": "ak_your_agent_key" } } } }

Desktop Clients

For desktop AI applications, add to your MCP configuration file. Example paths:

• macOS: ~/Library/Application Support/ /config.json
• Windows: %APPDATA%\ \config.json

{

"mcpServers": { "agenticmail": { "command": "npx", "args": ["-y", "@agenticmail/mcp"], "env": { "AGENTICMAIL_API_URL": "http://127.0.0.1:3829", "AGENTICMAIL_API_KEY": "ak_your_agent_key" } } } }

Environment Variables

¹ Either AGENTICMAIL_API_KEY OR AGENTICMAIL_MASTER_KEY (or AGENTICMAIL_ACCOUNT_KEYS_JSON) must be set, but you don't strictly need all three.

Optional Streamable HTTP transport (--http)

Most users should stick with the default stdio transport — that's what every MCP client config above uses. For environments that need a long-lived HTTP endpoint (browser-based clients, remote-development tunnels, multi-host setups), pass --http:

agenticmail-mcp --http                       # 127.0.0.1:8014, auth required

agenticmail-mcp --http --port=9001 agenticmail-mcp --http --host=0.0.0.0 # expose on network (token still required) agenticmail-mcp --http --token=mcphttp_xxx # use a known token instead of the minted one agenticmail-mcp --http --insecure # sandbox/test only — disables auth

The token is read from (in order): --token=... flag, MCP_HTTP_TOKEN env, ~/.agenticmail/mcp-http-token (auto-minted on first run). Clients must send Authorization: Bearer on every request to /mcp. GET /health stays open and returns only the session count.

Per-call identity switching (_account)

Every tool's input schema accepts an optional _account: " " parameter. When passed, the server resolves that name to an apiKey (from AGENTICMAIL_ACCOUNT_KEYS_JSON, then falling back to a live master-keyed lookup of /accounts) and runs the call as that agent. Without _account, the call uses AGENTICMAIL_API_KEY as the default identity.

This is what powers the @agenticmail/claudecode integration: one MCP server process, many AgenticMail identities. A Claude Code subagent that "is" Fola passes _account: "Fola" on every call and ends up reading Fola's real inbox, sending mail from fola@localhost, and so on.

Meta-tools for cheap discovery (request_tools + invoke)

To keep host context windows small, only ~10 of the 100 tools are pre-declared in a typical subagent's tools: whitelist. The other ~50 stay reachable through two always-on meta-tools:

• `request_tools({ query?, sets? })` — Returns a text catalogue of the unloaded tools, grouped by set (mail_extras, mail_compose, sms, account_admin, …). Optional substring filter or set-name filter.
• `invoke({ tool, args, _account? })` — Dispatches to any of the 100 tools by name. The agent uses request_tools to discover, invoke to call.

Token impact: a typical subagent spawn loads ~3K tokens of tool schemas instead of ~15K. The cost is one extra round trip for uncommon operations (discover → invoke), which is almost always a worthwhile trade.

---

How It Works

The MCP server sits between your AI and the AgenticMail API:

AI Client → MCP tool call → agenticmail-mcp → HTTP request → AgenticMail API → Stalwart Mail Server

Each tool call:

1. Receives structured arguments from the AI
2. Validates the input (UIDs must be positive integers, arrays must be non-empty, etc.)
3. Makes an HTTP request to the AgenticMail API with a 30-second timeout
4. Returns formatted text results back to the AI

The server runs with stdio transport — the AI client sends JSON-RPC messages via stdin, and the server responds via stdout. No network ports are opened by the MCP server itself. It shuts down gracefully on SIGTERM or SIGINT.

---

Tools

Email — Core Operations (13 tools)

| read_email | Read full email content with secu