gabrielmoreira Using MCP Agent Mail
Core Insight: Without coordination, multiple agents overwrite each other's work. Agent Mail provides identities, messaging, and file reservations to prevent conflicts.
When to Use What
| Situation | Action |
|---|---|
| Starting any agent session | macro_start_session |
| About to edit files | file_reservation_paths → edit → release_file_reservations |
| Need to tell another agent something | send_message with thread_id |
| Picking up someone else's work | macro_prepare_thread |
| Can't message an agent | request_contact → wait for approval |
| Server seems broken | Use health_check() first; CLI-only: doctor check --verbose → doctor repair --yes |
THE EXACT PROMPT — Session Bootstrap
Call this at the start of every agent session:
macro_start_session(
human_key="/abs/path/to/project",
program="claude-code",
model="YOUR_MODEL",
task_description="Working on auth module"
)
Returns: {project, agent, file_reservations, inbox}
This single call: ensures project exists → registers your identity → fetches inbox.
Core Operations
| Task | Tool |
|---|---|
| Bootstrap session | macro_start_session(human_key, program, model, task_description) |
| Send message | send_message(project_key, sender_name, to, subject, body_md) |
| Reply in thread | reply_message(project_key, message_id, sender_name, body_md) |
| Check inbox | fetch_inbox(project_key, agent_name, limit=20) |
| Reserve files | file_reservation_paths(project_key, agent_name, paths, ttl_seconds) |
| Release files | release_file_reservations(project_key, agent_name) |
| Search messages | search_messages(project_key, "query") |
The Four Macros
| Macro | When to Use |
|---|---|
macro_start_session |
Bootstrap: project → agent → inbox |
macro_prepare_thread |
Join existing thread with summary |
macro_file_reservation_cycle |
Reserve → work → auto-release |
macro_contact_handshake |
Cross-agent contact setup |
Fast Resource Reads (No Tool Call Required)
| Need | Resource |
|---|---|
| List agents | resource://agents/{project_key} |
| Inbox | resource://inbox/{agent}?project=/abs/path&limit=20 |
| Thread | resource://thread/{thread_id}?project=/abs/path&include_bodies=true |
| Ack-required | resource://views/ack-required/{agent}?project=/abs/path |
File Reservations
Reserve Before Editing
file_reservation_paths(
project_key="/abs/path/project",
agent_name="GreenCastle",
paths=["src/auth/**/*.ts"],
ttl_seconds=3600,
exclusive=true,
reason="bd-123"
)
Returns: {granted: [...], conflicts: [...]}
Conflict Resolution
If conflicts exist:
- Wait — TTL will expire
- Coordinate — Message the holder
- Share — Use
exclusive=false
Release When Done
release_file_reservations(project_key="/abs/path/project", agent_name="GreenCastle")
Beads Integration
Use bead IDs as your threading anchor:
1. Pick work: br ready --json → choose bd-123
2. Reserve files: file_reservation_paths(..., reason="bd-123")
3. Announce: send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
4. Work: Reply in thread with progress
5. Complete: br close bd-123, release_file_reservations(...), final message
Bead ID (often bd-###) goes in: thread_id, subject prefix, reservation reason, commit message
Quick Troubleshooting
| Error | Fix |
|---|---|
| "sender_name not registered" | Call macro_start_session first |
| "FILE_RESERVATION_CONFLICT" | Wait, coordinate, or use exclusive=false |
| "CONTACT_BLOCKED" | Use request_contact, wait for approval |
| Empty inbox | Check since_ts, urgent_only, agent name spelling |
| Server unreachable | Use health_check() or resource://config/environment to confirm MCP server is up; if CLI-only, check curl http://127.0.0.1:8765/health |
| Guard blocks commit | Set AGENT_NAME env var; bypass: AGENT_MAIL_BYPASS=1 git commit |
Doctor Diagnostics (CLI-only, optional)
# Quick health check (CLI daemon)
curl http://127.0.0.1:8765/health
# Full diagnostics (CLI)
uv run python -m mcp_agent_mail.cli doctor check --verbose
# Preview repairs (dry run, CLI)
uv run python -m mcp_agent_mail.cli doctor repair --dry-run
# Apply repairs (CLI)
uv run python -m mcp_agent_mail.cli doctor repair --yes
Agent Identity
Agents get adjective+noun names: GreenCastle, BlueLake, RedBear.
Best practice: Omit name parameter to auto-generate valid names.
register_agent(
project_key="/abs/path/project",
program="claude-code",
model="YOUR_MODEL",
task_description="Auth refactor"
) # name auto-generated
Human Overseer
Send urgent messages to agents from the web UI at http://127.0.0.1:8765/mail:
- Click "Human Overseer" mode
- Compose with
importance: urgent - Select target agents
Agents see urgent messages via fetch_inbox(..., urgent_only=true).
Pre-Commit Guard
install_precommit_guard(project_key="/abs/path", code_repo_path="/abs/path")
- Set
AGENT_NAMEenv var so guard knows who you are - Bypass emergency:
AGENT_MAIL_BYPASS=1 git commit -m "fix" - Warning mode:
AGENT_MAIL_GUARD_MODE=warn
Search Syntax (FTS5)
"exact phrase"
prefix*
term1 AND term2
term1 OR term2
(auth OR login) AND NOT admin
References
| Topic | Reference |
|---|---|
| All MCP tools | TOOLS.md |
| Workflow patterns | WORKFLOWS.md |
| MCP resources | RESOURCES.md |
| Cross-project setup | CROSS-PROJECT.md |
| Doctor & recovery | RECOVERY.md |
| Installation | INSTALL.md |
| Fix MCP config | FIX-MCP-CONFIG.md |
| Product bus, build slots, internals | ADVANCED.md |
Validation
# Server health
curl http://127.0.0.1:8765/health
# → {"status": "healthy"}
# Start server if needed
am