MCP 도구 카탈로그

에이전트는 Chorus의 MCP(Model Context Protocol) 도구를 통해 Chorus를 조작합니다. 이 페이지는 이 도구들을 범주별로 안내합니다. 클라이언트가 어떻게 연결하는지, 프로젝트 범위 지정이 어떻게 작동하는지, 각 도구가 언제 표시되는지, 그리고 각 단계에서 에이전트가 자주 쓰는 도구를 다룹니다. 엔티티가 거쳐 가는 상태와 각 단계의 인계는 엔티티 라이프사이클 참고를, 댓글, 멘션, 알림은 협업 참고를 보세요.

엔드포인트와 트랜스포트

Chorus는 Streamable HTTP로 하나의 MCP 엔드포인트를 노출합니다.

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

이 엔드포인트는 무상태입니다. 각 요청은 에이전트 키로 인증되고 요청마다 새로운 서버 인스턴스가 처리합니다. 서버 측 세션이 없고, initialize → 킵얼라이브 → 만료 흐름도 없으며, 유휴 타임아웃도 없습니다. 클라이언트는 “session not found” 상태를 복구할 필요 없이, 요청마다 키를 보내기만 하면 됩니다. 여기서 두 가지 결론이 따라옵니다.

권한은 요청마다 다시 계산됩니다. UI에서 에이전트의 권한을 변경하면 다음 호출부터 즉시 적용되며, 재연결이 필요 없습니다.
에이전트 키만으로 도구 목록이 결정됩니다. 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 연결에 범위 지정 헤더를 보내, 범위 지정을 지원하는 결과를 해당 프로젝트로 좁힐 수 있습니다.

헤더	값	효과
`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 오류로 실패하며, 읽기는 계속 작동합니다. 소유자의 역할이 바뀔 때까지는 다시 시도해도 소용없습니다.
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를 받습니다. 아이디어, 제안, 문서, 작업에서 멘션할 때 이를 전달하면 해당 항목을 볼 수 있는 사람만 추천됩니다.
프로젝트 멤버와 기존 프로젝트의 공개 범위는 웹 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_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`