MCP ツールカタログ

エージェントは Chorus の MCP（Model Context Protocol）ツールを通じて Chorus を操作します。本ページは、 このツール群のカテゴリー別ガイドです。クライアントがどう接続するか、プロジェクトの範囲指定がどう働くか、 各ツールがどう可視になるか、そして各段階でエージェントが使う高頻度のツールを扱います。エンティティが 経ていく状態と各段階の引き継ぎはエンティティのライフサイクルリファレンスを、コメント・メンション・ 通知はコラボレーションリファレンスをご覧ください。

エンドポイントとトランスポート

Chorus は Streamable HTTP で単一の MCP エンドポイントを公開します。

POST https://chorus.example.com/api/mcp
Authorization: Bearer cho_REDACTED

このエンドポイントはステートレスです。各リクエストはエージェントの API キーで認証され、リクエストごとの 新しいサーバーインスタンスによって処理されます。サーバー側のセッションはなく、initialize → キープ アライブ → 期限切れの流れもなく、無操作タイムアウトもありません。クライアントは「session not found」 状態を回復する必要が一切なく、ただ毎回のリクエストでキーを送るだけです。ここから二つの帰結が生じます。

• 権限はリクエストごとに再計算される。 UI でエージェントの権限を変更すると、次の呼び出しから 即座に効き、再接続は不要です。
• エージェントの API キーだけがツール一覧を決める。 tools/list が返すツールの集合は、そのキーのリクエスト ごとの有効権限から導かれます。

クライアントの MCP 設定では、これを http 型のサーバーとして設定します。最小の .mcp.json ブロック：

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "https://chorus.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cho_REDACTED"
      }
    }
  }
}

シェルからは、chorus mcp call <tool> で同じエージェント認証情報を使ってこれらのツールを呼び出せるため、 スクリプトや一度きりの呼び出しでもモデルのトークンを消費せずに済みます。 chorus CLIを参照してください。

ノート

MCP トランスポートのセッションは、Chorus のエージェントセッションとは無関係です。エージェントセッションは スウォームモードのサブエージェントを追跡してその作業を見えるようにするもので、下記の session ツールで作成・管理します。

プロジェクトによる範囲指定

多くのプロジェクトにまたがって働くエージェントは、MCP 接続に範囲指定ヘッダーを送ることで、結果を 特定のプロジェクトに絞り込めます。

ヘッダー	値	効果
X-Chorus-Project	単一のプロジェクト UUID、またはカンマ区切りで複数	結果をそのプロジェクトに限定する。
X-Chorus-Project-Group	プロジェクトグループ UUID	結果をそのグループ内のすべてのプロジェクトに限定する。

ヘッダーがない場合、結果はすべてのプロジェクトにわたります（既定）。両方のヘッダーがある場合は X-Chorus-Project-Group が優先します。これらのヘッダーに従うのは chorus_get_my_assignments だけで、範囲指定された プロジェクトに絞ったプロジェクト別トラッカーを返します。chorus_checkin の ideaTracker はヘッダーで フィルターされません。常にすべてのプロジェクトにわたる、エージェントの最も新しい着想（上限十件）を返します。 それ以外のすべてのツールは明示的な projectUuid 引数を取り、ヘッダーの影響を受けません。

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "https://chorus.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cho_REDACTED",
        "X-Chorus-Project": "uuid-a,uuid-b"
      }
    }
  }
}

権限とツールの可視性

ツールの可視性は、きめ細かな権限モデルで決まります。5 つの資源 （idea、proposal、document、task、project）× 3 つの動作 （read、write、admin）= 15 の権限ビットです。制限される各ツールは、必要な権限をちょうど一つ 宣言します。制限されるツールは、エージェントの有効権限セットがそのビットを含む場合にのみ、その tools/list に現れます。共通ツールは制限されず、常に現れます。

エージェントの有効セットは、ロールプリセットと、その上に追加された任意のカスタム権限の和集合です。

プリセット	有効な権限セット
developer_agent	*:read + task:write（6 ビット）
pm_agent	*:read + idea:write、proposal:write、document:write、task:write、project:write（10 ビット）
admin_agent	全 15 ビット（*:read + *:write + *:admin）

可視であることは、認可されていることと同じではありません。ツールは可視でも、実行時に操作を拒む ことがあります。たとえば課題の作業上の状態遷移（着手・提出など）は、誰がそのツールを見られるかにかかわらず、呼び出し元が その課題の担当者であることを要します。

プロジェクトのアクセス権

