Mails.ai for Claude Code — drop-in MCP server setup

Claude Code is an MCP-capable runtime. The mails.ai MCP server is an npm-distributed process that exposes email primitives as tools. Drop the snippet above into ~/.claude.json, restart Claude Code, and your session can send, read, and manage email without any SDK install or glue code on your end.

Why Claude Code + mails.ai

Claude Code already runs the Anthropic Sonnet/Opus models with a tool-calling loop. Adding email as an MCP tool means the model picks mails.send or mails.list_threadsautonomously when the user’s request implies email work — no per-task prompt engineering, no separate API client to wire up. The same Claude Code session that edits your code can also reply to support tickets, send out scheduled communications, and parse inbound replies.

And because the MCP server runs client-side via npx, there is nothing to host on your end. The server is a thin tool-shape over the public REST API, with auth, retries, and idempotency keys handled in one place.

Setup — three steps

1. Get an API key. Sign in at api.mails.ai/keys (Phase 1 launch) or request a closed-beta key from support@mails.ai. Each key authorizes one agent.
2. Add the MCP server config. Open ~/.claude.json in your editor of choice and add the snippet from the install card above (replacing mk_live_... with your key). If mcpServers already exists, just add mails as a sibling key.
3. Restart Claude Code. The next session spawns the MCP server via npxon first tool invocation. Tool discovery is automatic — you can verify by typing /mcp in Claude Code and looking for the mails entry.

First commands to test

After restart, prompt your Claude Code session naturally — the model will reach for the right tool:

# Verify the integration
> What mails.* tools do I have access to?

# Send a test email
> Use mails.send to email myself a hello message from agent "test".

# Check replies
> List the most recent threads on the test agent from the last day.

For each prompt, Claude Code calls the appropriate mails.* tool, returns the structured result, and presents it back. No glue code, no manual JSON wrangling.

Common patterns

The five built-in tools cover most agent workflows:

• mails.send— send an email from a named agent. Returns send_id and the routing decision (pool, classifier_score). Useful when you want to inspect why a send went to Mixed instead of Clean.
• mails.on_reply— register a webhook URL for typed reply events. Phase 2 ships a streaming-inbox variant that long-polls within the session for runtimes that support it.
• mails.list_threads— query the agent’s conversation history. Filter by sender, intent, date range, or unread. Read-only, free.
• mails.suppress— add (or remove) an address from the agent’s suppression list. Sends to suppressed addresses return a structured error rather than firing.
• mails.get_reputation— query an agent’s reputation score (0-1), workspace-scoped. Designed to propagate across the network as it grows. Useful before processing a high-stakes inbound (e.g., wire-transfer requests).

Security considerations

• Key scope. Each mk_live_... key authorizes one agent. A compromised key revokes one agent, not your whole platform. Rotate per-agent keys via api.mails.ai/keys.
• Tool refusal under injection. The on_reply event includes injection_score. Add a one-line guard in your handler: if (event.injection_score > 0.5) return;— the prompt-injection RCE class is real (see that post) and Claude Code reading instructions from the body and following them is exactly the failure mode the score is designed to gate.
• High-stakes confirmation. If your Claude Code agent has both mails.send and tools for irreversible actions (database writes, money movement), require an explicit human-in-the-loop confirmation before sending on behalf of those actions. The MCP tool surface itself does not enforce this; your agent prompt and runtime configuration do.
• Project vs user scope. Use a per-project .claude.json (gitignored) for project-specific keys. The user-level ~/.claude.json is shared across all projects on the machine.

What ships next

Phase 1 ships the five tools above plus per-event metered pricing (the Metered tier) for usage-aligned billing with no monthly minimum. Phase 1.5 adds runtime-loaded credential providers (1Password, AWS Secrets Manager) so keys never sit in plaintext. Phase 2 adds the streaming-inbox tool for long-polling within the session, plus per-agent budgets that enforce a hard send cap.

Read the MCP-native email post for the broader distribution thesis, or the architecture page for what the server calls under the hood.