MCP Agent Mail — Use Cases, Install & Live Demo

Why use it

Key features

Per-agent identities with persistent inboxes and outboxes
Searchable message history (FTS5) across all agents
Voluntary file leases — claim a path, release when done
HTTP-only FastMCP (Streamable HTTP), Docker-shippable
Hash-chained audit log for forensics
No SaaS dependency — runs on your infra

Live Demo

What it looks like in practice

mcp-agent-mail.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-agent-mail",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-agent-mail": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "http://127.0.0.1:8765/mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add mcp-agent-mail -- npx -y mcp-remote http://127.0.0.1:8765/mcp

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use MCP Agent Mail

Coordinate 3 Claude Code sessions on the same monorepo without merge hell

👤 Teams running parallel agent sessions ⏱ ~30 min intermediate

When to use: You spawn agents per feature branch and they keep grabbing the same files.

Prerequisites

Docker host reachable from each agent — docker compose up --build exposes :8765
Each agent gets a unique identity — First call to whoami registers; pin it in CLAUDE.md

Flow

Identify

Use mcp-agent-mail. Register me as claude-feature-auth and list active leases.✓ Copied

→ Identity persisted; lease list returned
Claim files before edit

Before editing src/auth/*, take a 30-min lease and announce intent in the #refactor thread.✓ Copied

→ Lease granted; message visible to other agents
Hand off

Done with the auth module. Release leases, post a summary to #refactor with the diff range.✓ Copied

→ Lease released; thread updated

Outcome: Three agents finish parallel work on the same repo without overwriting each other's edits.

Pitfalls

Leases are advisory — agents can still ignore them — Add a CLAUDE.md rule: 'Always check leases before edit, post intent first'

Combine with: filesystem · github

Hand work between agents working on linked repos

👤 Devs juggling frontend/backend agents ⏱ ~20 min intermediate

When to use: Backend agent finishes an API change; frontend agent needs to adapt.

Flow

Send

From claude-backend: send claude-frontend a message titled 'New /v2/orders schema' with the OpenAPI diff.✓ Copied

→ Message dispatched; frontend agent's inbox count increments
Receive

From claude-frontend: read inbox, summarize new messages, propose component updates.✓ Copied

→ Frontend agent acks the change and starts work

Outcome: Async handoff between agents without you copy-pasting prompts.

Pitfalls

Identity confusion across machines — Bind identity to hostname or use long random suffix

Get a forensic trail of every agent message and lease

👤 Ops / debugging agent misbehavior ⏱ ~15 min intermediate

When to use: An agent did something weird at 3am and you need to reconstruct who told whom what.

Flow

Search

Search messages between 02:00 and 04:00 mentioning 'database migration'.✓ Copied

→ Hash-anchored entries returned
Verify chain

Verify the audit chain hasn't been tampered.✓ Copied

→ Chain valid; tamper detection clean

Outcome: Defensible record of agent communication for postmortem.

Pitfalls

DB grows unbounded — Schedule retention pruning; archive to S3 monthly

Combine with: filesystem

Combinations

Pair with other MCPs for X10 leverage

mcp-agent-mail + filesystem

Lease-then-edit discipline for parallel agents

Before any filesystem.write, claim a lease via mcp-agent-mail.✓ Copied

mcp-agent-mail + github

Post PR notifications to a thread other agents subscribe to

When my PR merges, post to #merged with the SHA and changed paths.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
whoami	(none)	First call from any agent	free
send_message	to, subject, body, thread?	Hand work to another agent	free
read_inbox	since?, limit?	Start of session — see what's queued	free
claim_lease	path, ttl_min, reason	Before editing a file other agents may touch	free
release_lease	lease_id	After commit / when done	free
search_messages	query, from?, to?	Forensics or rediscovering context	free

Cost & Limits

What this costs to run

API quota: Self-hosted; bound by your hardware
Tokens per call: Tiny — ~50–200 tokens overhead per coordination call
Monetary: Free (MIT)
Tip: Cheap to run; the cost is the agent calls you avoid by not double-doing work

Security

Permissions, secrets, blast radius

Minimum scopes: Network access between agent host and mail server

Credential storage: Optional bearer token in env

Data egress: Stays on your infra — no third-party calls

Never grant: Public exposure without TLS + auth

Anything in messages is searchable forever — don't paste secrets

Troubleshooting

Common errors and fixes

Connection refused on :8765

Verify Docker container is up and port forwarded; check docker ps

Verify: curl http://127.0.0.1:8765/health

Identity collision

Append a random suffix or bind to hostname

Lease taken by stale agent

Leases auto-expire by TTL; reduce default TTL or force-release admin tool

Alternatives

MCP Agent Mail vs others

Alternative	When to use it instead	Tradeoff
Plain shared CLAUDE.md	Two agents max, low concurrency	No state — relies on agents reading the same file
Git branches per agent	You want hard isolation	Merge cost grows; no real-time signaling

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills