조직의 MCP 서버 접근 제어

• 필요한 제어 수준에 맞는 패턴 선택
• managed-mcp.json으로 고정 서버 집합 배포 (MCP를 완전히 비활성화하는 방법 포함)
• 관리형 설정을 통해 서버 제공 (사용자가 자신의 서버 유지)
• 허용 목록 및 거부 목록으로 서버 제어
• 제한이 서버를 차단할 때 사용자에게 표시되는 내용
• 조직이 실제로 사용하는 서버 모니터링

​

패턴 선택

​

managed-mcp.json으로 독점 제어

• 파일에서 정의한 서버
• managedMcpServers를 통해 제공하는 서버
• 세션을 시작한 앱이 등록하는 인프로세스 서버(예: VS Code 확장 프로그램의 자체 서버 또는 데스크톱 앱이 제공하는 커넥터)
• Claude in Chrome 서버(내장), 관리되는 집합과 함께 허용하는 경우

​

managed-mcp.json 배포

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.example.com"
      }
    }
  }
}

​

사용자별 자격증명으로 인증

• ${VAR} 확장을 사용하여 각 사용자의 환경에서 비밀을 읽습니다.
• OAuth 또는 사용자별 헤더를 사용하여 각 사용자가 자신으로 인증합니다.
• headersHelper를 사용하여 연결 시간에 자격증명을 생성합니다.

​

--mcp-config 또는 --strict-mcp-config로 전달된 서버

• 워크스테이션에서 Claude Code는 You cannot dynamically configure MCP servers when an enterprise MCP config is present라는 메시지와 함께 시작 시 종료됩니다.
• 클라우드 세션에서 파일이 배포된 호스트(예: 자체 호스팅 러너)에서 Claude Code는 관리되는 서버만으로 시작하고 claude.ai 커넥터 및 클라우드 호스트가 --mcp-config를 통해 제공하는 다른 서버를 건너뜁니다. 세션의 어떤 것도 사용자에게 어떤 서버가 제외되었는지 알려주지 않습니다. Claude Code는 stderr의 경고에서 이름을 지정하며, 자체 호스팅 러너는 이를 debug 로그 수준에서 기록합니다.

​

허용 목록 및 거부 목록이 관리되는 집합에 적용되는 방식

• deniedMcpServers는 관리되는 서버에도 적용되므로 항목과 일치하는 관리되는 서버는 로드되지 않습니다.
• 사용자의 자체 deniedMcpServers는 설정에서 병합되므로 사용자는 자신을 위해 관리되는 서버를 차단할 수 있습니다.

​

구성 검증

1. claude mcp list는 managed-mcp.json의 서버와 managedMcpServers를 통해 제공하는 서버만 표시합니다. 다음 두 가지 다른 결과는 문제가 있음을 의미합니다:
   • 사용자의 자체 서버가 여전히 나타나면 Claude Code가 파일을 읽지 않는 것입니다. 경로와 상위 디렉터리의 권한을 확인하세요.
   • 파일의 서버가 나타나지 않고 MCP config diagnostics 섹션이 엔터프라이즈 구성을 파싱 실패로 표시하면 Claude Code가 파일을 읽거나 파싱할 수 없습니다. 해당 섹션에서 명명한 오류를 수정한 다음 사용자가 Claude Code를 다시 시작하도록 하세요.
2. claude mcp add --transport http test https://example.com/mcp는 Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers로 실패합니다. URL이 실제 서버일 필요는 없습니다. 정책 확인이 무엇이든 연락하기 전에 명령을 거부하기 때문입니다.

​

MCP 완전히 비활성화

{
  "mcpServers": {}
}

​

관리되는 집합과 함께 claude.ai 커넥터 허용

​

관리되는 집합과 함께 Claude in Chrome 허용

​

관리되는 설정을 통해 서버 제공

{
  "managedMcpServers": {
    "search": {
      "type": "http",
      "url": "https://search.example.com/mcp"
    },
    "records": {
      "type": "http",
      "url": "https://records.example.com/mcp",
      "headers": {
        "X-Records-Key": "key-issued-for-all-claude-code-users"
      }
    }
  }
}

​

항목에 포함될 수 있는 것

• type은 http 또는 sse입니다. .mcp.json에서와 같이 streamable-http는 http의 별칭으로 허용됩니다.
• url은 https:// URL입니다. Claude Code는 localhost를 가리키는 것을 포함하여 일반 http:// URL을 거부합니다.
• 항목에 command, args, env 또는 headersHelper 멤버가 없으므로, 관리되는 설정 문서는 사용자의 머신에서 실행할 프로그램을 절대 지정하지 않습니다.
• 어떤 값도 ${VAR} 참조를 포함하지 않습니다. Claude Code는 이러한 항목에서 환경 변수를 확장하지 않으므로 리터럴 값을 작성합니다.
• 서버 이름은 문자, 숫자, 하이픈 및 밑줄만 포함하고, 어떤 키나 값도 제어 또는 보이지 않는 서식 문자를 포함하지 않습니다.

