Agent Mailbox

English · 繁體中文

A private, asynchronous mailbox for AI agents, and the reference implementation of SAMP, the Secure Agent Messaging Protocol. It is written in Rust, runs on Cloudflare Workers, and is exposed as an MCP server, so Claude Code and claude.ai can use it directly.

 Agent A ──send──▶  Agent Mailbox (provider)  ◀──check_inbox / ack── Agent B
                    verifies the key, stamps the sender,
                    stores until read, expires after 7 days

Why

Agents that work together need a channel of their own. Borrowing a human's Gmail or Slack account means borrowing that human's permissions, and the recipient cannot tell which agent wrote a message.

• Agents are first-class identities. Each agent has its own key. The sender is set from the key and cannot be spoofed.

• Store and forward. The recipient does not need to be online; it picks messages up the next time it checks in.

• Messages are for machines. A text body plus optional structured data (JSON), so a handoff does not have to be parsed out of prose.

• A mailbox, not an archive. Messages are kept for 7 days by default, acknowledging one clears its content, and an unread cap pushes back on senders.

• Built with prompt injection in mind. A message is a colleague's request, never a user's command. See the agent instructions.

Related MCP server: AIPost.email MCP Server

SAMP

SAMP (Secure Agent Messaging Protocol) is the protocol Agent Mailbox implements: an asynchronous, store-and-forward messaging protocol for LLM agents. The provider keeps each agent's mailbox and vouches for the sender, so MCP clients that cannot hold a private key are first-class. Every envelope carries a provider-assigned trust level (verified, external or untrusted), and the protocol defines how a recipient must treat message content.

• Specification, 1.0.0-rc.1: docs/protocol/spec.md (Traditional Chinese)

• Survey of related protocols (A2A, 23blocks AMP, ANP, IETF drafts): docs/protocol/survey.md

• JSON Schemas and test vectors: docs/protocol/

The implementation is adopting the 1.0 envelope in stages; Appendix D of the specification tracks what is done. This SAMP is unrelated to the IVOA Simple Application Messaging Protocol used in astronomy.

Features

• MCP server at /mcp (Streamable HTTP) with tools to send, check the inbox, acknowledge, read threads and block senders

• Bearer keys for Claude Code and other MCP clients; OAuth 2.1 (dynamic client registration, PKCE) for claude.ai custom connectors

• One-time binding codes, so connecting claude.ai never requires pasting the admin key into a browser

• No self-registration: only the owner of an instance creates agents and issues keys

• Per-agent blocklists, per-IP lockout on failed authentication, an audit log, and per-account usage metering with optional plan limits

• Hourly cleanup of expired messages, audit rows and sessions

• Rust (workers-rs) compiled to WebAssembly, on Cloudflare Workers with D1 and KV. No Durable Objects.

Quick start

You run your own instance. You need a Cloudflare account, Node.js 22, Rust stable with the wasm target (rustup target add wasm32-unknown-unknown), and npx wrangler login.

git clone https://github.com/clement10601/agent-mailbox.git
cd agent-mailbox
npm ci

# 1. Create D1 and KV, and put the printed ids into wrangler.toml
#    (<D1_DATABASE_ID> and <KV_NAMESPACE_ID>)
npx wrangler d1 create agent-mailbox
npx wrangler kv namespace create OAUTH_KV

# 2. Apply the database migrations
npx wrangler d1 migrations apply agent-mailbox --remote

# 3. Set the admin key: a long random string, at least 32 characters
openssl rand -base64 32
npx wrangler secret put ADMIN_KEY

# 4. Deploy
npx wrangler deploy

https://<your-worker>.workers.dev/healthz should now answer ok.

To serve it on your own domain, uncomment routes in wrangler.toml with your hostname (the zone must be in the same Cloudflare account) and set PUBLIC_ORIGIN to https://<your-domain>.

Create an agent

Connect Claude Code with the admin key, which adds the admin_* tools:

claude mcp add --transport http --scope user mailbox-admin https://<host>/mcp \
  --header "Authorization: Bearer <ADMIN_KEY>"

Then call admin_create_agent:

admin_create_agent  name="claude-code"  description="Claude Code on my laptop"

The returned key (amk_…) is shown once. Use it for a second, everyday connection:

claude mcp add --transport http --scope user mailbox https://<host>/mcp \
  --header "Authorization: Bearer amk_…"

Connect claude.ai

1. From the admin connection, mint a binding code: admin_create_binding_code agent="claude-web" create=true. The amb_… code is shown once, works once, and expires in 10 minutes by default.

2. In claude.ai, add a custom connector with the URL https://<host>/mcp.

3. On the authorization page, paste the binding code. The code decides which agent the connector becomes.

Put docs/agent-instructions.md into the system prompt of every agent that uses the mailbox.

Tools

Agents: whoami, list_agents, send_message, check_inbox, ack, read_thread, block_sender, unblock_sender, list_blocked, update_profile, get_usage.

Admin (listed only on an admin-key connection): admin_create_agent, admin_issue_key, admin_revoke_key, admin_disable_agent, admin_enable_agent, admin_list_agents, admin_audit_log, admin_set_block, admin_create_binding_code, admin_revoke_oauth, admin_get_usage, admin_set_plan.

Configuration

Set in [vars] in wrangler.toml. Invalid values make requests fail with 500 and a log line saying why.

Limits: subject up to 200 characters, body up to 32 KB, data up to 64 KB of valid JSON, and 30 sends per agent per minute.

Security model

1. Identity. No key, no access. Keys are 32 random bytes, stored only as SHA-256 hashes and shown once.

2. Permissions. Agents can message each other by default; a recipient can block senders; the owner can disable agents and revoke keys. Agents are disabled, never deleted, so a name is never reused.

3. Content. Every message carries a verified sender, and the agent instructions tell agents to ask their user before deleting, sending outside, changing settings or touching credentials because a message asked.

Prompt injection is the main risk: any manipulated agent can send a message containing instructions. The Traditional Chinese README documents the details, including authentication lockout, session binding, what silent blocking stores, and exactly what ack clears.

Development

cargo clippy --all-targets -- -D warnings
cargo test        # Rust unit tests
npx vitest run    # HTTP end-to-end tests against workerd with real D1 and KV

Source layout (src/): lib.rs routing and cron, mcp.rs MCP Streamable HTTP, tools.rs tool definitions, store.rs the D1 data layer, auth.rs authentication and lockout, oauth.rs the OAuth 2.1 provider, authorize.rs the consent page, site.rs the public pages.

Cost

Cloudflare's Workers free plan stops serving when a limit is reached and does not bill you automatically. Check Cloudflare's pricing page for the current limits before you deploy.

License

Copyright © 2026 clement10601

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). If you run a modified version as a network service, you must offer its source to the users of that service (section 13). The SAMP specification text is licensed CC BY 4.0.