MCP 工具目录

智能体通过 Chorus 的 MCP（Model Context Protocol）工具对 Chorus 进行操作。本页是这套工具 的分类指南：客户端如何连接、项目范围过滤如何工作、每个工具如何变为可见，以及智能体在各 阶段使用的高频工具。关于实体经历的各个状态以及各阶段如何交接，参阅 生命周期参考；关于评论、@提及与通知，参阅 协作参考。

端点与传输

Chorus 通过 Streamable HTTP 暴露单一的 MCP 端点：

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

该端点是无状态的。每个请求都用智能体密钥进行鉴权，并由一个全新的、每请求独立的服务器 实例处理，不存在服务器端会话，没有 initialize → 保活 → 过期的流程，也没有闲置超时。客户端 无需恢复任何“会话未找到”的状态；它只需在每个请求上带上密钥即可。由此有两个结论：

• 权限按请求重新计算。 在 UI 中修改某个智能体的权限，会在下一次调用时立即生效，无需重新 连接。
• 仅凭智能体密钥即决定工具列表。 tools/list 返回的工具集，是根据该密钥在本次请求时的有效权限 得出的。

在客户端的 MCP 配置中，将其配置为一个 http 类型的服务器。一个最小的 .mcp.json 配置块：

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

在 shell 中，chorus mcp call <tool> 命令可用同一份智能体凭据调用上述任意工具，适合脚本与一次性调用，且无需消耗模型 token。参见 chorus 命令行工具。

注意

MCP 传输会话与 Chorus 的智能体会话无关。智能体会话用于追踪蜂群模式下的子智能体，让你能看到它们的工作， 通过下文的会话工具创建与管理。

按项目过滤范围

跨多个项目工作的智能体，可以在 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 时完全相同。
• 角色过低即禁止。当所有者的角色过低时（例如查看者执行写操作，或编辑者在私有项目中执行仅限管理员的操作）， 调用会以禁止访问错误失败；读操作仍然可用。在所有者的角色改变之前，重试也无济于事。
• 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 界面中管理；没有对应的 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 相同，但 没有近期想法的数量上限，并额外带有一个关于未完成任务的 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。若任务带有结构化验收标准，则所有必需 标准必须已被标记为 passed（通过 chorus_mark_acceptance_criteria），否则验证被阻止。

输入：{ 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 响应（每个工具的实时自描述）。 本页是对这套工具的分类指南，而非对每个工具逐字节的转录。当某个自描述与本页不一致时，以服务器为准。