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가 실행되는 머신에서만 접근할 수 있습니다.

클라이언트 연결

클라이언트를 Streamable HTTP 엔드포인트로 지정합니다. 정확한 구성 형태는 클라이언트에 달려 있지만, URL은 어느 경우든 동일합니다.

{
  "mcpServers": {
    "control-center": {
      "type": "http",
      "url": "http://127.0.0.1:9030/mcp"
    }
  }
}

Claude Code

Claude Code는 프로젝트 .mcp.json에서 이 설정을 가져오지 않습니다 — 프로젝트 범위 MCP 서버를 승인 프롬프트 뒤에 가두는데, 비대화형 claude -p는 이 프롬프트에 결코 응답하지 않습니다. 구성을 명시적으로 전달합니다.

claude --mcp-config /path/to/mcp.json --strict-mcp-config

--strict-mcp-config는 Claude가 그 파일만 사용하도록 하므로, 같은 서버가 프로젝트에서도 발견되어 두 번 등록되는 일이 없습니다.

점검: 클라이언트에 도구 목록을 요청합니다. 티켓, 스페이스, 메모리, 코드 그래프, 리뷰를 아우르는 mcp__* 항목이 보여야 합니다.

호스트 외부로 MCP 제공하기

설정 → 서버 → MCP 서버에서 인증 토큰 행의 지정을 누르고 토큰을 붙여 넣습니다.
모든 POST /mcp 요청에 Authorization: Bearer <token>으로 보냅니다.

토큰이 없는 표면은 루프백이 아닌 모든 호출자를 403으로 거부합니다. 이는 의도적으로 실패 시 차단되도록 설계된 것입니다. 토큰이 있어야 호스트 외부 서비스가 아예 가능해집니다.

토큰 변경은 실행 중인 표면에 즉시 적용됩니다 — 재시작이 필요 없습니다.

모든 호출을 워크스페이스로 한정하기

워크스페이스 범위 데이터를 다루는 모든 도구는 workspace_id를 요구하며, 이것이 없는 호출은 어떤 “현재” 워크스페이스로도 해석되지 않고 거부됩니다.

{
  "workspace_id": "acme",
  "title": "Fix login bug",
  "priority": "high"
}

이 id는 브라우저나 앱 URL에 있는 값입니다: /workspaces/<workspace_id>/…. 유일한 예외는 list_workspaces와 뉴스피드 도구처럼 실제로 워크스페이스를 가로지르는 도구입니다 — 뉴스피드는 사용자별 데이터이고 에이전트에는 자기 사용자가 없으므로, 그 도구들은 서버 소유자의 피드에서 작동합니다.

리포 범위 도구는 추가로 해당 리포가 그 워크스페이스에 연결되어 있는지 확인합니다.

표면이 무엇을 거부하는지 알아두기

모드 게이팅. 호출은 호출한 에이전트의 스페이스 모드에 따라 서버 측에서 판정됩니다. 읽기 전용 모드의 에이전트는 space_id를 생략한다고 해서 쓰기 도구에 도달할 수 없습니다 — 모드는 대신 활성 실행에서 조회됩니다.
액션 가드레일. 변경 도구는 자신의 효과 클래스를 선언하고 제품의 나머지 부분이 사용하는 것과 동일한 정책을 거칩니다. 가드레일 구성을 참고하세요.
확인. 일부 파괴적 도구는 호출이 진행되기 전에 승인해야 하는 확인 페이로드를 구성합니다.

전체 카탈로그는 검색 게이팅 없이 tools/list에 게시됩니다 — 외부 MCP 클라이언트는 캐시된 목록에 없는 도구 호출을 거부하므로, 도구를 숨기면 정리되는 것이 아니라 망가집니다.

문제 해결

클라이언트에 도구가 보이지 않음

MCP 서버 카드가 실행 중이라고 표시하는지 확인합니다
포트가 cc_server 포트와 일치하는지 확인합니다
Claude Code에서는 --mcp-config와 --strict-mcp-config를 전달했는지 확인합니다

서버가 아닌 머신에서 발생하는 403

베어러 토큰이 구성되어 있지 않습니다. 토큰을 설정하고 함께 보냅니다.

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

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

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

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