Agent Handoff MCP

Agent Handoff MCP

AI エージェント間で、範囲が限定され監査可能なハンドオフを行うための、ローカル優先のModel Context Protocolサーバーです。

Agent Handoff MCPを使うと、Claude、Codex、ローカルエージェント、その他のMCPクライアントが、あるモデルに別のモデルを制御させることなく、共有受信トレイを利用できます。エージェントは、構造化された作業を送信し、受領を確認し、ブロッカーを報告し、完了を報告するか、自分が最初にキューに登録した作業をキャンセルできます。すべての状態遷移は実行者を特定でき、SQLiteに保持されます。

なぜ必要なのか

マルチエージェントシステムでは、チャットの記録、その場しのぎのファイル、またはベンダー固有のオーケストレーションを通じて作業が引き継がれることがよくあります。これでは、所有権、ライフサイクルの状態、認可の境界、永続的な監査証跡が失われます。このサーバーは、ハンドオフを小さなプロトコルオブジェクトにします。

sender -> queued -> accepted -> completed
                   |             ^
                   v             |
                 blocked --------+

sender may cancel only while queued

このサーバーは作業を調整しますが、エージェントの実行、参照情報の取得、任意のファイルの読み込み、自律的なエージェントループの作成は行いません。

MCP ツール

ツール	目的
handoff_whoami	認証されたID、境界、ポリシーのリビジョンを表示します。
handoff_send	認可された受信者に構造化されたハンドオフを送信します。
handoff_inbox	現在のID宛てのハンドオフを一覧表示します。
handoff_get	ハンドオフと追記専用のイベント履歴を読み取ります。
handoff_acknowledge	キュー済みまたはブロック中の作業を受け入れます。
handoff_update_status	作業をブロック中または完了にし、キュー済みの場合はキャンセルします。

設計上の特性

• WALモードとパラメーター化クエリを使用するSQLite共有状態
• Streamable HTTPおよびstdioトランスポート
• 不透明なUUID形式のハンドオフ、イベント、スレッドの識別子
• 明示的なsend_toおよびreceive_from認可。許容的なデフォルトはありません
• エージェントごとの情報開示上限：public-safe、internal、またはrestricted
• 厳格なレジストリ検証：未知のキー、重複、未サポートのバージョンは拒否されます
• 不変のポリシースナップショット：各操作は現在のレジストリに照らして確認されるため、再起動しなくても、IDの無効化、トークンのローテーション、関係の制限がライブセッションに反映されます
• HTTP用の、有効期限付きでハッシュ化されたベアラートークンのバインディング
• 安全な再試行のための冪等性キー
• 自動的な応答の往復を制限する、返信チェーンの最大深度
• メッセージ、配列、参照、リクエストサイズの厳格な上限
• 送信者と受信者のみが読み取り可能。現在のポリシーに照らして再認可されます
• 追記専用のライフサイクルイベント。MCPの削除ツールはありません
• 参照は不活性な文字列として保存され、参照先の取得は行われません

コマンドライン

このパッケージは、agent-handoff-mcpというディスパッチャーバイナリを1つインストールします。パッケージ名と同じ名前なので、パッケージがnpmに公開されると、npx @sarutobi-sasuke/agent-handoff-mcp <command>で直接実行できます。（まだ公開されていないため、それまではソースのチェックアウトを使用してください。）

コマンド	目的
http	共有Streamable HTTPサーバーを起動します。
stdio	HANDOFF_AGENT_IDにバインドされたstdioサーバーを起動します。
init --registry <path>	無効化された合成IDを含むスターターレジストリを作成します。
validate --registry <path>	トークンやデータベースを読み込まずにレジストリを検証します。
issue --registry <path> --agent <id> --expires <iso8601>	有効期限付きトークンを発行し、stdoutに一度だけ出力します。
rotate ...	既存のトークンを置き換えます。古いトークンは直ちに使えなくなります。
disable / enable	すべてのトランスポートでIDの有効・無効を切り替えます。
revoke	IDのトークンバインディングを削除します。
token	レジストリに触れずにトークンとダイジェストを生成します。

