조직의 MCP 서버 접근 제어하기

조직의 MCP 서버 접근 제어하기

Claude Code 엔터프라이즈·팀 관리자를 위해 조직 차원에서 MCP(모델 컨텍스트 프로토콜) 서버 접근을 관리하는 가이드예요. 원격 저장소·마켓플레이스처럼 조직이 승인한 채널로만 사용자가 MCP 서버를 설치하고 연결할 수 있게 허용 목록과 차단 목록을 구성해요. 관리 설정 파일의 mcpServers 필드로 원격 관리형 MCP 서버를 선언하고, 사용자가 무시할 수 없도록 잠그는 방식이에요.

출처: 공식문서

본문

요구 사항

  • Claude Code 관리자 설정 접근 권한(엔터프라이즈·팀 관리자에게만 제공).
  • 관리 설정에서 관리형 MCP가 활성화되어 있어야 해요(mcpServers, managedMCPServers 관련 설정 존재).

관리형 MCP 서버

관리자는 관리 설정 파일의 mcpServers 필드에 관리형(managed) MCP 서버를 정의할 수 있어요. 관리형 서버는 사용자가 자신의 claude mcp 구성에서 수정하거나 제거할 수 없는 서버예요 — 조직 정책으로 잠겨 있어요. 사용자 입장에서는 claude mcp list에서 다른 개인·로컬 서버와 함께 표시되지만, 관리 설정 값은 사용자 파일의 값으로 재정의되거나 제거되지 않아요.

관리형 서버 정의 예시 (관리 설정 파일):

{
  "mcpServers": {
    "company-gateway": {
      "type": "http",
      "url": "https://gateway.internal.corp/mcp",
      "headers": { "Authorization": "Bearer <org-token>" }
    }
  }
}

관리형 서버의 세부 규칙:

  • transport: type과 url(HTTP/SSE) 또는 command/args(stdio)를 사용해요.
  • 보안 자격증명: 공유 조직 자격증명은 서버 정의의 고정 헤더로 넣으면 파일에 평문으로 노출되므로, 시크릿은 환경 변수 참조나 관리 도구 전달 방식을 우선하는 게 좋아요.
  • 오버라이드 금지: 사용자 ~/.claude/settings.json이나 프로젝트 .mcp.json에 같은 서버 이름을 다시 정의해도 관리형 값이 우선하며, 경고 없이 병합될 뿐 사용자 값으로 바뀌지 않아요.
  • 서버 이름 충돌: 사용자 설정의 서버 이름이 관리형과 겹치면 관리형 정의가 사용자 정의보다 우선해요.

허용 목록과 차단 목록

관리자는 원격·로컬 서버 유형별로 MCP 접근을 제어하는 정책을 설정할 수 있어요. Canada·서버 유형에 따라 승인된 원본만 사용자가 추가할 수 있게 제한하거나, 명시적으로 차단된 원본을 걸러내요. 일반적인 규칙:

  • 기본: 별도 설정이 없으면 사용자는 개인 로컬 서버, 원격 URL 서버를 자유롭게 추가할 수 있어요(관리 차단 목록 미적용).
  • 골목 검증(origin allowlist): 조직이 승인한 원격 서버 URL·저장소만 허용하려면 정책 파일에 허용 목록을 정의해요. 목록에 없는 원본으로의 연결은 거부돼요.
  • 차단 목록(denylist): 특정 원격 서버나 도메인을 명시적으로 금지해요. 차단된 원본은 사용자가 추가할 수 없어요.

관리형 MCP 정책이 적용되면, 사용자 세션에서 claude mcp list가 반환하는 서버 목록이 정책 결과를 반영해요. 목록에 없는 원격 서버를 claude mcp add로 추가하려 하면 조직 정책에 따라 거부될 수 있어요.

문제 해결

  • 서버가 목록에 안 보여요: 관리 설정에서 관리형 MCP가 활성화됐는지, mcpServers 정의가 올바른 JSON인지 확인.
  • 연결 실패: HTTP 서버면 URL에 /mcp 엔드포인트가 정확한지, 인증 헤더가 유효한지. stdio 서버면 command가 PATH에 있고 args가 올바른지.
  • 사용자 재정의가 안 먹어요: 관리형 서버는 의도적으로 잠겨 있어요. 서버를 바꾸려면 관리 설정에서 값을 수정해야 해요.
  • 시크릿 노출: 고정 헤더에 토큰을 넣으면 로그·설정 파일에 보일 수 있어요. 환경 변수 참조나 시크릿 전달을 쓰세요.

더 알아보기