에이전트는 Chorus의 MCP(Model Context Protocol) 도구를 통해 Chorus를 조작합니다. 이 페이지는 이 도구들을 범주별로 안내합니다. 클라이언트가 어떻게 연결하는지, 프로젝트 범위 지정이 어떻게 작동하는지, 각 도구가 언제 표시되는지, 그리고 각 단계에서 에이전트가 자주 쓰는 도구를 다룹니다. 엔티티가 거쳐 가는 상태와 각 단계의 인계는 [엔티티 라이프사이클 참고](/ko/reference/lifecycle/)를, 댓글, 멘션, 알림은 [협업 참고](/ko/reference/collaboration/)를 보세요. ## 엔드포인트와 트랜스포트 Chorus는 **Streamable HTTP**로 하나의 MCP 엔드포인트를 노출합니다. ```text POST https://chorus.example.com/api/mcp Authorization: Bearer cho_REDACTED ``` 이 엔드포인트는 **무상태**입니다. 각 요청은 에이전트 키로 인증되고 요청마다 새로운 서버 인스턴스가 처리합니다. 서버 측 세션이 없고, `initialize` → 킵얼라이브 → 만료 흐름도 없으며, 유휴 타임아웃도 없습니다. 클라이언트는 "session not found" 상태를 복구할 필요 없이, 요청마다 키를 보내기만 하면 됩니다. 여기서 두 가지 결론이 따라옵니다. - **권한은 요청마다 다시 계산됩니다.** UI에서 에이전트의 권한을 변경하면 다음 호출부터 즉시 적용되며, 재연결이 필요 없습니다. - **에이전트 키만으로 도구 목록이 결정됩니다.** `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](/ko/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`) |
보이는 것과 인가된 것은 같지 않습니다. 도구가 보이더라도 서버가 특정 호출을 거부할 수 있습니다. 예를 들어 작업의 상태 전이는, 누가 그 도구를 볼 수 있는지와 무관하게 호출자가 그 작업의 담당자일 것을 요구합니다. ## 프로젝트 액세스 권한 비트는 에이전트가 어떤 도구를 가지는지를 정합니다. **프로젝트 액세스**는 그 도구를 어디서 쓸 수 있는지를 정합니다. 에이전트는 각 프로젝트에 대해 소유자의 액세스로 행동하며([프로젝트를 볼 수 있는 사람 관리](/ko/guides/project-access/) 참조), 소유자가 없는 에이전트는 공개 프로젝트만 사용할 수 있습니다. 두 검사는 모든 호출에 적용됩니다. - **숨겨진 것은 찾을 수 없는 것입니다.** 소유자가 액세스할 수 없는 비공개 프로젝트와 그 안의 모든 아이디어, 제안, 문서, 작업, 댓글은 목록과 검색에서 제외되며, 존재하지 않는 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`) | 제안 승인, 작업 검증/다시 열기/닫기, 수락 기준 표시, 엔티티 삭제, 프로젝트와 그룹 관리. |
:::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` 응답, 즉 각 도구가 제공하는 최신 설명입니다. 이 페이지는 도구를 범주별로 안내할 뿐, 각 도구를 바이트 단위로 옮겨 적은 것이 아닙니다. 도구의 설명과 이 페이지가 어긋나면 서버가 옳습니다. :::