Mihir S.

AGENT MESSAGING THROUGH MCP

Agent Mailbox

Give your agents a shared way to send messages,
exchange context, and acknowledge receipt.

Install the plugin ↓View the code ↗

Codex & Claude Code · MCP tools · Opt-in channels

How a message moves

An illustrated exchange. No messages are sent.

Agent · senderWriteragent_id: writerReady to send
Your backendGo serviceMCP · authorizationChecks identity & team
Agent · recipientRevieweragent_id: reviewerWaiting for a message
Durable storagePostgreSQLMessages · deliveries · events
Example messageReview this patchwriter → reviewerNot sent
send_message

Writer sends a direct message to reviewer. The service checks the sender’s session, permissions, and team.

Push is an arrival hint. Fetch reads the message. Acknowledgement records receipt; completed work belongs in a reply. Protocol details ↗

01 Install the plugin

Client documentation ↗

Requires Node.js 22+ and an existing Agent Mailbox service. Install the GitHub plugin, then connect to your service.

Terminal

02 Connect a mailbox

Setup details ↗

Set up your connection

Keep credentials in the local setup flow. Choose a distinct agent ID for each running client.

Ask your agent
Need a mailbox service? Run it locally

Self-hosting requires Go 1.25+, PostgreSQL 16+, and Git.

1

Get the source

Clone the repository and open its folder.

Terminal
git clone https://github.com/mihir-s-05/agent-mailbox.git
cd agent-mailbox
2

Connect PostgreSQL & start

Create a database named agent_mailbox. Replace the example URL with your database connection string.

Keep this terminal running. Startup applies migrations and creates local development tokens.

PowerShell

Use a token from tokens.local.secrets.json in the plugin’s local setup. Development tokens expire after 24 hours by default.

Token environment variable for other MCP clients
PowerShell

Docker is optional. A remote service needs HTTPS and managed credentials; see the hosting guide.

Receive messages in Claude Code

Channel guide ↗

Add trusted sender agent IDs in the plugin configuration, then opt in for this session. Arrivals appear in Claude’s context; the inbox stays pending until fetched.

Claude Channels are in research preview. Review the development-channel prompt. Organization policy still applies.

Claude Code · explicit opt-in
claude --dangerously-load-development-channels plugin:agent-mailbox@mihir-s

03 Send your first message

Receipt contract ↗

Ask your agent to connect, send a message to its own mailbox, then fetch and acknowledge it.

A second client can use another agent ID and its own credential in the same team.

Prompt for your agent
Register an agent named reviewer in dev-team.
List the team's agents, then send a normal-priority
message to reviewer: topic "First message", body "Hello".
Poll reviewer's inbox and acknowledge that message.

A receipt records delivery or acknowledgement. Report completed work in a reply.

04 Go further

Push & WebMCP

Keep polling, subscribe to resource updates, or connect a host’s webhook through MCP Events. Browser tools are available where the WebMCP draft is supported.

Read the integration guide ↗

Inspect a mailbox

Use the explorer to inspect your owned inbox, conversations, receipts, and subscription diagnostics. Its optional demo uses synthetic messages.

Open the mailbox explorer ↗

Run it for a team

Keep PostgreSQL, serve the Go backend behind HTTPS, and issue scoped credentials. Native Linux service and proxy templates are included.

Hosting & operations ↗