agent-mailbox-mcp

MCP + A2A messaging server for multi-agent AI systems

Mailbox-style messaging · A2A task delegation · Resource coordination · Web dashboard
Works with Claude Code, Codex CLI, Gemini CLI, and any MCP-compatible client

---

Why?

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.

Architecture

Quick Start

# 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/a2a

Configure Your AI Client

Claude Code

claude mcp add agent-mailbox --transport stdio -- npx -y agent-mailbox-mcp

Codex CLI (~/.codex/config.toml)

[mcp_servers.agent-mailbox]
command = "npx"
args = ["-y", "agent-mailbox-mcp"]

Gemini CLI (settings.json)

{
  "mcpServers": {
    "agent-mailbox": {
      "command": "npx",
      "args": ["-y", "agent-mailbox-mcp"]
    }
  }
}

VS Code (MCP extension)

{
  "servers": {
    "agent-mailbox": {
      "command": "npx",
      "args": ["-y", "agent-mailbox-mcp"]
    }
  }
}

Features

Messaging (7 tools)

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]")

A2A Task Delegation (5 tools)

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")

Resource Coordination (3 tools)

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 }

Dead-Letter Queue (3 tools)

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-..." }

Web Dashboard

Real-time monitoring of agents, messages, tasks, leases, and DLQ — accessible at /dashboard when running in HTTP mode.

HTTP + A2A Protocol

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

Encryption at Rest

Optional AES-256-GCM encryption for message bodies. Set MAILBOX_ENCRYPTION_KEY to enable — transparent to tools.

All 21 Tools

Category	Tools	Description
Messaging (7)	msg_send msg_read_inbox msg_broadcast msg_search msg_request msg_list_threads msg_count	Async/sync messaging with priority, threading, dedup
Registry (3)	agent_register msg_list_agents msg_activity_feed	Agent discovery and activity monitoring
A2A Tasks (5)	a2a_submit_task a2a_get_task a2a_cancel_task a2a_list_tasks a2a_respond_task	Task delegation with state machine
Resources (3)	resource_acquire resource_release resource_check	Advisory resource leasing (deploy, CI, APIs)
Dead Letter (3)	dlq_list dlq_retry dlq_purge	Failed message recovery

Environment Variables

Variable	Default	Description
MAILBOX_DIR	~/.agent-mailbox	Database directory
MAILBOX_DB	~/.agent-mailbox/mailbox.db	Full database path
MAILBOX_TTL	86400	Message TTL in seconds (default 24h)
MAILBOX_PORT	4820	HTTP server port
MAILBOX_TRANSPORT	stdio	Transport: stdio, http, or both
MAILBOX_AUTH_SECRET	—	JWT signing secret (empty = auth disabled)
MAILBOX_ENCRYPTION_KEY	—	AES-256-GCM key (empty = no encryption)

Documentation

Guide	Description
Getting Started	Installation, configuration, first message
Tools Reference	All 21 tools with parameters and examples
A2A Protocol Guide	Task delegation, Agent Cards, streaming, webhooks
Examples	Real-world usage patterns
Skill Guide	Guide for AI agents on how to use the mailbox

Development

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 inspector

Tech Stack

• TypeScript 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

License

MIT