mcp-delegate

Claude Code（オーケストレーター）に、別のモデル（Ollama経由のローカル、またはOpenRouter経由のリモート）で実行される独立した完全なエージェントループへタスクを委任するツールを提供するMCPサーバー。独自のツールアクセス（ファイル、bashなど）を持ち、最終結果のみを返す——機能的にはネイティブのサブエージェントと同等だが、モデルに依存しない。

完全なビルド計画は mcp-subagent-delegation-plan.md を参照。個別のコミット/チェックポイントとして段階的に分かれている。

Status

フェーズ1、2、3、4が完了。

• delegate_task — 設定済みのOpenAI互換エンドポイント（Ollama、LM Studio、vLLM、OpenRouterなど）に対する単発のチャット補完。

• delegate_agentic_task — 委任されたモデルに、呼び出し元が指定した作業ディレクトリにスコープされた独自のツール使用ループ（read_file、write_file、run_bash）を提供する。ツールの呼び出しを停止するか、max_iterations に達するか、timeout_seconds を超えるまで実行される。

• list_recent_delegations — 過去の委任（どちらのツールでも）が実際に何をしたかを、ログを掘り返したり再実行したりせずに確認する。

• get_delegation_transcript — capture_transcript=True で実行された場合の、1回の委任の完全なメッセージ/ツール呼び出しトランスクリプト（例：モデル比較/評価実行用）。

元の計画からの逸脱: フェーズ2では agent-loop をサブプロセスとしてラップする予定だった。agent-loopはLinux/macOS/WSLのみをサポートしており、このサーバーはWindows上でネイティブに動作する必要があるため、代わりにフェーズ5の代替案として説明されているインプロセスループを構築した——同じツールインターフェースで、サブプロセス/ANSIストリッピングの複雑さがなく、agent-loopのAGPL/商用不可ライセンスを完全に回避できる。delegate/agentic.py を参照。

安全性に関する注意: working_dir は呼び出し元が指定するものであり、固定されたサンドボックスではない——委任されたモデルは、指定されたディレクトリに対して無人でファイル/bashアクセスができる。ファイルツール（read_file/write_file）は working_dir 内に留まるようにスコープされている。run_bash はそのディレクトリを cwd として実行されるが、シェルコマンドは完全にはサンドボックス化されておらず、そこから逃げ出せる可能性がある（例：cd ..）。無人モデルが読み取り、書き込み、コマンド実行を行っても問題ないディレクトリを指定すること。

ガードレールに関する注意: 元の計画のフェーズ4では、agent-loop自身のガードレール（反復上限、繰り返し検出）が有効であることを確認するよう求めていた。agent-loopを使用していないため、これは直接には適用されない——我々のループには独自の max_iterations と timeout_seconds の上限（テストで検証済み）があるが、繰り返し検出はない。2つのツール呼び出しを交互に繰り返してスタックしたモデルは、早期に検出されるのではなく max_iterations に達するまで実行される。実際にそのような事態が発生するようなら追加する価値がある。

Related MCP server: deepseek-subagent-mcp

Setup

uv sync
cp .env.example .env             # fill in DELEGATE_BASE_URL / DELEGATE_API_KEY / DELEGATE_MODEL
cp models.json.example models.json   # optional: named backends, see below

Multiple backends

両方のツールはオプションの backend パラメータを受け取り、デフォルトの DELEGATE_* 環境変数の代わりに models.json から base_url/model/api_key を参照する——例えば、同じターン内で一方の呼び出しに backend="ollama-local"、もう一方に backend="openrouter-free" を指定し、それぞれを並行して実行できる。model も指定された場合は、そのバックエンド内のモデル文字列のみを上書きする。

キーを models.json に直接書く代わりに、環境変数を参照する:

{
  "openrouter-free": {
    "base_url": "https://openrouter.ai/api/v1",
    "model": "nvidia/nemotron-nano-9b-v2:free",
    "api_key_env": "OPENROUTER_API_KEY"
  }
}

models.json は .env と同じくgitignoreされている。

Concurrency

MCPツール呼び出しはすでに個別のワーカースレッドで実行されるため、追加の配管なしで並行委任が並列実行される。DELEGATE_MAX_CONCURRENCY（デフォルト4、.env.example を参照）は、両方のツール、任意のバックエンドにわたって同時に実行される委任の数を制限し、大規模なファンアウトがローカルモデルサーバーや有料APIのレート制限を圧迫するのを防ぐ。

