MCP Agent Mail: Inboxes and Advisory File Leases for Parallel Coding Agents

The problem: several agents, one working tree

Run a backend agent and a frontend agent against the same repository and the failure is predictable. One rewrites a module while the other is mid-edit, the second sees a diff it did not author, and either it overwrites the change or it stalls trying to work out what happened. The README lists exactly this: agents that "overwrite each other's edits or panic on unexpected diffs", miss context from parallel workstreams, and force a human to relay messages between tools.

The project targets people already running an agent swarm rather than a single assistant. The README names FastMCP clients and CLI tools including Claude Code, Codex, Gemini CLI and Factory Droid, coordinating across one or more codebases. If you run one agent at a time, the coordination layer has nothing to coordinate and you are paying installation cost for an unused inbox.

Two storage layers with different jobs

The architecture splits storage by purpose. Git holds the artifacts, so messages, leases and attachments land as files a human can read and diff in a normal review. SQLite holds the index, which is what makes search, threading and querying practical without walking the Git history.

That split is the most interesting design decision in the repository. A pure database would make the history opaque; a pure file store would make search expensive. Keeping both means the audit trail is inspectable with Git tooling while the query path stays fast. The cost is that two stores must agree, and the README does not describe a reconciliation or repair command for the case where the index and the Git tree drift apart. Treat that as an open question rather than a solved one.

Messages are GitHub-Flavored Markdown and can carry images, so an agent can attach a screenshot of a broken layout to the thread where it reports the break.

Identities, inboxes and advisory leases

Registration produces a temporary-but-persistent identity such as GreenCastle. The name is memorable rather than meaningful, which matters when several agents are reporting into one thread and you need to tell them apart at a glance.

Each identity gets an inbox and an outbox. Agents send and receive Markdown messages, search and summarize conversations, and group them into threads. Alongside the mail, an agent can declare a file reservation, described in the README as a lease, over specific files or globs to signal intent. A directory view lists active agents, the programs or models behind them, and recent activity.

The word to hold onto is advisory. A lease is a signal, not a lock. Nothing in the supplied material suggests the server blocks a write from an agent that ignores an existing reservation. Two agents that both choose to respect leases will avoid collisions; one that does not respect them will walk straight through. If your failure mode is a corrupted file rather than a wasted edit, this is the wrong mechanism.

Installing it and starting the server

The README gives a one-line installer:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

The script installs uv if missing and updates PATH for the session, installs jq for config merging, creates a Python 3.14 virtual environment, runs the auto-detect integration for supported agent tools, starts the MCP HTTP server on port 8765, and prints a masked bearer token. It writes helper scripts under scripts/, including run_server_with_token.sh, and adds an am alias to .zshrc or .bashrc so that typing am starts the server later.

Flags let you control placement and behaviour: --dir, --project-dir, --no-start, --start-only, --port and --token. The README also documents --skip-beads and --skip-bv for the task tracker and viewer components.

The installer is the part to read closely before running it. It installs Beads Rust and creates a bd alias pointing at br, replacing any existing bd installation. The README states that both implementations use the same .beads/issues.jsonl format, so existing Beads data stays compatible, and that a bd-br-migration skill is installed so agents can adapt to CLI differences. Even so, a script that swaps a binary you already depend on is a decision, not a detail. If you want the mail server without that change, pass --skip-beads.

Transports, tool filtering and what 0.3.0 changed

The release notes for v0.3.0 name three additions: stdio transport, tool filtering and push notifications. The README describes the server as HTTP-only, so the stdio option appears to be a later addition and the README has not been updated to match. That mismatch is worth checking against the current source before you plan a deployment, because the transport you pick determines whether the server sits behind a port and a bearer token or runs as a child process of the agent client.

