MCP Agent Mail — ユースケース, インストール & ライブデモ

なぜ使うのか

主な機能

永続的な受信箱・送信箱を持つエージェントごとのアイデンティティ
全エージェントにまたがる検索可能なメッセージ履歴 (FTS5)
任意のファイルリース — パスを宣言し、完了後に解放
HTTP専用FastMCP (Streamable HTTP)、Dockerで配備可能
フォレンジクス用のハッシュチェーン監査ログ
SaaS依存なし — 自社インフラ上で動作

ライブデモ

実際の動作

mcp-agent-mail.replay ▶ 準備完了

0/0

インストール

クライアントを選択

~/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"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

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

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

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit

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

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json

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

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json

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

context_servers に追加。保存時に Zed がホットリロード。

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

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方： MCP Agent Mail

同一モノリポ上の3つのClaude Codeセッションをマージ地獄なしに調整する

👤 並列エージェントセッションを運用するチーム ⏱ ~30 min intermediate

使うタイミング： フィーチャーブランチごとにエージェントを起動すると、同じファイルを奪い合ってしまう場合。

前提条件

各エージェントからアクセス可能なDockerホスト — docker compose up --build でポート:8765を公開
各エージェントに一意なアイデンティティを付与 — whoami の初回呼び出しで登録；CLAUDE.mdにピン留め

フロー

アイデンティティ確認

Use mcp-agent-mail. Register me as claude-feature-auth and list active leases.✓ コピーしました

→ アイデンティティ永続化；リース一覧返却
編集前にファイルをクレーム

Before editing src/auth/*, take a 30-min lease and announce intent in the #refactor thread.✓ コピーしました

→ リース付与；メッセージが他のエージェントから参照可能
引き継ぎ

Done with the auth module. Release leases, post a summary to #refactor with the diff range.✓ コピーしました

→ リース解放；スレッド更新

結果： 3つのエージェントが互いの編集を上書きすることなく同一リポジトリ上で並列作業を完遂する。

注意点

リースはアドバイザリー — エージェントは無視することができる — CLAUDE.mdにルールを追加：「編集前に必ずリースを確認し、先にインテントを投稿すること」

組み合わせ： filesystem · github

連携するリポジトリ間でエージェント同士が作業を引き継ぐ

👤 フロントエンド/バックエンドのエージェントを管理する開発者 ⏱ ~20 min intermediate

使うタイミング： バックエンドエージェントがAPIの変更を完了し、フロントエンドエージェントが適応する必要がある場合。

フロー

送信

From claude-backend: send claude-frontend a message titled 'New /v2/orders schema' with the OpenAPI diff.✓ コピーしました

→ メッセージ送信；フロントエンドエージェントの受信箱カウントが増加
受信

From claude-frontend: read inbox, summarize new messages, propose component updates.✓ コピーしました

→ フロントエンドエージェントが変更を確認し作業を開始

結果： プロンプトをコピー＆ペーストすることなく、エージェント間で非同期に作業を引き継ぐ。

注意点

マシンをまたいだアイデンティティの混乱 — ホスト名にアイデンティティを紐付けるか、長いランダムサフィックスを使用する

すべてのエージェントメッセージとリースのフォレンジクストレイルを取得する

👤 Opsチーム / エージェントの異常動作をデバッグする担当者 ⏱ ~15 min intermediate

使うタイミング： エージェントが深夜3時に不審な動作をし、誰が誰に何を伝えたかを再構成する必要がある場合。

フロー

検索

Search messages between 02:00 and 04:00 mentioning 'database migration'.✓ コピーしました

→ ハッシュアンカー付きエントリが返却
チェーン検証

Verify the audit chain hasn't been tampered.✓ コピーしました

→ チェーン有効；改ざん検知クリーン

結果： ポストモーテム用の、エージェント通信の防御可能な記録。

注意点

DBが無制限に肥大化する — リテンション削除をスケジュール；月次でS3にアーカイブ

組み合わせ： filesystem

組み合わせ

他のMCPと組み合わせて10倍の力を

mcp-agent-mail + filesystem

並列エージェントのためのリース取得→編集の規律

Before any filesystem.write, claim a lease via mcp-agent-mail.✓ コピーしました

mcp-agent-mail + github

他のエージェントが購読するスレッドにPR通知を投稿する

When my PR merges, post to #merged with the SHA and changed paths.✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング	コスト
whoami	(なし)	任意のエージェントからの最初の呼び出し時	free
send_message	to, subject, body, thread?	別のエージェントに作業を渡すとき	free
read_inbox	since?, limit?	セッション開始時 — キューされている内容を確認する	free
claim_lease	path, ttl_min, reason	他のエージェントが触れる可能性のあるファイルを編集する前	free
release_lease	lease_id	コミット後 / 完了時	free
search_messages	query, from?, to?	フォレンジクスまたはコンテキストの再発掘時	free

コストと制限

運用コスト

APIクォータ: セルフホスト；ハードウェアの性能に依存
呼び出しあたりのトークン: 少量 — 調整呼び出し1回あたり約50〜200 tokenのオーバーヘッド
金額: 無料 (MIT)
ヒント: 運用コストは安価；節約効果は二重作業の回避から生まれる

セキュリティ

権限、シークレット、影響範囲

最小スコープ： エージェントホストとメールサーバー間のネットワークアクセス

認証情報の保管： オプションのベアラートークンを環境変数で管理

データ送信先： 自社インフラ内に留まる — サードパーティへの通信なし

絶対に付与しない： TLS + 認証なしでの公開インターネットへの露出

メッセージの内容は永久に検索可能 — シークレットを貼り付けないこと

トラブルシューティング

よくあるエラーと対処法

:8765への接続拒否

Dockerコンテナが起動中でポートフォワーディングが設定されていることを確認；docker ps で確認

確認： curl http://127.0.0.1:8765/health

アイデンティティの衝突

ランダムなサフィックスを付加するか、ホスト名に紐付ける

古いエージェントにリースが取られたまま

リースはTTLで自動失効；デフォルトTTLを短縮するか管理ツールで強制解放

代替案

MCP Agent Mail 他との比較

代替案	代わりに使う場面	トレードオフ
共有CLAUDE.mdのみ	エージェントが最大2つで低並列の場合	状態なし — 同じファイルをエージェントが読むことに依存
エージェントごとのGitブランチ	ハードな分離が必要な場合	マージコストが増大；リアルタイムシグナリングなし

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る