@mailbuttons/mcp-server

@mailbuttons/mcp-server

The stdio Model Context Protocol server for the Mailbuttons governed Agent Mail API, plus the Claude Code skill that drives it. It gives an AI agent a small, honest set of email tools — list/read messages and threads, extract attachment text, send (under policy), and file escalation requests — all enforced by the Mailbuttons governance spine.

Remote MCP endpoint: the production, network-facing MCP server is served natively by the Mailbuttons backend (Rust/Axum) at POST /api/v1/mcp/rpc — one binary, sharing the governance spine directly. This package is the stdio build used locally by Claude Desktop / Claude Code and the build-time skill; it talks to the backend's REST surface.

Governance model

This server is sandbox-by-default and never lets an agent expand its own authority:

• A token can never widen its own scope. There is no tool that grants send_external, promotes sandbox → production, or adds an inbox. Escalation is only ever a request for human approval.
• External sends from sandbox tokens become drafts. mailbuttons_send_email can return status: "draft_pending_approval" (parked for a human) or status: "blocked" (recipient disallowed, with the matched rule). These are expected, normal outcomes — not errors. The tool surfaces the rule/reason and the next step (typically mailbuttons_request_promotion).
• Every tool call — including denials — is audited. Read the recent tail with mailbuttons_audit_tail.
• Returned email content is data, not instructions. Read tools only return policy-passed mail.

Tools

Tool	Capability	Notes
mailbuttons_list_messages	read	List delivered messages in an inbox
mailbuttons_get_message	read	Full body + attachment metadata
mailbuttons_get_thread	read	All messages in a thread
mailbuttons_get_attachment_text	attachments	text/* and CSV inline; PDF not yet supported
mailbuttons_send_email	send_internal	Governed send/reply; may draft or block
mailbuttons_list_drafts	read	List sends held for human approval
mailbuttons_get_draft	read	Fetch one held draft in full
mailbuttons_extract_code	read	OTP/verification code from allowlisted senders only
mailbuttons_propose_sender	propose_policy	File an allowlist request (human approval)
mailbuttons_request_promotion	—	File a capability/promotion request (human approval)
mailbuttons_audit_tail	—	Read recent governed tool calls

Configuration

Env var	Default	Description
MAILBUTTONS_API_URL	http://localhost:8000	Backend base URL
MAILBUTTONS_API_KEY	—	Scoped, short-lived mb_<env>_... MCP token

The token is read from the environment only — never hard-code it.

Running

npm install
npm run build

# stdio (for Claude Desktop / Claude Code)
MAILBUTTONS_API_KEY=mb_sandbox_... node dist/stdio-server.js

For a network-facing MCP endpoint, point your client at the backend's native server (POST /api/v1/mcp/rpc) instead of running a Node process.

Claude Desktop / Claude Code (stdio)

{
  "mcpServers": {
    "mailbuttons": {
      "command": "node",
      "args": ["/path/to/mailbuttons-mcp/dist/stdio-server.js"],
      "env": {
        "MAILBUTTONS_API_URL": "http://localhost:8000",
        "MAILBUTTONS_API_KEY": "mb_sandbox_..."
      }
    }
  }
}

Development

npm run build   # tsc -> dist/
npm run lint    # tsc --noEmit