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	結果をそのグループ内のすべてのプロジェクトに限定する。

範囲指定ヘッダーに従うのは chorus_get_my_assignments だけです。未指定ならアクセス可能なプロジェクト全体を対象とし、両方あれば X-Chorus-Project-Group が優先します。chorus_checkin は絞り込まれない activeProjects の分布を返し、最近の着想一覧ではありません。他のツールはそれぞれの明示的な範囲引数を使います。これらのヘッダーは一般的なアクセスフィルターではありません。

{
  "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 — 共通

概要には最大 10 プロジェクトが含まれ、各プロジェクトで最後に更新された進行中の着想の順に並びます。掲載された各プロジェクトの着想数は切り詰められません。完全なトラッカーには chorus_get_my_assignments を使います。

識別情報、所有者、有効権限、ペルソナと activeProjects を返します。プロジェクト UUID ごとに名前と activeIdeaCount があり、進行中の着想総数は切り詰められません。個別の着想や課題は含みません。最近の未読通知を最大五件返し、自動で既読にします。notifications.unread は既読化後の残りの未読数です。範囲指定ヘッダーでは絞られません。

{ checkinTime, agent: { uuid, name, permissions, persona, systemPrompt, owner },
  activeProjects: { <projectUuid>: { name, activeIdeaCount } },
  notifications: { unread, recent[] } }

chorus_get_my_assignments — 共通

進行中の着想／課題の完全なトラッカーをプロジェクト別に返し、範囲指定ヘッダーに従います。ideaTracker は個別の着想の派生ステータスと提案／課題数を、taskTracker は終端状態でない課題と受け入れ基準の進捗を含みます。完全な一覧には activeProjects ではなくこちらを使います。

{ 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? }
返り値： { uuid, status: "to_verify" }

status なしの chorus_report_work で完了を報告し、chorus_report_criteria_self_check を記録し、chorus_get_task で in_progress を確認してから明示的に提出します。先に status: "to_verify" を報告すると提出は失敗します。誤操作を in_progress に戻すと開発側と管理側の判定と根拠が消えるため、自己チェックをやり直します。正しく提出された課題は再開しないでください。課題を実行するを参照してください。

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?, kind?,
          acceptanceCriteriaItems: [{ description, required? }],  // 必須、空不可
          dependsOnDraftUuids?[] }
返り値：更新された Proposal

提案検証とドラフトの種類

chorus_pm_add_task_draft と chorus_pm_update_task_draft は任意の kind として implementation、verification、docs、other を受け取ります。編集後に chorus_pm_validate_proposal を呼び、その後 chorus_pm_submit_proposal で提出します。提出時もサーバーで検証します。結果は { valid, issues[] } で、レベルは error、warning、info です。エラーがある場合のみ valid が false になります。

• E-DEP-UNKNOWN：依存先が同じ提案の課題ドラフトではありません。
• E-DEP-SELF：自己依存です。
• E-DEP-CYCLE：依存関係の循環です。
• I-KIND：種類が未指定で実装の網羅性を確認できません。
• W-IMPL：種類の指定はありますが implementation がありません。助言のみです。既存実装や文書のみの範囲を説明し、架空の作業を作らないでください。依存がない警告（W4）も助言です。

任意の Pi ゲートはローカルの読み直し／検証順序を追跡するもので、サーバーの認可ではありません。提案をレビューするを参照してください。

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 応答、つまり各ツールのライブの自己 記述です。本ページはこのツール群のカテゴリー別ガイドであって、 各ツールを一バイト単位で転写したものではありません。ある自己記述と本ページが食い違うときは、サーバーの記述が正です。