콘텐츠로 이동

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에 있습니다.

  1. 설정 → 서버 → MCP 서버로 이동합니다.
  2. MCP 서버 카드를 확인합니다 — 실행 중인지 중지됨인지와 수신 대기 중인 포트를 보여 줍니다.

이 표면은 새로 설치하면 기본적으로 켜져 있습니다. 카드의 토큰은 서버 소유자만 보며, 엔드포인트를 시작하거나 중지할 수 있는 사람도 서버 소유자뿐입니다. 앱 실행 시 시작은 재시작 후에 표면이 다시 켜질지를 제어하고, 시작 / 중지는 그 환경 설정을 바꾸지 않는 세션 제어입니다.

서버는 기본적으로 루프백에 바인딩하므로, --bind any로 시작하지 않았다면 엔드포인트는 cc_server가 실행되는 머신에서만 접근할 수 있습니다.

모든 요청에는 어느 머신에서 보내든, 루프백을 포함해 서버의 MCP 토큰이 필요합니다. 서버는 처음 시작할 때 토큰을 만듭니다. 끌 방법도, 지울 방법도 없습니다.

  1. 설정 → 서버 → MCP 서버에서 인증 토큰 행을 찾습니다.
  2. 토큰 표시를 누르고 복사합니다.
  3. 교체하려면 토큰 교체를 누릅니다. 서버는 즉시 새 토큰으로 전환하며, 이전 토큰을 계속 사용하는 모든 클라이언트는 새 토큰을 받을 때까지 거부됩니다.

클라이언트를 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는 프로젝트 .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를 전달했는지 확인합니다

요청에 토큰이 없었거나 오래된 토큰이었습니다. 인증 토큰 행에서 현재 토큰을 복사해 Authorization: Bearer <token>으로 보내십시오. URL의 토큰은 무시됩니다.

이전에 작동하던 클라이언트의 403

섹션 제목: “이전에 작동하던 클라이언트의 403”

요청에 웹 페이지에서 온 Origin이나 서버가 응답하지 않는 Host가 있었습니다. 브라우저 페이지가 아니라 클라이언트에서 루프백 주소나 서버의 공개 호스트 이름으로 엔드포인트를 호출하십시오.

POST /mcp 본문은 application/json으로 보내십시오.

도구 호출이 “Missing or invalid argument: workspace_id”로 실패함

섹션 제목: “도구 호출이 “Missing or invalid argument: workspace_id”로 실패함”

workspace_id를 추가합니다. 암시적 워크스페이스는 없습니다.

도구 호출이 알 수 없는 도구로 거부됨

섹션 제목: “도구 호출이 알 수 없는 도구로 거부됨”

MCP 도구에 카탈로그가 나열되어 있습니다. 거기에 나온 이름 그대로 호출합니다.