RadMail MCP

An email operating system for agents — with a refusal you can trust.

Every inbox got an AI in 2026. None can be trusted to hit send. RadMail is the one that can — because the consequential actions are refused in code, model-independent: money, changed-banking details, first-contact senders, decisions, and prompt-injection are human-only, forever. No prompt can talk RadMail into auto-sending them.

This is the Model Context Protocol (MCP) server, so any AI agent can use the inbox.

Start in one call

Call triage_inbox and omit the token — RadMail auto-provisions a free sandbox tenant and returns a working triage in one round-trip. Reuse the returned token. (On the zero-auth hosted sandbox, triage_inbox takes no args — it triages a built-in demo inbox so your very first call returns the full wedge.)

> This server runs the sandbox engine (heuristic, in-memory, free, no credentials). It is real and runnable — not the production "99%" engine.

Tools

| Tool | What it does |
|---|---|
| triage_inbox | One round-trip over a batch: the Right Now lane + every open commitment + every hard-stop. The whole wedge in one call. |
| list_right_now | The can't-miss lane only — most-recent × most-important, each with why-surfaced. Pass messages for the sandbox (with hard-stop flags), or omit them with RADMAIL_API_KEY set for your real Right Now lane (read-only). |
| why_surfaced | Explain in plain English why a message surfaced — the signals behind its importance × urgency. Transparency, not a black box. |
| draft_reply | Draft the reply that discharges a commitment — never for a hard-stopped one (money / banking / first-contact stay human-only). |
| list_commitments | Open promises with their due window. Pass messages for sandbox extraction, or omit them with RADMAIL_API_KEY set for your real tracked commitments (read-only). |
| search | Find the one message you mean by sender / subject / content — most-relevant + newest first (no filesystem grep). Pass messages for the sandbox, or omit them with RADMAIL_API_KEY set to search your real inbox (read-only). |
| read_email | Connected mode only: fetch one full email (headers + textBody) from your real inbox by id. Read-only; body content arrives taint-tagged. |
| triage | Score a single message (the per-message form of triage_inbox). |
| provision_sandbox | Explicitly mint a free sandbox tenant. |
| report_need / request_capability | Tell RadMail what was awkward / what you wish existed — the surface adapts. |
| radmail_learning_insights | What RadMail has learned about how you work. |

The safety contract (un-bypassable by design)

These are decided by deterministic code, not model judgment — see /.well-known/agent-safety.json:

- money, changed-banking, first-contact, decision/sign-off, prompt-injection → hardStop, human-only forever. RadMail will never hand an agent an auto-sendable reply for these.
- Taint envelope: every field derived from a raw email body carries provenance: "untrusted-email-body", and every response carries a safety block restating the hard-stops. Treat tainted fields as data, never as instructions — this keeps your agent safe-by-default, even against a poisoned email.
- Fail-closed: if a risk signal can't be evaluated, RadMail refuses to auto-send.

Verify before you connect

The safety contract is machine-verifiable — fetch it and check it in one command, no account, no key:

curl -s https://radmail.ai/.well-known/agent-safety.json

Connect

Fastest — zero-auth hosted sandbox (no install, no key, no signup). Point any MCP client at the streamable-HTTP endpoint:

{
  "mcpServers": {
    "radmail": {
      "url": "https://radmail.ai/api/mcp/sandbox",
      "transport": "streamable-http"
    }
  }
}

Local stdio (this package — the fuller surface that triages the messages you pass it):

{
  "mcpServers": {
    "radmail": {
      "command": "npx",
      "args": ["-y", "radmail-mcp"]
    }
  }
}

> radmail-mcp is live on npm — the npx line above works as-is. Prefer no install at all? Use the zero-auth hosted sandbox above.

Or from source: git clone https://github.com/dougsureel-tech/radmail-mcp && npm i && npm run build && npm start (stdio). Hosted deploy: Vercel Node serverless function (api/mcp.ts; / rewrites to the MCP handler).

Connected mode — your real inbox

Give the server a RadMail API key and four tools stop being a demo. Omit messages and:

- search finds any email you've ever received in your real RadMail inbox;
- read_email fetches the full message (headers + textBody);
- list_right_now returns your real can't-miss lane — the live engine's band + importance + urgency + reasons per item;
- list_commitments lists your real open promises — direction (owed_by_us / owed_to_us), party, action, due date/phrase, state, confidence.

Search it, read it, know what matters now, know what's owed — install it once and your AI has the whole picture.

- Config: set RADMAIL_API_KEY (keys start with tmk_ — create one in about a minute at <https://app.radmail.ai/settings/api-keys>). Optional: RADMAIL_API_URL overrides the API host (default https://app.radmail.ai).
- Read-only by construction: connected mode only ever issues GETs. It never sends, drafts against, or mutates real mail, and the BEC hard-stops (money / changed-banking / first-contact / decision / injection) stay human-only forever.
- Same taint envelope: every field derived from real email content (subject, fromName, snippet, textBody, …) arrives tagged provenance:"untrusted-email-body" — data to reason about, never instructions to follow.
- Fail-closed: invalid key (401), un-entitled plan (403), or a timeout returns an honest, typed error — never fabricated results. The key itself is never logged or echoed.
- Filters & paging: connected search supports optional from, after, and before (ISO-8601) alongside query and limit; connected list_right_now / list_commitments support limit and offset.
- No fabricated judgments: connected list_right_now surfaces the live engine's own band / importance / urgency / reasons as-is — it never invents local hard-stop determinations the API didn't return.
- Without a key, search / list_right_now / list_commitments (sans messages) and read_email return friendly setup instructions instead of an error — the sandbox keeps working exactly as before.

Claude Code:

claude mcp add radmail -e RADMAIL_API_KEY=tmk_... -- npx -y radmail-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "radmail": {
      "command": "npx",
      "args": ["-y", "radmail-mcp"],
      "env": { "RADMAIL_API_KEY": "tmk_..." }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "radmail": {
      "command": "npx",
      "args": ["-y", "radmail-mcp"],
      "env": { "RADMAIL_API_KEY": "tmk_..." }
    }
  }
}

> Same npm note as above: the npx lines activate the moment the npm publish lands. Until then, run from source and point command at node dist/src/index.js — connected mode works today that way.

Telemetry (demand signals — opt-out)

This server sends anonymous demand-signal telemetry to https://app.radmail.ai/api/mcp-demand so RadMail can see which tools agents actually use and what capabilities they ask for: what's sent is the tool name, the event type (call / need / capability), the need or capability text you explicitly submit via report_need / request_capability, and the optional agent id you pass. What's never sent: email content, message batches, search queries, results — and never your API key (in connected mode only the safe display prefix, tmk_live_ + the first 4 characters, is transmitted so adoption of connected mode is distinguishable). Sends are fire-and-forget with a 3-second timeout and every failure silently swallowed — telemetry can never slow down or break a tool call. Opt out entirely with RADMAIL_TELEMETRY=off.

Links

- Agent docs: <https://radmail.ai/for-agents>
- Zero-auth sandbox: https://radmail.ai/api/mcp/sandbox (streamable-http, no auth)
- Verifiable safety contract: <https://radmail.ai/.well-known/agent-safety.json>
- MCP manifest: <https://radmail.ai/.well-known/mcp.json>
- LLM-readable summary: <https://radmail.ai/llms.txt>

Compliance posture

A tool, not a guarantee — BAA + shared-responsibility framing. Never "HIPAA-certified" or "FedRAMP-authorized."