サーバーを直接実行する（主にエラーなく起動するかを確認するのに有用——その後、MCPクライアントのためにstdioで待機する）:

uv run server.py

Logging

delegate_task/delegate_agentic_task のすべての呼び出し——成功か失敗かに関わらず——はローカルのSQLiteファイル delegations.db（gitignoreされ、初回使用時に作成）に記録される: ツール、バックエンド、モデル、タスクテキスト、開始/終了時刻、反復回数、成功/失敗、切り詰められた結果/エラープレビュー、およびバックエンドが返した場合はトークン使用量。list_recent_delegations ツールで照会するか、sqlite3 delegations.db "select * from delegations order by id desc limit 20" で直接照会できる。ロギングはベストエフォートであり——ロギングの失敗で、それ以外は成功した委任が失敗することはない。

両方のツールは、バックエンドが使用量を報告した場合、戻り値の末尾に [tokens: N prompt / N completion / N total ($cost)] の行を追加する。これにより、呼び出し元のエージェントは別途 list_recent_delegations を呼び出さなくてもすぐに確認できる。

Cost tracking

pricing.json はモデル文字列 → {input_per_million, output_per_million} のUSDレートをマッピングする。呼び出しの解決されたモデルにエントリがある場合、コストは実際のトークン使用量から計算され、delegations.db（cost_usd カラム）に記録され、[tokens: ...] サフィックスに含まれる。エントリがないモデルは cost_usd = NULL が記録される——無料と見なすのではなく不明として——つまり、エントリの欠落が支出を黙って過小報告することはない。ローカルモデルは通常その理由でエントリを持たない。本当に無料のモデル（例：OpenRouterの :free モデル）は、省略される代わりに明示的な {"input_per_million": 0, "output_per_million": 0} エントリが与えられる。

.env/models.json とは異なり、pricing.json は秘密情報でも環境固有でもないため、gitignoreされるのではなく直接コミットされる。価格は変動する——同梱のファイルは、これが構築されたモデル比較ベイクオフで指定されたモデルについて、2026-08-21にOpenRouterの /api/v1/models から取得されたもの。必要に応じて再取得して編集し、モデルを追加/更新すること。

Transcript capture (model comparison / eval runs)

両方のツールは capture_transcript: bool = False を受け取る。設定すると、最終回答だけでなく、すべてのモデルメッセージ、ツール呼び出し、ツール結果を含む完全なメッセージ交換が記録され、戻り値に [delegation_id: N] サフィックスが付く。get_delegation_transcript(delegation_id) で取得できる。

これは、同じタスクを複数の異なるモデル/バックエンドで実行し、最終回答だけでなく各モデルがどのようにそこに到達したか（ツール選択、不正な形式のツール呼び出し、リトライ）を比較するために存在する——例えば、本番使用のために1つを選ぶ前に候補モデル間でベイクオフを行う場合など。通常の委任には不要な追加のロギングオーバーヘッドであるため、デフォルトではオフ。

Register with Claude Code

プロジェクトスコープの .mcp.json はすでにチェックインされている（uv run server.py）。このディレクトリでClaude Codeを再起動するか、claude mcp list を実行して delegate サーバーが認識されたことを確認し、次に簡単なプロンプトで delegate_task を呼び出すよう依頼してラウンドトリップを確認する。

Tools

• delegate_task(prompt, model=None, system_prompt=None, backend=None, capture_transcript=False) -> str — 設定済みバックエンドに対する単発のチャット補完。

• delegate_agentic_task(task, working_dir, model=None, max_iterations=20, timeout_seconds=600, backend=None, capture_transcript=False) -> str — working_dir にスコープされた read_file/write_file/run_bash ツールを使ったマルチステップ委任。 capture_transcript=True の場合を除き、完全なトランスクリプトではなく最終回答のみを返す。

• list_recent_delegations(limit=20) -> list[dict] — 直近に記録された委任を新しい順で返す。

• get_delegation_transcript(delegation_id) -> list[dict] — capture_transcript=True で記録された1回の委任の完全なトランスクリプト。

delegate_task/delegate_agentic_task は、エラー（設定ミス、到達不能なエンドポイント、タイムアウト、反復上限）を例外として発生させるのではなく "Error: ..." 文字列として返す。これにより、呼び出し元のエージェントが何が問題だったかを確認できる。