権限ビットは、エージェントがどのツールを持つかを決めます。プロジェクトのアクセス権は、それをどこで使えるかを 決めます。エージェントは各プロジェクトに対して、その所有者のアクセス権で行動します （プロジェクトを閲覧できる人を管理するを参照）。所有者のいないエージェントは公開 プロジェクトしか使えません。どちらの確認も、すべての呼び出しで適用されます。

• 非表示は「見つからない」と同じです。 所有者がアクセスできない非公開プロジェクトと、その中のすべての 着想・提案・文書・課題・コメントは、一覧と検索から除かれ、存在しない ID と同じ not-found エラーを返します。
• ロールが足りなければ forbidden です。 所有者のロールが足りない場合（たとえば閲覧者が書き込む場合や、 非公開プロジェクトで編集者が管理者専用の操作をする場合）、呼び出しは forbidden エラーで失敗します。 読み取りは引き続き機能します。所有者のロールが変わるまでは、再試行しても解決しません。
• chorus_get_project は、プロジェクトの visibility と呼び出し元の accessLevel （viewer、editor、admin のいずれか）を報告します。
• chorus_admin_create_project と chorus_admin_create_project_group は visibility （public または private）を受け付けます。作成したプロジェクトやグループでは、エージェントの所有者が管理者になります。非公開グループの中に 作成したプロジェクトは非公開になります。
• chorus_admin_update_project_group は、グループの visibility を変更でき、明示的なグループメンバーを一度に 一人ずつ管理できます（memberAction：add、update、remove のいずれかと、userUuid および role）。 chorus_admin_move_project_to_group はプロジェクトを移動するか、グループから外します。グループの visibility を変更するときやプロジェクトを移動するときは、まず preview: true を付けてツールを呼び出し、 アクセス権への影響と confirmationToken を受け取ってから、そのトークンを付けて同じ変更を繰り返します。 メンバーの変更はプレビューなしで直接適用されます。
• グループの公開範囲やメンバーを変更するには、所有者がグループの管理者である必要があります。非公開プロジェクトの 移動、非公開グループへの移動や非公開グループからの移動、または誰かのアクセス権を広げる移動には管理者が 必要です。それ以外の移動には編集者が必要です。
• chorus_search_mentionables は任意の entityType と entityUuid を受け取ります。着想・提案・文書・課題から メンションするときにこれらを渡すと、それを閲覧できる人だけが候補になります。
• プロジェクトのメンバーと既存プロジェクトの公開範囲は Web UI で管理します。そのための MCP ツールはありません。

ツールのカテゴリー

カテゴリー	制限	何を扱うか
共通（Public）	なし、常に可視	発見と読み取り（chorus_get_*、chorus_list_*、chorus_search*）、chorus_checkin、chorus_get_my_assignments、コメント、要件詳細化の回答、通知、そして chorus_create_tasks と chorus_update_task。
セッション（Session）	なし、常に可視	スウォームモードのワーカー向けエージェントセッションのライフサイクル：chorus_create_session、chorus_session_checkin_task / chorus_session_checkout_task、chorus_session_heartbeat、chorus_close_session、chorus_reopen_session、chorus_list_sessions、chorus_get_session。
開発者（Developer）	task:write	課題の担当、解除、報告、そして検証への提出。
PM	idea:write、proposal:write、document:write、project:write	着想、要件詳細化、提案、文書、参考資料の作成と推進。
管理者（Admin）	*:admin（プロジェクト／グループの作成は project:write）	提案の承認、課題の検証／再オープン／クローズ、受け入れ基準のマーク、エンティティの削除、プロジェクトとグループの管理。

注意

chorus_create_report は共通ツールに見えます。pm_ 接頭辞がなく、共通ツールと同じ場所で定義されているからです。 しかしそれは document:write で制限されます。そのビットを持つエージェント（pm_agent / admin_agent プリセット、または document:write をカスタム権限として加えた開発者エージェント）にのみ 現れます。制限のない共通ツールとして扱わないでください。

chorus_create_tasks と chorus_update_task は実際に共通ツールです。どのエージェントも課題のフィールド、依存、 受け入れ基準を編集できますが、課題を in_progress や to_verify に移せるのはその課題の担当者だけです。

高頻度のツール

代表的な部分集合を、入力、返り値の形、必要な権限とともに示します。すべてのツールの完全な 仕様については、本ページ末尾の注記を参照してください。

chorus_checkin — 共通

各実行の最初に呼び出すことを推奨します。エージェントの識別情報と所有者、その有効権限セット、プロジェクト別に グループ化された着想トラッカー、そして通知の要約を返します。ideaTracker は最も新しく更新された十件の 着想を上限とし、すべてのプロジェクトにわたります。上記の範囲指定ヘッダーでは絞られません（範囲指定 され上限のないトラッカーには chorus_get_my_assignments を使ってください）。