agent-handoff-http、agent-handoff-stdio、agent-handoff-token、agent-handoff-validateも、直接実行できるエイリアスとしてインストールされます。

クイックスタート

要件：Node.js 22.13 以降。

ソースをチェックアウトしている場合：

git clone https://github.com/SarutobiSasuke8/agent-handoff-mcp.git
cd agent-handoff-mcp
npm ci
npm run build
cp .env.example .env
node dist/src/cli.js init --registry ./config/agents.yaml
node dist/src/cli.js issue --registry ./config/agents.yaml --agent example-alpha --expires 2027-01-01T00:00:00Z
node dist/src/cli.js issue --registry ./config/agents.yaml --agent example-beta --expires 2027-01-01T00:00:00Z
node dist/src/cli.js enable --registry ./config/agents.yaml --agent example-alpha
node dist/src/cli.js enable --registry ./config/agents.yaml --agent example-beta
node dist/src/cli.js validate --registry ./config/agents.yaml
npm run check
npm start

各 issue コマンドは、その ID の未加工トークンを一度だけ出力します。安全なチャネルを通じて、そのクライアントに渡してください。保存されるのは SHA-256 ダイジェストのみです。PowerShell および POSIX のクリーンルームでの手順全体については、docs/QUICKSTART.md を参照してください。

デフォルトのエンドポイントは次のとおりです。

GET  http://127.0.0.1:3220/healthz   liveness and policy state
GET  http://127.0.0.1:3220/readyz    readiness; 503 while the policy is degraded
POST http://127.0.0.1:3220/mcp
Authorization: Bearer handoff_<agent-specific-token>

デフォルトでは、サーバーは localhost にバインドします。リモート環境にデプロイする前に、認証済みのプライベートネットワークまたは TLS の境界を前段に設けてください。

Stdio モード

各 stdio クライアントは、それぞれのプロセス環境を通じて自身の ID を指定し、同じ SQLite データベースとレジストリを共有します。

{
  "command": "node",
  "args": ["/absolute/path/agent-handoff-mcp/dist/src/cli.js", "stdio"],
  "env": {
    "HANDOFF_AGENT_ID": "example-beta",
    "HANDOFF_MCP_DB": "/absolute/shared/path/handoffs.sqlite",
    "HANDOFF_MCP_REGISTRY": "/absolute/path/agents.yaml"
  }
}

複数のクライアントが 1 つの長時間稼働するサービスに接続する場合は、HTTP を使用してください。各クライアントの設定を通じて固定 ID を安全に受け取れるローカルクライアントには、stdio を使用してください。どちらのトランスポートもすべての操作でレジストリを再確認するため、実行中の stdio セッションにも失効が適用されます。

ローカル HTTP 適合性チェック

ソースをチェックアウトして npm ci を実行した後、npm run conformance を実行してください。既存の固定された Registry スキーマに対する server.json の検証、分離されたループバックサーバーと使い捨ての SQLite レジストリフィクスチャの起動、curl を使ったベアラーリクエストの欠落および無効ケースの確認、公式フレームワークに加えて Inspector の tools/list と読み取り専用の handoff_whoami 呼び出しを実行します。curl と、バージョンが正確に固定された npx ツールへのネットワークアクセスが必要です。オペレーターのレジストリ、既存のデータベース、保存済みログイン情報、稼働中のサービスは使用しません。

検証対象の仕様リビジョンは 2026-07-28 で、@modelcontextprotocol/[email protected] --requirements 2026-07-28 を使用します。現在の HTTP トランスポートの対象は 2025-11-25 です。ステートレスなリクエスト処理だけでは、新しいライフサイクルへの対応は証明できません。Inspector の @modelcontextprotocol/[email protected] は、アプリケーションのスモークテストで旧プロトコル時代を明示的に使用します。上流のフレームワークにはベアラーヘッダーのフラグがないため、テスト専用の fetch アダプターが、一時的なフィクスチャヘッダーをそのループバックエンドポイントにのみ追加します。本番の認証は変更せずにテストされます。

