mcp-dispatch
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., "@mcp-dispatch dispatch message to bob: deployment complete"
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.
mcp-dispatch
Local inter-agent messaging for AI coding agents via MCP.
Multiple Claude Code sessions (or any MCP-compatible agents) running on the same machine can send messages to each other through a shared filesystem relay. No server process, no ports, no network — just directories and JSON files with atomic writes.
Features
Non-destructive messaging — Messages persist until explicitly acknowledged. No more lost messages from crashes or compaction.
Threading — Group messages into conversations with
thread_idandreply_to.Structured payloads — Attach machine-readable data alongside human-readable messages.
TTL & must_read — Time-sensitive messages auto-expire. Critical messages survive until acknowledged.
Delivery receipts —
peek()shows read/unread state of messages you've sent.Config-driven — TOML config for agent rosters, directories, and limits. Or go dynamic with no roster.
Zero infrastructure — Filesystem relay survives process crashes. No daemon to manage.
Related MCP server: hardline-mcp
Quick Start
1. Install
Requires Python 3.11+ and uv.
git clone https://github.com/sophia-labs/mcp-dispatch.git
cd mcp-dispatch
uv syncFor real-time stderr alerts when messages arrive (optional):
uv sync --extra watch2. Configure Claude Code
Add to your ~/.claude.json:
{
"mcpServers": {
"dispatch": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-dispatch", "python", "server.py"],
"env": {
"MCP_DISPATCH_AGENT_ID": "alice"
}
}
}
}Each Claude Code window needs a unique MCP_DISPATCH_AGENT_ID.
3. Send messages
From any Claude Code session:
Agent alice: dispatch("Hey bob, I pushed the fix", target="bob")
Agent bob: peek() → sees alice's message
Agent bob: ack(["msg-abc12345"]) → message removedTools
Tool | Description |
| Send a message to one agent or all |
| Read messages and delivery receipts for sent messages |
| Acknowledge and delete processed messages |
| List connected agents |
dispatch
dispatch(
message="Deployed to staging",
target="all", # or a specific agent name
priority="normal", # "normal" or "urgent"
thread_id="deploy-123", # optional: group into conversation
reply_to="msg-abc", # optional: reference specific message
payload={"commit": "abc123", "env": "staging"}, # optional: structured data
ttl=3600, # optional: expire after 1 hour
must_read=True, # optional: survive TTL, require explicit ack
)peek
peek() # new (unread) messages only
peek(include_read=True) # all unacknowledged messages
peek(thread_id="deploy-123") # filter by threadack
ack(message_ids=["msg-abc", "msg-def"]) # delete specific messagesConfiguration
Create ~/.config/mcp-dispatch/config.toml:
# Agent roster (omit for dynamic registration — any name accepted)
agents = ["alice", "bob", "carol"]
# Message directory (default: ~/.config/mcp-dispatch/messages)
dispatch_dir = "~/.config/mcp-dispatch/messages"
# Maximum message size in bytes (default: 65536)
max_message_bytes = 65536
# Default TTL in seconds (0 = no expiry)
default_ttl = 0
# Custom MCP instructions template (optional)
# Placeholders: {agent_id}, {agent_list}
# instructions = "You are {agent_id}. Available agents: {agent_list}."Environment Variables
Variable | Description |
| Agent identity (required in dynamic mode) |
| Config file path (default: |
| Override dispatch directory from config |
Dynamic Mode
When no agents roster is configured, any agent name is accepted. Inbox directories are created on demand. This is more flexible but less safe (typos create phantom agents).
How It Works
Each agent gets an inbox directory (
{dispatch_dir}/{agent_name}/)Messages are JSON files written atomically (tmp + rename)
Presence is tracked via PID files in
{dispatch_dir}/.presence/Messages have states:
pending→read→ acknowledged (deleted)Piggyback delivery: pending messages are attached to every tool response
TTL cleanup runs lazily on read operations
Optional watchdog prints stderr alerts for the human operator
Message Format
{
"id": "msg-a1b2c3d4",
"from": "alice",
"to": "bob",
"timestamp": "2026-02-17T20:30:00Z",
"priority": "normal",
"content": "Deployed to staging",
"payload": {"commit": "abc123"},
"thread_id": "deploy-123",
"reply_to": null,
"ttl": 3600,
"must_read": false,
"state": "pending"
}License
MIT — see LICENSE.
Available Tools
4 toolsackA
Acknowledge and delete messages by their IDs. This is the only way to permanently remove messages from your inbox (besides TTL expiry). Pass a list of message IDs to acknowledge.
Inputs: message_ids (required).
dispatchA
Send a message to another agent or all agents. Use priority='urgent' for time-sensitive messages. Optional: thread_id groups messages into conversations, reply_to references a specific message, payload carries structured data (dict), ttl sets expiry in seconds, must_read=true prevents auto-expiry. Returns confirmation plus any pending messages for you.
Inputs: message (required), ttl, target, payload, +4 more.
peekA
Read incoming messages without deleting them. By default returns only NEW (unread) messages with full bodies. Set include_read=true to see ALL unacknowledged messages. Filter by thread_id to see a specific conversation. Use ack() to acknowledge messages when you're done with them. Also returns delivery receipts for your recently sent messages.
Modes:
mode='full' (default): each message returned with full content + payload.
mode='metadata': each message returned as {id, from, ts, priority, preview_120, size_bytes, thread_id, state} — no full body. ~80% smaller; use this for defensive polling.
since: ISO8601 timestamp filter — only return messages with timestamp >= since.
Inputs: mode, since, thread_id, include_read.
whoA
List all currently connected agents and their status.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct responsibility: dispatch sends, peek reads, ack deletes, and who lists agents. The only minor overlap is dispatch returning pending messages, but its primary purpose is unambiguous.
Tool names are consistently short, lowercase, and command-like, but they are not all verbs: dispatch, ack, and peek are actions while who is a query. This is a minor deviation from an otherwise coherent naming style.
Four tools is an ideal size for a messaging and dispatch server. Each tool covers a necessary operation without redundancy or bloat.
The message lifecycle is fully covered: create via dispatch, read via peek, remove via ack, plus agent discovery via who. Advanced features like reply_to, thread grouping, TTL, and payloads are supported through parameters, so there are no obvious gaps.
Maintenance
Related MCP Connectors
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Inbox for AI agents: one address per agent to message, share files and pay other agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables multi-agent coordination for Claude Code and Claude.ai through file-based JSON communication, eliminating the human bottleneck of message relaying.14 npmMIT
- AlicenseAqualityBmaintenanceEnables local AI coding agents to message each other on one machine using a durable SQLite mailbox and live-ask tools.93MIT
- AlicenseNot gradedqualityCmaintenanceEnables real-time, file-based messaging between terminal AI agents (like Claude Code, Gemini CLI) allowing them to collaborate on tasks directly without a server or network, using JSON files and atomic rename for coordination.20 PyPIMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents on the same machine to exchange asynchronous messages as plain Markdown files, with optional wake-up notifications per agent.11 npm1AGPL 3.0