Tool filtering matters more than it sounds. An MCP server exposes its tools to the client, and every tool in the list is context the model has to carry. Filtering lets you present a narrower surface, which is useful when an agent only needs to read its inbox and not, say, broadcast to every identity in the directory. Push notifications change the interaction from polling to being told, which is the difference between an agent that checks for messages between tasks and one that can be interrupted by a message.

Where it stops being the right tool

Two limitations are visible in the supplied material. The first is the advisory nature of leases, covered above. The second is the project's own status line: under active development, with the design captured in docs/planning/project_idea_and_guide.md. A coordination layer sits underneath every agent you run, so its failure modes are your failure modes. Adopting it means accepting that the interface may move.

There is also a boundary between the open source server and the commercial companion stack. The README describes an iOS app plus host automation that provisions, pairs and steers heterogeneous fleets, with Message Stacks, Human Overseer broadcasts, Beads awareness and plan editing, and enforcement of Double-Arm confirmations for destructive work. The open source server provides the mailboxes, leases, Typer CLI helpers and searchable archives. If what you actually want is scheduled prompts and confirmation gates for destructive operations, that is the companion product, not the server in this repository. Read the README's own framing carefully before assuming the OSS install covers the whole workflow.

Licensing is unresolved in the metadata: the repository is listed with a NOASSERTION licence identifier rather than a recognised SPDX value. That is a fact to verify against the repository's licence file, not something to assume either way. I am not giving legal advice; if the licence terms affect how you ship, have someone who can read them do so.

Compared with a shared task file

The obvious alternative is a shared Markdown file or task list that every agent appends to, which is how many small swarms start. The difference is in the query and the signal. A flat file gives you append and read; it gives you no identity registry, no per-agent inbox, no threading, and no way for one agent to announce that it is about to touch a glob of files. Search means grepping the file, and concurrent appends from several agents are their own coordination problem.

A second alternative is a general task tracker used as the coordination bus. Beads is the relevant comparison here, and the installer's behaviour makes the relationship concrete: the same script installs Beads Rust and aliases bd to br. Beads tracks work items; Agent Mail carries messages, threads and file intent. They overlap on the question of who is doing what, and the README's own workflow has agents acknowledge the Beads backlog before touching code and then register with Agent Mail. If you already have a tracker your team reads, adding mail on top is a smaller step than replacing the tracker with a chat layer.

Maintenance cost and what to verify first

Upgrade cost is concentrated in the installer, not the server. Re-running it can replace your bd binary, rewrite shell profile entries for the am alias, and re-run the auto-detect integration against your agent tool configs. The auto-detect step is the one to watch: the README does not enumerate which files it edits or whether it preserves existing entries, so inspect your tool configuration afterwards rather than assuming a clean merge. jq is installed specifically for safe config merging, which suggests the script tries to be careful, but careful and correct are different claims.

The Python 3.14 virtual environment is another pin to check against your own toolchain before you run the installer on a machine you care about.

A reasonable sequence is to read docs/planning/project_idea_and_guide.md first, then run the installer with --no-start and --skip-beads on a scratch directory, inspect what changed in your shell profile and agent configs, and only then start the server on port 8765 and register a single test identity. The first thing to test in practice is the lease: have one agent reserve a glob and a second agent attempt the same reservation, and see what the server actually reports. The README calls the reservations voluntary, and that word is doing a lot of work.

Editorial conclusion

Adopt MCP Agent Mail if you already run several FastMCP-compatible agents against one repository and you want their exchanges stored as human-readable Markdown rather than trapped in a chat log. Do not adopt it if you need hard mutual exclusion on files, since the reservations are explicitly advisory, or if you object to an installer that replaces an existing bd binary and writes an am alias into your shell profile. Before committing, read docs/planning/project_idea_and_guide.md, confirm the NOASSERTION licence identifier has been resolved to an actual licence file, and check what the auto-detect integration will change in your agent tool configs.

Official sources

1. Dicklesworthstone/mcp_agent_mail on GitHub
2. Issues
3. README
4. Releases