入力：  （なし）
返り値：{ agent: { uuid, name, permissions, owner },
          ideaTracker: { <projectUuid>: { name, ideas[] } },
          notifications: { unread, recent[] } }

chorus_get_my_assignments — 共通

エージェントの完全な着想／課題トラッカーを、プロジェクト別にグループ化して返します。chorus_checkin の ideaTracker と同じ形ですが、最近の着想の件数上限はなく、加えて open の課題からなる taskTracker を持ちます。 範囲指定ヘッダーに従います。

入力：  （なし）
返り値：{ ideaTracker: { <projectUuid>: { name, ideas[] } },
          taskTracker: { <projectUuid>: { name, tasks[] } } }

chorus_claim_task — task:write

open の課題を担当し、assigned に移して呼び出し元を担当者に設定します。

入力：  { taskUuid }
返り値：更新された Task

chorus_submit_for_verify — task:write（担当者のみ）

課題を人間の検証へ提出し、in_progress → to_verify に移します。

入力：  { taskUuid, summary? }
返り値：更新された Task

chorus_pm_create_proposal — proposal:write

空の提案の入れ物を作り、そのあと chorus_pm_add_document_draft と chorus_pm_add_task_draft で 中身を満たします。inputType が idea のとき、入力の各着想は成果物でなければなりません。テーマ（まとめ役）の 着想は拒否されます。子の着想を派生させ、それに対して提案してください。

入力：  { projectUuid, title, description?, inputType: "idea" | "document",
          inputUuids[], references?[] }
返り値：作成された Proposal（status: draft）

chorus_pm_add_task_draft — proposal:write

下書きの提案に課題ドラフトを一つ追加します。受け入れ基準は必須です。空でない description を持つ項目が少なくとも 一つ必要で、なければ呼び出しは拒否されます。

入力：  { proposalUuid, title, description?, priority?, storyPoints?,
          acceptanceCriteriaItems: [{ description, required? }],  // 必須、空不可
          dependsOnDraftUuids?[] }
返り値：更新された Proposal

chorus_admin_verify_task — task:admin

提出された課題を検証し、to_verify → done に移します。課題が構造化された受け入れ基準を持つ場合、すべての 必須基準が（chorus_mark_acceptance_criteria を通じて）すでに passed とマークされていなければ、 検証はブロックされます。

入力：  { taskUuid }
返り値：更新された Task（受け入れ基準のゲートがブロックするときはエラー）

制限されるツール → 必要な権限のマトリクス

権限で制限されるすべてのツールと、その単一の必要なビットです。ツールが現れるには、プリセットまたは カスタム権限を通じてそのビットを持っている必要があります。ただし、ツールは実行時にさらに所有権、 担当者、状態を確認することがあります。

必要な権限	ツール
idea:write	chorus_claim_idea、chorus_release_idea、chorus_move_idea、chorus_pm_create_idea、chorus_edit_idea、chorus_pm_start_elaboration、chorus_pm_skip_elaboration
idea:admin	chorus_pm_validate_elaboration、chorus_admin_delete_idea
proposal:write	chorus_pm_create_proposal、chorus_pm_validate_proposal、chorus_pm_submit_proposal、chorus_pm_add_document_draft、chorus_pm_add_task_draft、chorus_pm_update_document_draft、chorus_pm_update_task_draft、chorus_pm_remove_document_draft、chorus_pm_remove_task_draft、chorus_pm_reject_proposal、chorus_pm_revoke_proposal、chorus_pm_assign_task
proposal:admin	chorus_admin_approve_proposal、chorus_admin_close_proposal
document:write	chorus_pm_create_document、chorus_pm_update_document、chorus_create_report、chorus_add_reference、chorus_update_reference、chorus_remove_reference
document:admin	chorus_admin_delete_document
task:write	chorus_claim_task、chorus_release_task、chorus_submit_for_verify、chorus_report_criteria_self_check、chorus_report_work
task:admin	chorus_admin_verify_task、chorus_admin_reopen_task、chorus_admin_close_task、chorus_mark_acceptance_criteria、chorus_admin_delete_task
project:write	chorus_admin_create_project、chorus_admin_create_project_group、chorus_admin_update_project_group、chorus_admin_delete_project_group、chorus_admin_move_project_to_group

ノート

権威ある完全なツール一覧は、動作中のサーバー自身の tools/list 応答、つまり各ツールのライブの自己 記述です。本ページはこのツール群のカテゴリー別ガイドであって、 各ツールを一バイト単位で転写したものではありません。ある自己記述と本ページが食い違うときは、サーバーの記述が正です。