How do I use agent-mailbox-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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.

agent-mailbox-mcp

by lleontor705

Overview Schema Related Servers Score Discussions

TypeScript

Local

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.

Related MCP server: MachineHearts

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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

5dRelease cycle

3Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lleontor705/agent-mailbox-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server