このチェックは、現在、リビジョンの差異により 1 で終了します。検出事項と秘匿化済みログは、無視対象の release-evidence/conformance/ に出力されます（HANDOFF_CONFORMANCE_OUTPUT で変更できます）。別のチェックが失敗しても、すべてのチェックを実行します。失敗がランナー内で黙ってベースライン化されたり、修復されたりすることはありません。リリースゲートとして提案する前に、初回実行時の検出事項を参照してください。このコマンドは公開も CI の変更も行いません。

運用メトリクス

HANDOFF_MCP_METRICS=1 を設定すると、作成、受け入れ（claim 済み）、期限切れのハンドオフ数とストアエラーについて、プロセス内カウンターを記録できます。また、ツール呼び出し時間のヒストグラムも記録されます。claim としてカウントされるのは、初回の queued から accepted への移行のみです。デフォルトでは無効です。有効にすると、HTTP サーバーと stdio サーバーの両方が、起動時、60 秒ごと、正常終了時に、ローカルの stderr に JSON スナップショットを 1 件出力します。たとえば、HANDOFF_MCP_METRICS=1 agent-handoff-mcp stdio 2>metrics.jsonl を実行すると、MCP の stdout に混在させずに、実行中プロセスのスナップショットを取得できます。src/metrics.ts のスナップショットは、OpenTelemetry の OTLP JSON 形式に沿った resourceMetrics/scopeMetrics 構造を使用します。固定のメトリクス名、カウント、時間、上限付きのツール名ラベルのみを含み、ハンドオフの内容、タイトル、エージェントのテキスト、トークンがレコーダーに入ることはありません。ネットワークエクスポーターやパブリックなメトリクスエンドポイントは設定されていません。現在のハンドオフライフサイクルには期限切れへの遷移がないため、期限切れカウンターは 0 のままです。

ドキュメント

MCP Registry のドラフトマニフェストは、stdio 引数を指定して npm バイナリを起動し、運用担当者に HANDOFF_AGENT_ID、HANDOFF_MCP_REGISTRY、HANDOFF_MCP_DB を要求します。ID や認証情報は作成しません。 名前空間には、GitHub の所有者名の正確な表記である io.github.SarutobiSasuke8 を使用します。 prepublishOnly には check:registry が含まれます。公開とレジストリへのログインは、引き続き別々の運用担当者の操作です。ビルドではソースマップとその JavaScript リンクは省略されます。

• クリーンルームでのクイックスタート
• プロトコルとライフサイクル
• アーキテクチャ
• セキュリティモデル
• Registry JSON Schema
• ロードマップ
• リリース検証、2026-10-01
• 変更履歴

範囲の境界

このプロジェクトは調整のためのプリミティブであり、汎用タスクプラットフォームではありません。共有タスクボード、意思決定、ブロードキャスト、プレゼンス、リース、通知、コンテキストの昇格、リモートディスパッチは、今後のオプションモジュールの対象です。6 つのツールからなるハンドオフ機能は、安定したコアとして維持されます。

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。

復旧とローカルリリースの証跡

agent-handoff-mcp backup <out-file> を使用すると、検証済みレジストリを含む、稼働中の WAL スナップショットを作成できます。サーバーを停止した後、新しいファイルに restore <file> を実行します。既存の保存先には --force が必要です。稼働中のサーバー、破損したバックアップ、不完全な復元は引き続きブロックされます。コマンド、ポリシーの照合、ローカルプロセスガードの制限については、復旧を参照してください。

ローカルの SQLite ストアは、起動時に schema_migrations テーブルを使って、順序付けされ記録されたマイグレーションを適用します。バージョン管理されていない既存のストアを認識し、保留中の変更を適用する前に、確認したスキーマを記録します。スキーマのバージョンが新しいストアは、明確なエラーを表示して開くことを拒否します。データベースをダウングレードするのではなく、互換性のあるバイナリを使用してください。

npm run release:dry-run は、ローカルチェック、E2E 復旧の証明、許可リストの検証、SPDX SBOM、tarball、SHA-256 の証跡を、Git で無視される release-evidence/ に生成します。パッケージの公開は、引き続き所有者が行います。