Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-mailbox-mcp send a message to analyst asking for Q1 report"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AI agents working in multi-agent systems need to communicate, delegate tasks, and coordinate resources. Without a messaging layer:
Agents can't send results to each other
No way to delegate complex work to specialized agents
Multiple agents editing the same file cause conflicts
Failed or expired messages are silently lost
agent-mailbox-mcp provides the messaging infrastructure your agents need — combining MCP (agent-to-tools) with A2A (agent-to-agent) in a single server.
Related MCP server: Hive
# stdio mode (default — use with Claude Code, Codex, Gemini)
npx -y agent-mailbox-mcp
# HTTP mode (enables A2A, dashboard, SSE streaming)
MAILBOX_TRANSPORT=http npx -y agent-mailbox-mcp
# → Dashboard: http://localhost:4820/dashboard
# → Agent Card: http://localhost:4820/.well-known/agent-card.json
# → A2A endpoint: http://localhost:4820/a2aclaude mcp add agent-mailbox --transport stdio -- npx -y agent-mailbox-mcp~/.codex/config.toml)[mcp_servers.agent-mailbox]
command = "npx"
args = ["-y", "agent-mailbox-mcp"]settings.json){
"mcpServers": {
"agent-mailbox": {
"command": "npx",
"args": ["-y", "agent-mailbox-mcp"]
}
}
}{
"servers": {
"agent-mailbox": {
"command": "npx",
"args": ["-y", "agent-mailbox-mcp"]
}
}
}Send, receive, search, and manage messages between agents with priority, threading, deduplication, and auto-expiration.
→ msg_send(sender: "coordinator", recipient: "analyst", subject: "Q1 Report", body: "Generate the Q1 revenue report", priority: "high")
← { sent: true, message_id: "msg-a1b2c3", thread_id: "thr-d4e5f6" }
→ msg_read_inbox(agent: "analyst")
← { count: 1, messages: [{ subject: "Q1 Report", priority: "high", ... }] }
→ msg_broadcast(sender: "team-lead-1", subject: "Group 1 complete", body: "Completed: [1.1, 1.2]")Delegate complex work to specialized agents. Tasks have a full lifecycle with state tracking, artifacts, and streaming.
→ a2a_submit_task(from_agent: "manager", to_agent: "researcher", message: "Find top 5 competitors")
← { task_id: "task-x1y2z3", status: "submitted" }
→ a2a_respond_task(task_id: "task-x1y2z3", message: "Analysis complete: ...", status: "completed", artifact_name: "competitor-report")Advisory locking for deploy, CI, APIs, or any shared resource. Prevents agents from stepping on each other's work.
→ resource_check(resource_id: "deploy-staging")
← { held: false }
→ resource_acquire(resource_id: "deploy-staging", agent: "implement-1", lease_type: "exclusive", ttl_seconds: 300)
← { acquired: true }
→ resource_release(resource_id: "deploy-staging", agent: "implement-1")
← { released: true }Expired and failed messages go to a DLQ instead of being lost. Retry or purge them.
→ dlq_list()
← { count: 2, entries: [{ reason: "expired", subject: "Important task", ... }] }
→ dlq_retry(dlq_id: "dlq-abc123")
← { retried: true, new_message_id: "msg-..." }Real-time monitoring of agents, messages, tasks, leases, and DLQ — accessible at /dashboard when running in HTTP mode.
Full A2A protocol support over JSON-RPC 2.0:
Agent Cards at /.well-known/agent-card.json for discovery
SSE Streaming at /a2a/tasks/:id/stream for real-time task updates
Push Notifications via webhooks with exponential backoff retry
JWT Authentication with granular scopes
Optional AES-256-GCM encryption for message bodies. Set MAILBOX_ENCRYPTION_KEY to enable — transparent to tools.
Category | Tools | Description |
Messaging (7) |
| Async/sync messaging with priority, threading, dedup |
Registry (3) |
| Agent discovery and activity monitoring |
A2A Tasks (5) |
| Task delegation with state machine |
Resources (3) |
| Advisory resource leasing (deploy, CI, APIs) |
Dead Letter (3) |
| Failed message recovery |
Variable | Default | Description |
|
| Database directory |
|
| Full database path |
|
| Message TTL in seconds (default 24h) |
|
| HTTP server port |
|
| Transport: |
| — | JWT signing secret (empty = auth disabled) |
| — | AES-256-GCM key (empty = no encryption) |
Guide | Description |
Installation, configuration, first message | |
All 21 tools with parameters and examples | |
Task delegation, Agent Cards, streaming, webhooks | |
Real-world usage patterns | |
Guide for AI agents on how to use the mailbox |
git clone https://github.com/lleontor705/agent-mailbox-mcp.git
cd agent-mailbox-mcp
npm install
npm run dev # stdio server
npm run serve # HTTP server with dashboard
npm test # 111 tests
npm run build # TypeScript compilation
npm run inspect # MCP inspectorTypeScript with strict mode
SQLite (WAL mode) via better-sqlite3 — zero external services
Express for HTTP transport
MCP SDK (@modelcontextprotocol/sdk) for protocol compliance
Zod for runtime input validation
Node.js crypto for JWT and AES-256-GCM — zero auth dependencies
MIT
Cancel an A2A task. Only non-terminal tasks can be canceled.
Inputs: task_id (required).
Get the status and full history of an A2A task including messages and artifacts.
Inputs: task_id (required).
List A2A tasks for an agent with pagination.
Inputs: agent (required), role, limit, offset.
Respond to an A2A task as the assigned agent. Sends a response and optionally updates the task status.
Inputs: message (required), task_id (required), status, artifact_name, +1 more.
Submit a task to another agent via the A2A protocol. Creates a new task with an initial message.
Inputs: message (required), to_agent (required), from_agent (required), metadata, +1 more.
Register an agent in the mailbox system with a name, role, and optional A2A Agent Card metadata.
Inputs: name (required), url, role, skills, +2 more.
List messages in the dead-letter queue. These are messages that expired or failed delivery.
Inputs: limit, offset.
Remove all entries from the dead-letter queue.
Inputs: no named parameters.
Retry a dead-letter message by re-inserting it as a new pending message.
Inputs: dlq_id (required).
Get recent messaging activity feed.
Inputs: minutes.
Send a message to all registered agents.
Inputs: body (required), sender (required), subject (required), priority.
Count messages by status for an agent.
Inputs: agent (required).
List all registered agents with their roles and last activity.
Inputs: no named parameters.
List conversation threads for an agent.
Inputs: agent (required), limit.
Read unread messages for an agent. Messages are marked as delivered.
Inputs: agent (required), limit.
Send a message and wait for a reply (synchronous request/reply pattern with polling).
Inputs: body (required), sender (required), subject (required), recipient (required), +1 more.
Search messages by content, subject, or sender/recipient.
Inputs: query (required), agent, limit, offset.
Send a message to another agent. Supports deduplication and threading.
Inputs: body (required), sender (required), subject (required), recipient (required), +3 more.
Acquire an advisory lease on a resource. Used for coordinating exclusive or shared access between agents.
Inputs: agent (required), resource_id (required), metadata, lease_type, +1 more.
Check the current lease status of a resource.
Inputs: resource_id (required).
Release a previously acquired resource lease.
Inputs: agent (required), resource_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 21 tools
Each tool targets a specific action and resource: messaging (send, read, broadcast, search, request, threads, count, activity), A2A tasks (submit, get, list, cancel, respond), resource leases (acquire, release, check), and dead-letter queue management (list, retry, purge). The purposes are clearly distinct and descriptions eliminate ambiguity.
Most tools follow a consistent prefix-based naming scheme (msg_, a2a_, resource_, dlq_) with verb_object patterns. Minor deviations include 'msg_activity_feed' (noun instead of verb) and 'agent_register' lacking a category prefix, but these are not confusing.
With 21 tools, the count is slightly above the typical well-scoped range but appropriate given the server's broad scope covering messaging, A2A tasks, resource coordination, and DLQ management. Each tool contributes to a cohesive set, though a few could be consolidated.
The domain is well-covered with full lifecycles for messaging, A2A tasks, resource leases, and DLQ handling. Minor gaps include no resource listing or message deletion, but these are not critical for the server's purpose.
MCP Server for an Agent Task Marketplace
MCP server for building and testing AI agents with multi-model experimentation and insights.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
