MCP 서버 사용
이 가이드에서는 외부 MCP 클라이언트 — Claude Code, 편집기, MCP Inspector — 를 Control Center 자체의 도구 서버에 연결하는 방법을 설명합니다.
Control Center는 110개의 도구를 등록하고 프로토콜 버전 2024-11-05의 Model
Context Protocol을 통해 제공합니다. 예상할 법한 도구 계열이 통째로 빠져
있습니다. 회의나 캘린더 도구가 없고 프로젝트 도구도 없습니다.
엔드포인트 찾기
섹션 제목: “엔드포인트 찾기”MCP 표면은 기본 cc_server 리스너를 공유합니다. 별도의 MCP 포트는 없습니다.
| 엔드포인트 | 메서드 | 용도 |
|---|---|---|
/mcp |
POST |
Streamable HTTP 전송 — 클라이언트가 사용하는 방식입니다 |
/mcp |
DELETE |
세션 종료 |
/sse |
GET |
서버 전송 알림 스트림 |
따라서 기본 로컬 설치에서는 http://127.0.0.1:9030/mcp에 있습니다.
- 설정 → 서버 → MCP 서버로 이동합니다.
- MCP 서버 카드를 확인합니다 — 실행 중인지 중지됨인지와 수신 대기 중인 포트를 보여 줍니다.
이 표면은 새로 설치하면 기본적으로 켜져 있습니다. 카드의 토큰은 서버 소유자만 보며, 엔드포인트를 시작하거나 중지할 수 있는 사람도 서버 소유자뿐입니다. 앱 실행 시 시작은 재시작 후에 표면이 다시 켜질지를 제어하고, 시작 / 중지는 그 환경 설정을 바꾸지 않는 세션 제어입니다.
서버는 기본적으로 루프백에 바인딩하므로, --bind any로 시작하지 않았다면
엔드포인트는 cc_server가 실행되는 머신에서만 접근할 수 있습니다.
토큰 받기
섹션 제목: “토큰 받기”모든 요청에는 어느 머신에서 보내든, 루프백을 포함해 서버의 MCP 토큰이 필요합니다. 서버는 처음 시작할 때 토큰을 만듭니다. 끌 방법도, 지울 방법도 없습니다.
- 설정 → 서버 → MCP 서버에서 인증 토큰 행을 찾습니다.
- 토큰 표시를 누르고 복사합니다.
- 교체하려면 토큰 교체를 누릅니다. 서버는 즉시 새 토큰으로 전환하며, 이전 토큰을 계속 사용하는 모든 클라이언트는 새 토큰을 받을 때까지 거부됩니다.
클라이언트 연결
섹션 제목: “클라이언트 연결”클라이언트를 Streamable HTTP 엔드포인트로 지정하고, 모든 요청에 토큰을
Authorization: Bearer <token>으로 보냅니다. GET /sse도 포함됩니다. 다른 방법으로는
보낼 수 없으며, URL에 넣은 토큰은 받지 않습니다. 정확한 구성 형태는 클라이언트에 달려
있습니다.
{ "mcpServers": { "control-center": { "type": "http", "url": "http://127.0.0.1:9030/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Claude Code
섹션 제목: “Claude Code”Claude Code는 프로젝트 .mcp.json에서 이 설정을 가져오지 않습니다 — 프로젝트
범위 MCP 서버를 승인 프롬프트 뒤에 가두는데, 비대화형 claude -p는 이
프롬프트에 결코 응답하지 않습니다. 구성을 명시적으로 전달합니다.
claude --mcp-config /path/to/mcp.json --strict-mcp-config--strict-mcp-config는 Claude가 그 파일만 사용하도록 하므로, 같은 서버가
프로젝트에서도 발견되어 두 번 등록되는 일이 없습니다.
점검: 클라이언트에 도구 목록을 요청합니다. 티켓, 스페이스, 메모리, 코드
그래프, 리뷰를 아우르는 mcp__* 항목이 보여야 합니다.
엔드포인트가 거부하는 것
섹션 제목: “엔드포인트가 거부하는 것”토큰은 서버의 모든 도구를 열어 주므로, 엔드포인트는 토큰을 확인하기 전에 웹 페이지가 보냈을 수 있는 모든 것을 거부합니다.
| 요청 | 응답 |
|---|---|
이 머신의 페이지가 아닌 Origin 헤더(http://localhost, http://127.0.0.1 또는 http://[::1], 포트는 무관) |
403, “교차 출처 요청은 허용되지 않습니다” |
이 리스너의 루프백 주소와 포트도, 서버의 공개 호스트 이름도 아닌 Host 헤더 |
403, “알 수 없는 호스트” |
본문이 application/json이 아닌 POST |
415 |
| 토큰이 없거나 틀린 경우 | 401 |
호스트 외부로 MCP를 제공하려면 --bind any로 서버를 시작하고, 다른 머신에서 공개
호스트 이름으로 서버를 지정해 토큰을 보내십시오.
모든 호출을 워크스페이스로 한정하기
섹션 제목: “모든 호출을 워크스페이스로 한정하기”워크스페이스 범위 데이터를 다루는 모든 도구는 workspace_id를 요구하며,
이것이 없는 호출은 어떤 “현재” 워크스페이스로도 해석되지 않고 거부됩니다.
{ "workspace_id": "acme", "title": "Fix login bug", "priority": "high"}이 id는 브라우저나 앱 URL에 있는 값입니다: /workspaces/<workspace_id>/….
유일한 예외는 list_workspaces와 뉴스피드 도구처럼 실제로 워크스페이스를
가로지르는 도구입니다 — 뉴스피드는 사용자별 데이터이고 에이전트에는 자기
사용자가 없으므로, 그 도구들은 서버 소유자의 피드에서 작동합니다.
리포 범위 도구는 추가로 해당 리포가 그 워크스페이스에 연결되어 있는지 확인합니다.
표면이 무엇을 거부하는지 알아두기
섹션 제목: “표면이 무엇을 거부하는지 알아두기”- 모드 게이팅. 호출은 호출한 에이전트의 스페이스 모드에 따라 서버
측에서 판정됩니다. 읽기 전용 모드의 에이전트는
space_id를 생략한다고 해서 쓰기 도구에 도달할 수 없습니다 — 모드는 대신 활성 실행에서 조회됩니다. - 액션 가드레일. 변경 도구는 자신의 효과 클래스를 선언하고 제품의 나머지 부분이 사용하는 것과 동일한 정책을 거칩니다. 가드레일 구성을 참고하세요.
- 확인. 일부 파괴적 도구는 호출이 진행되기 전에 승인해야 하는 확인 페이로드를 구성합니다.
전체 카탈로그는 검색 게이팅 없이 tools/list에 게시됩니다 — 외부 MCP
클라이언트는 캐시된 목록에 없는 도구 호출을 거부하므로, 도구를 숨기면
정리되는 것이 아니라 망가집니다.
개인 MCP 서버는 소유자의 것으로 남습니다
섹션 제목: “개인 MCP 서버는 소유자의 것으로 남습니다”이 가이드는 Control Center 자체의 엔드포인트에 관한 것입니다. 반대 방향, 즉 Control
Center가 자신이 실행하는 에이전트에게 넘겨주는 MCP 서버는 설정 → 서버 → MCP 서버 →
외부 MCP 서버 아래에 나열됩니다. 서버의 머신에서 Claude, Codex, Cursor, Gemini, VS
Code, Windsurf, OpenCode용으로 구성되었거나 .mcp.json에 있는 서버는 자동으로 거기에서
찾습니다.
발견된 이 서버들은 서버 사용자 자신의 도구 구성에서 오며 그 사용자의 신원과 자격 증명으로 동작하므로 서버 소유자의 것입니다.
- 서버 소유자가 시작했거나 책임지는 내장 하네스 실행에서만 사용할 수 있습니다. 여기에는 소유자가 책임지는 워크스페이스의 자동화도 포함됩니다.
- 멤버의 실행, 멤버에게 묶인 자동화, 기록된 소유자가 없는 서버에서의 모든 실행은 이들을 받지 못합니다. 그곳에서는 도구가 나열되지 않고, 호출할 수 없으며, 도구 검색에도 나타나지 않습니다.
- 이 엔드포인트는 누구에게도, 소유자의 토큰을 포함해, 이들을 나열하거나 호출하거나 검색하지 않으며 이들의 리소스나 프롬프트를 전달하지도 않습니다. 따라서 MCP로 Control Center에 연결하는 에이전트 CLI(예: Claude Code)도 Control Center를 통해서는 이들을 얻지 못하며, 자체 구성을 사용합니다.
워크스페이스에 구성된 MCP 서버는 이 중 어떤 것의 영향도 받지 않습니다.
문제 해결
섹션 제목: “문제 해결”클라이언트에 도구가 보이지 않음
섹션 제목: “클라이언트에 도구가 보이지 않음”- MCP 서버 카드가 실행 중이라고 표시하는지 확인합니다
- 포트가
cc_server포트와 일치하는지 확인합니다 - Claude Code에서는
--mcp-config와--strict-mcp-config를 전달했는지 확인합니다
401 Unauthorized
섹션 제목: “401 Unauthorized”요청에 토큰이 없었거나 오래된 토큰이었습니다. 인증 토큰 행에서 현재 토큰을 복사해
Authorization: Bearer <token>으로 보내십시오. URL의 토큰은 무시됩니다.
이전에 작동하던 클라이언트의 403
섹션 제목: “이전에 작동하던 클라이언트의 403”요청에 웹 페이지에서 온 Origin이나 서버가 응답하지 않는 Host가 있었습니다. 브라우저
페이지가 아니라 클라이언트에서 루프백 주소나 서버의 공개 호스트 이름으로 엔드포인트를
호출하십시오.
415 Unsupported Media Type
섹션 제목: “415 Unsupported Media Type”POST /mcp 본문은 application/json으로 보내십시오.
도구 호출이 “Missing or invalid argument: workspace_id”로 실패함
섹션 제목: “도구 호출이 “Missing or invalid argument: workspace_id”로 실패함”workspace_id를 추가합니다. 암시적 워크스페이스는 없습니다.
도구 호출이 알 수 없는 도구로 거부됨
섹션 제목: “도구 호출이 알 수 없는 도구로 거부됨”MCP 도구에 카탈로그가 나열되어 있습니다. 거기에 나온 이름 그대로 호출합니다.