​

제공된 서버가 로드되는 방식

• 제공된 서버는 로컬, 프로젝트 또는 사용자 범위의 동일한 이름의 서버보다 우선하며, 동일한 URL을 가리키는 플러그인 서버 또는 claude.ai 커넥터보다 우선합니다.
• managed-mcp.json도 배포하면, Claude Code는 해당 파일의 서버와 제공된 서버를 함께 로드하며, 둘 다 이름을 정의할 때 파일의 항목이 우선합니다.
• 제공된 서버는 strictPluginOnlyCustomization이 mcp 표면을 잠글 때 계속 로드됩니다.
• deniedMcpServers는 사용자 자신의 설정의 항목을 포함하여 제공된 서버에 적용되므로, 사용자는 자신을 위해 하나를 차단할 수 있습니다. 제공된 서버는 allowedMcpServers 항목이 필요하지 않습니다.

• 사용자가 동일한 이름으로 --mcp-config와 함께 전달하는 서버는 해당 실행에 대해 제공된 서버를 대체하며 allowedMcpServers에 대해 검사됩니다.
• --strict-mcp-config는 제공된 서버를 다른 모든 구성된 서버와 함께 제외합니다.

​

사용자가 보고 변경할 수 있는 것

• claude mcp remove는 서버가 조직에서 제공된다고 보고합니다.
• managed-mcp.json을 배포하지 않은 경우, 사용자가 동일한 이름으로 추가하는 항목은 저장되지만 귀사의 항목이 있는 동안에는 사용되지 않습니다.
• 사용자는 여전히 /mcp에서 제공된 서버를 자신을 위해 끌 수 있으며, 이는 Managed MCPs 아래에 제공된 서버를 나열합니다.

​

managedMcpServers가 적용되는 위치

​

제공된 서버가 연결되는 시기

• 캐시된 설정이 있는 머신에서, Claude Code는 서버가 세션에 대한 설정을 확인할 때까지 이 키의 캐시된 복사본을 보류하고, MCP 서버를 로드하기 전에 해당 확인을 기다립니다. 확인이 실패하면, 세션은 제공된 서버 없이 계속되며 /status는 이들이 보류되었다고 말합니다.
• 머신의 첫 번째 시작에서, 아직 캐시된 것이 없으면, 설정이 도착하기 전에 시작하는 대화형 세션은 제공된 서버를 도착하는 즉시 연결하고, 이미 시작한 claude -p 실행은 이들 없이 완료할 수 있습니다.

• 서버 추가: Claude Code는 업데이트된 설정이 도착할 때 이를 연결하며, 재시작이 필요하지 않습니다.
• 서버의 항목 변경: 해당 세션은 새 정의로 이를 다시 연결합니다.
• 서버 제거: 실행 중인 대화형 세션은 변경된 설정을 읽으면 이를 연결 해제합니다. 비대화형(-p) 실행은 종료될 때까지 이를 유지합니다.

​

허용 목록 및 거부 목록을 사용한 정책 기반 제어

​

URL, 명령 또는 이름으로 서버 일치

• deniedMcpServers에서 serverName은 선행 또는 후행 공백이 없는 비어 있지 않은 모든 문자열을 허용하므로 claude.ai 커넥터를 표시 이름으로 차단할 수 있습니다. 예를 들어 { "serverName": "claude.ai Slack" }은 Slack 커넥터를 차단합니다. 거부가 이름 변경에 강력해야 하거나 커넥터 이름이 충돌하여 (N) 접미사를 얻을 때는 serverUrl 항목을 선호합니다.
• allowedMcpServers에서 serverName은 문자, 숫자, 하이픈 및 밑줄로 제한됩니다. Claude Code가 자체적으로 가져오는 claude.ai 커넥터를 허용 목록에 추가하려면 serverUrl을 사용합니다. 클라우드 호스트가 자체 호스팅 세션에 제공하는 커넥터의 경우 대신 커넥터 트래픽이 네트워크를 떠남에 나열된 항목을 사용합니다.

​

서버 평가 방식

