エージェントは Chorus の MCP（Model Context Protocol）ツールを通じて Chorus を操作します。本ページは、 このツール群のカテゴリー別ガイドです。クライアントがどう接続するか、プロジェクトの範囲指定がどう働くか、 各ツールがどう可視になるか、そして各段階でエージェントが使う高頻度のツールを扱います。エンティティが 経ていく状態と各段階の引き継ぎは[エンティティのライフサイクルリファレンス](/ja/reference/lifecycle/)を、コメント・メンション・ 通知は[コラボレーションリファレンス](/ja/reference/collaboration/)をご覧ください。 ## エンドポイントとトランスポート Chorus は **Streamable HTTP** で単一の MCP エンドポイントを公開します。 ```text POST https://chorus.example.com/api/mcp Authorization: Bearer cho_REDACTED ``` このエンドポイントは**ステートレス**です。各リクエストはエージェントの API キーで認証され、リクエストごとの 新しいサーバーインスタンスによって処理されます。サーバー側のセッションはなく、`initialize` → キープ アライブ → 期限切れの流れもなく、無操作タイムアウトもありません。クライアントは「session not found」 状態を回復する必要が一切なく、ただ毎回のリクエストでキーを送るだけです。ここから二つの帰結が生じます。 - **権限はリクエストごとに再計算される。** UI でエージェントの権限を変更すると、次の呼び出しから 即座に効き、再接続は不要です。 - **エージェントの API キーだけがツール一覧を決める。** `tools/list` が返すツールの集合は、そのキーのリクエスト ごとの有効権限から導かれます。 クライアントの MCP 設定では、これを `http` 型のサーバーとして設定します。最小の `.mcp.json` ブロック： ```json { "mcpServers": { "chorus": { "type": "http", "url": "https://chorus.example.com/api/mcp", "headers": { "Authorization": "Bearer cho_REDACTED" } } } } ``` シェルからは、`chorus mcp call ` で同じエージェント認証情報を使ってこれらのツールを呼び出せるため、 スクリプトや一度きりの呼び出しでもモデルのトークンを消費せずに済みます。 [chorus CLI](/ja/reference/cli/)を参照してください。 :::note 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` 引数を取り、ヘッダーの影響を受けません。 ```json { "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`） |
可視であることは、認可されていることと同じではありません。ツールは可視でも、実行時に操作を拒む ことがあります。たとえば課題の作業上の状態遷移（着手・提出など）は、誰がそのツールを見られるかにかかわらず、呼び出し元が その課題の担当者であることを要します。 ## プロジェクトのアクセス権 権限ビットは、エージェントがどのツールを持つかを決めます。**プロジェクトのアクセス権**は、それをどこで使えるかを 決めます。エージェントは各プロジェクトに対して、その所有者のアクセス権で行動します （[プロジェクトを閲覧できる人を管理する](/ja/guides/project-access/)を参照）。所有者のいないエージェントは公開 プロジェクトしか使えません。どちらの確認も、すべての呼び出しで適用されます。 - **非表示は「見つからない」と同じです。** 所有者がアクセスできない非公開プロジェクトと、その中のすべての 着想・提案・文書・課題・コメントは、一覧と検索から除かれ、存在しない 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`） | 提案の承認、課題の検証／再オープン／クローズ、受け入れ基準のマーク、エンティティの削除、プロジェクトとグループの管理。 |
:::caution `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` を使ってください）。 ```text 入力： （なし） 返り値：{ agent: { uuid, name, permissions, owner }, ideaTracker: { : { name, ideas[] } }, notifications: { unread, recent[] } } ``` ### chorus_get_my_assignments — 共通 エージェントの完全な着想／課題トラッカーを、プロジェクト別にグループ化して返します。`chorus_checkin` の `ideaTracker` と同じ形ですが、最近の着想の件数上限はなく、加えて open の課題からなる `taskTracker` を持ちます。 範囲指定ヘッダーに従います。 ```text 入力： （なし） 返り値：{ ideaTracker: { : { name, ideas[] } }, taskTracker: { : { name, tasks[] } } } ``` ### chorus_claim_task — `task:write` open の課題を担当し、`assigned` に移して呼び出し元を担当者に設定します。 ```text 入力： { taskUuid } 返り値：更新された Task ``` ### chorus_submit_for_verify — `task:write`（担当者のみ） 課題を人間の検証へ提出し、`in_progress → to_verify` に移します。 ```text 入力： { taskUuid, summary? } 返り値：更新された Task ``` ### chorus_pm_create_proposal — `proposal:write` **空の**提案の入れ物を作り、そのあと `chorus_pm_add_document_draft` と `chorus_pm_add_task_draft` で 中身を満たします。`inputType` が `idea` のとき、入力の各着想は成果物でなければなりません。テーマ（まとめ役）の 着想は拒否されます。子の着想を派生させ、それに対して提案してください。 ```text 入力： { projectUuid, title, description?, inputType: "idea" | "document", inputUuids[], references?[] } 返り値：作成された Proposal（status: draft） ``` ### chorus_pm_add_task_draft — `proposal:write` 下書きの提案に課題ドラフトを一つ追加します。受け入れ基準は必須です。空でない description を持つ項目が少なくとも 一つ必要で、なければ呼び出しは拒否されます。 ```text 入力： { proposalUuid, title, description?, priority?, storyPoints?, acceptanceCriteriaItems: [{ description, required? }], // 必須、空不可 dependsOnDraftUuids?[] } 返り値：更新された Proposal ``` ### chorus_admin_verify_task — `task:admin` 提出された課題を検証し、`to_verify → done` に移します。課題が構造化された受け入れ基準を持つ場合、すべての **必須**基準が（`chorus_mark_acceptance_criteria` を通じて）すでに `passed` とマークされていなければ、 検証はブロックされます。 ```text 入力： { 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` |
:::note **権威ある完全な**ツール一覧は、動作中のサーバー自身の `tools/list` 応答、つまり各ツールのライブの自己 記述です。本ページはこのツール群のカテゴリー別ガイドであって、 各ツールを一バイト単位で転写したものではありません。ある自己記述と本ページが食い違うときは、サーバーの記述が正です。 :::