MCP Agent Mail

MCP Agent Mail is a mail-like coordination layer for coding agents, exposed as an HTTP-only FastMCP server. It provides a shared communication fabric for multiple agents (e.g., backend, frontend, infra) to prevent conflicts and maintain context.

Core Features:

• Identities: Agents can register temporary-but-persistent identities (e.g., GreenCastle).
• Messaging: Supports sending/receiving GitHub-Flavored Markdown messages with images.
• Searchable History: Provides an inbox/outbox and searchable message archives.
• File Leases: Allows agents to declare advisory file reservations (leases) on files or globs to signal intent and avoid overwriting each other's work.
• Auditability: Backed by Git (for human-auditable artifacts) and SQLite (for indexing and queries).
• Observability: Allows inspection of active agents, programs/models, and activity.

FastMCP servers expose capabilities through three primary component types that follow the Model Context Protocol (MCP) standard:

• Tools: Executable functions that perform actions or produce side effects (analogous to POST requests). LLMs invoke these to change state or trigger processes.
• Resources: Read-only data sources identified by a unique URI (analogous to GET requests). They provide context to the LLM via idempotent information retrieval.
• Prompts: Reusable, parameterized message templates that provide structured instructions to guide LLM behavior for specific tasks.

Signature verification ensures the bundle has not been tampered with. For verification to succeed, the following must be present and intact:

1. The original manifest.json (unmodified).
2. The manifest.sig.json file (containing the signature and public key).
3. All assets referenced in the manifest must have matching SHA-256 hashes.

If verification fails, the bundle is likely corrupted or tampered with; you should re-export and re-transfer the data.

To manage complexity, use server composition instead of complex router-level dependencies. You can create specialized FastMCP instances (e.g., for admin tools) and mount them onto a main FastMCP server using the .mount() method with a specific prefix. This allows sub-servers to have their own specific configurations, such as unique authentication providers.

# Main server
main_mcp = FastMCP(name="MainServer")

# Create a sub-server for admin tools
admin_mcp = FastMCP(name="AdminTools")
# Add bearer token auth provider only to this server
# mcp.auth = BearerAuthProvider(...)

@admin_mcp.tool
def sensitive_operation(): ...

# Mount the admin server with a prefix and its own auth
main_mcp.mount(admin_mcp, prefix="admin")

The Per-Pane Agent Identity Contract defines a canonical way to map a tmux pane to a specific agent name. This allows shell scripts, hooks, and external tools to discover which agent is running in a specific pane without querying the MCP server.

Identities are stored in a file-based system following the XDG Base Directory Specification, ensuring they persist across reboots but remain separate from configuration. The system uses a project-specific hash to ensure multi-project safety.

The project uses Beads Rust (br) as its primary task tracker. The installer automatically replaces the original Go-based Beads CLI (bd) with the Rust implementation.

Key Details:

• Maintenance: br is the actively maintained version; the Go version is no longer maintained.
• Compatibility: The installer creates a shell alias so that bd commands redirect to br, preserving existing workflows.
• Data Format: Both implementations use the same .beads/issues.jsonl format, ensuring existing Beads data remains compatible.
• Agent Support: AI coding agents are provided with a bd-br-migration skill to handle CLI differences between the two versions.

When interacting with MCP Agent Mail, choose between high-level macros for speed/simplicity or granular tools for precise control.

Use Macros for:

• Speed and efficiency, especially when using smaller models.
• Common flows: macro_start_session, macro_prepare_thread, macro_file_reservation_cycle, macro_contact_handshake.

Use Granular Tools for:

• Precise control over the workflow.
• Specific actions: register_agent, file_reservation_paths, send_message, fetch_inbox, acknowledge_message.

File reservations in Agent Mail use repo-root relative paths rather than absolute OS paths. This ensures compatibility across different worktrees and machines.

Path Matching Rules

• Storage: Patterns are stored exactly as provided (e.g., app/api/*.py).
• Normalization: All paths are normalized for separators (/ vs \) and case (on case-insensitive filesystems).
• Matching: The pre-commit guard matches staged files against reservations using Git wildmatch pathspec. It honors core.ignorecase and handles renames/moves by checking both the new path and the old path (via git diff --name-status -M).
• Best Practice: Use narrow patterns (e.g., frontend/**) instead of broad patterns (e.g., **/*) to minimize unnecessary conflicts across teams.

MCP Agent Mail provides integration capabilities for various Flywheel tools:

• NTM: Agent panes coordinate via mail; the dashboard displays the inbox.
• BV: Task IDs are mapped to thread IDs; robot flags inform task selection.
• CASS: Enables searching mail threads across different sessions.
• CM: Allows extraction of procedural memory from mail archives.
• DCG: Notifies agents when commands are blocked.
• RU: Facilitates multi-repo updates via cross-project mail.