Mailbuttons MCP Server

@mailbuttons/mcp-server

The Model Context Protocol server for Mailbuttons, governed email for AI agents. Give Claude Code, Cursor or your own agent an inbox it can read and send from: sandbox by default, human approval for anything addressed outside it, and every call on record. This package is the stdio build plus the Claude Code skill that drives it; the hosted endpoint is served by the Mailbuttons backend (see below).

Mailbuttons runs the agents in its catalogue on this same platform. This server is the way to build your own agent on it.

Get started: sign up and create an API key at mailbuttons.com — docs at mailbuttons.com/developers.

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

These twelve tools are the governed runtime surface. They are identical on the hosted endpoint and in this package.

Build-time tools (this package only)

The stdio build adds three helpers for setting an integration up. They exist so the Claude Code skill can scaffold a working agent; the hosted endpoint never exposes them, and none of them can grant a capability.

Both writers only touch the paths named above, inside the directory the server was launched from. Generated code reads MAILBUTTONS_API_KEY from the environment and never inlines a token.

Get a token (free, about a minute)

# 1. Email yourself a sign-in code
curl -s -X POST https://mailbuttons.com/api/auth/otp/request \
  -H 'Content-Type: application/json' -d '{"email":"you@example.com"}'

# 2. Exchange the code for an mbk_ API key
curl -s -X POST https://mailbuttons.com/api/auth/otp/cli-exchange \
  -H 'Content-Type: application/json' -d '{"email":"you@example.com","code":"123456"}'

# 3. Create a free sandbox inbox; the response carries its sandbox_token (mb_sandbox_...)
curl -s -X POST https://mailbuttons.com/api/v1/mcp/sandbox-inboxes \
  -H 'Authorization: Bearer mbk_...' -H 'Content-Type: application/json' -d '{"label":"my agent"}'

Sandbox tokens can read and send within the sandbox domain; anything addressed outside it becomes a draft a human approves. More: https://mailbuttons.com/developers/#mcp

Connect

Remote (recommended): Claude Code

claude mcp add --transport http mailbuttons https://mailbuttons.com/api/v1/mcp/rpc \
  --header "Authorization: Bearer mb_sandbox_..."

Any client that speaks Streamable HTTP and lets you set a header works the same way: URL https://mailbuttons.com/api/v1/mcp/rpc, header Authorization: Bearer mb_sandbox_....

Local (stdio): Claude Desktop, Cursor and others

{
  "mcpServers": {
    "mailbuttons": {
      "command": "npx",
      "args": ["-y", "@mailbuttons/mcp-server"],
      "env": { "MAILBUTTONS_API_KEY": "mb_sandbox_..." }
    }
  }
}

Configuration

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

Development

npm run build   # tsc -> dist/
npm run lint    # tsc --noEmit
npm test        # build + vitest (includes the version-alignment check)

Releases: bump the version in package.json, server.json (both places), src/server.ts and skill/SKILL.md together; npm test fails if they drift. Then npm publish, then mcp-publisher publish from this directory. See docs/mcp-publishing.md in the monorepo.

Licence

MIT. Mailbuttons is a trading name of Code Cutter Limited (UK).