About Mailbuttons
Mailbuttons is an MCP server for agents that need controlled access to email. It uses sandbox inboxes, per-send policy checks and human approval for external sends or scope changes.
Key features
- 01Sandbox-by-default inboxes
- 02Per-mailbox inbound sender policies
- 03Recipient blocklists for outgoing mail
- 04Account send caps and tamper-evident audit log
- 05Human approval for external sends and scope changes
Use cases
- 01Let an agent read mail in a restricted inbox
- 02Prevent unapproved messages to external recipients
- 03Review and audit blocked or permitted send attempts
MCP support
Exposes governed email access to MCP clients through a hosted streamable-HTTP endpoint or a local stdio server. Sandbox tokens cannot send externally until a human promotes them.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://mailbuttons.com/api/v1/mcp/rpcclaude mcp add --transport http com-mailbuttons https://mailbuttons.com/api/v1/mcp/rpc{"mcpServers":{"com-mailbuttons":{"type":"http","url":"https://mailbuttons.com/api/v1/mcp/rpc"}}}Open in Cursor{"servers":{"com-mailbuttons":{"type":"http","url":"https://mailbuttons.com/api/v1/mcp/rpc"}}}Open in VS Code{"mcpServers":{"com-mailbuttons":{"type":"http","url":"https://mailbuttons.com/api/v1/mcp/rpc"}}}{"mcpServers":{"com-mailbuttons":{"serverUrl":"https://mailbuttons.com/api/v1/mcp/rpc"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
https://mailbuttons.com/api/v1/mcp/rpcAuth requiredTools
12| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Max messages to return (default backend-defined). |
| query | string | No | Optional full-text/sender filter passed through to JMAP search. |
| cursor | integer | No | Pagination cursor from a previous call's next_cursor. |
| inbox_id | integer | Yes | Inbox (mailbox) id. Must be in scope for the token. |
Details
From the project READMEMailbuttons MCP server
Governed email for AI agents, over the Model Context Protocol. Give an agent a scoped mailbox where the server enforces the guardrails, not the prompt: sandbox-by-default inboxes, a policy gate on every send, and a tamper-evident audit log. External sending and scope changes are human-approved, never granted by the agent itself.
- Registry:
com.mailbuttons/mcp-server - npm:
@mailbuttons/mcp-server - Platform: mailbuttons.com · agent front door: mbag.ai
Use it
Hosted (recommended) — a streamable-HTTP endpoint served by the platform:
https://mailbuttons.com/api/v1/mcp/rpc
Authorization: Bearer <your Mailbuttons MCP token> # mb_sandbox_... (or mb_prod_...)
Local (stdio) — run the npm package and let your agent launch it:
{
"mcpServers": {
"mailbuttons": {
"command": "npx",
"args": ["-y", "@mailbuttons/mcp-server"],
"env": { "MAILBUTTONS_API_KEY": "mb_sandbox_..." }
}
}
}
Get a scoped token from the dashboard or POST /api/v1/mcp/sandbox-inboxes.
Sandbox tokens can never send externally until a human promotes them.
What the server enforces
- Inbound — a per-mailbox sender policy, fail-closed: mail from strangers bounces by default, so nobody can prompt-inject your agent just by emailing it.
- Outbound — a recipient blocklist the agent can read but not change; a
blocked send returns a normal
{"status":"blocked"}result, not an error. - Caps + audit — per-account send caps and a hash-chained audit log that records refusals too.
- Escalation — sending externally or widening scope is propose-only; a named human approves. The agent cannot approve its own request.
Install as an agent skill
This repo ships a root SKILL.md, so any skills-aware agent can add it:
npx skills add mailbuttons/mcp-server
Docs
- Agent signup (for agents): https://mbag.ai/docs/agent-signup.md
- Trust model: https://mbag.ai/docs/trust-model.md
- OpenAPI: https://mbag.ai/api/openapi.json
- Framework recipes:
references/(Claude Agent SDK, LangChain, plain SDK)
Mailbuttons is a trading name of Code Cutter Limited (UK, no. 08453060). MIT licensed.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.