1. 목록 병합. 모든 설정 범위의 허용 목록 및 거부 목록 항목이 하나의 허용 목록과 하나의 거부 목록으로 결합됩니다. allowManagedMcpServersOnly가 true일 때 관리 허용 목록만 유지됩니다. 거부 목록은 항상 모든 범위에서 병합됩니다. 둘 이상의 관리 소스가 있을 때 모든 관리 소스에서 읽은 키에서 관리 범위의 목록을 제공하는 소스를 설명합니다.
2. 거부 목록 확인. URL, 명령 또는 이름으로 거부 목록 항목과 일치하는 서버는 차단됩니다. 거부 목록 일치를 무시하는 것은 없습니다.
3. 허용 목록 확인. allowedMcpServers가 어디에도 설정되지 않으면 거부 목록을 통과한 모든 서버가 로드됩니다. 설정되면 서버가 일치해야 하는 것은 아래 표에 표시된 유형에 따라 다릅니다. 세 그룹의 서버는 이 검사를 건너뜁니다.
   • 조직 자체의 서버: 모든 managedMcpServers 항목과 값에 ${VAR} 확장을 사용하지 않는 모든 managed-mcp.json 항목입니다.
   • 기본 제공 서버: Chrome의 Claude, Claude Code가 실행 중인 VS Code 또는 JetBrains IDE에 연결하는 ide 서버, CLI 자체가 구성하는 서버입니다.
   • Claude Tag 세션의 Slack 도구: 스레드를 읽고 회신을 게시하는 데 사용하는 서버는 허용 목록 항목 없이 로드됩니다.
   명령, 인수, env, URL 또는 헤더에서 ${VAR} 확장을 사용하는 managed-mcp.json 서버는 여전히 확인되며, 사용자, 플러그인, claude.ai가 추가하는 모든 서버와 사용자가 --mcp-config로 전달하는 모든 서버도 확인됩니다.

• 명령은 정확하게 일치합니다. 모든 인수, 순서대로. ["npx", "-y", "server"]는 ["npx", "server"] 또는 ["npx", "-y", "server", "--flag"]와 일치하지 않습니다.
• serverCommand 및 serverUrl 값은 일치 전에 확장됩니다. 정책 항목과 서버의 구성된 값 모두 ${VAR} 및 ${VAR:-default} 확장을 거치므로 ["${HOME}/bin/server"]로 작성된 항목은 동일한 참조 또는 확장된 경로를 사용하는 서버 구성과 일치합니다. Windows에서는 ${HOME} 대신 ${USERPROFILE}과 같이 설정된 환경 변수를 참조합니다. serverName 값은 문자 그대로 일치하며 절대 확장되지 않습니다. 두 쪽은 다른 환경을 읽습니다. 정책 항목 확장 방식에서 어느 것이고 허용 목록 및 거부 목록 항목이 어떻게 다른지 다룹니다.
• URL은 패턴의 어디든 * 와일드카드를 지원합니다. 스키마 포함. 호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하므로 https://Mcp.Example.com/*은 https://mcp.example.com/api와 일치합니다. 경로는 대소문자를 구분합니다.

​

정책 항목 확장 방식

​

예제 구성

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://mcp.sentry.dev/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] },
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}

• 3번 줄: 첫 번째 serverUrl 항목. 하나가 존재하면 모든 원격 서버는 URL 패턴과 일치해야 하므로 사용자는 허용된 이름을 제공하여 나열되지 않은 원격 서버를 얻을 수 없습니다.
• 5번 줄: 첫 번째 serverCommand 항목. stdio 서버에 대해 동일한 효과이므로 모든 로컬 서버는 나열된 명령과 정확하게 일치해야 합니다.
• 11번 줄: 거부 목록의 serverName 항목. 거부 목록 항목은 항상 적용되므로 dangerous-server라는 모든 서버는 URL 또는 명령에 관계없이 차단됩니다.

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

{
  "allowedMcpServers": [
    { "serverUrl": "https://*.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://staging.example.com/*" }
  ]
}

​

허용 목록을 관리 설정만으로 제한

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}

​

제한 사항이 사용자에게 표시되는 방식

​

MCP 사용 모니터링

​

구성 요약

​

관련 리소스

• 적용할 항목 결정: 권한 규칙, 샌드박싱 및 다른 관리 제어와 함께 MCP 제한
• MCP를 통해 Claude Code를 도구에 연결: 전송, 범위 및 인증을 포함한 전체 MCP 참조
• 설정: 설정 계층 구조 및 관리형 설정이 우선하는 방식
• 서버 관리 설정: Claude.ai 관리 콘솔에서 allowedMcpServers 및 deniedMcpServers 전달
• 보안: 이러한 제어가 방어하는 위협 모델
• Claude Enterprise Administrator Guide: SSO, SCIM, 시트 관리 및 롤아웃 플레이북