MCP 클라이언트 애플리케이션 허용 목록

MCP 클라이언트 애플리케이션 허용 목록 (Allowlisting)

허용 목록(allowlist)을 사용해 MCP 게이트웨이 접근을 승인된 클라이언트 애플리케이션(예: Claude Code, Cursor, 내부 CLI)으로 제한할 수 있어요. LiteLLM은 인증 후 클라이언트 신원을 확인하고 허용되지 않으면 HTTP 403을 반환해요.

허용 목록은 게이트웨이 전체에 적용돼요. 기존 MCP 서버 권한은 허용된 클라이언트에도 계속 적용됩니다.

출처: 문서

본문

클라이언트 신원 구성 (Configure the client identity)

JWT 인증이 구성된 경우 mcp_client_id_jwt_field를 클라이언트 애플리케이션을 식별하는 액세스 토큰 클레임으로 설정해 주세요:

ID 공급자 또는 토큰 형식	클라이언트 ID 클레임
Okta	`cid`
Microsoft Entra ID, v2 토큰	`azp`
Microsoft Entra ID, v1 토큰	`appid`
RFC 9068 액세스 토큰	`client_id`

예를 들어 JWT 구성에 클레임 설정을 추가하고 프록시를 다시 시작해 주세요:

config.yaml:

general_settings:
  enable_jwt_auth: true
  litellm_jwtauth:
    mcp_client_id_jwt_field: azp

중첩 클레임은 점 표기법을 지원해요. 이 설정이 구성되면 JWT 호출자는 일치하는 클레임이 있어야 하고, 요청 헤더가 누락되었거나 목록에 없는 클레임을 재정의할 수 없어요.

허용 클라이언트 추가 (Add allowed clients)

각 항목에는 두 개의 필드가 있어요:

필드	용도
`alias`	관리 UI와 게이트웨이 로그의 표시 이름.
`value`	토큰의 클라이언트 ID. 매칭은 정확하고 대소문자를 구분해요.

아래 예시들은 antigravity-cli와 claude-code를 샘플 클라이언트 ID로 사용해요. ID 공급자가 발급한 값을 사용하세요.

관리 UI:

MCP Servers → Network Settings → Allowed Clients를 엽니다.

Add client 클릭, Alias와 Value 입력 후 Add 클릭. 승인된 각 애플리케이션에 대해 반복하고 Save 클릭. JWT 전용 접근이면 Client Identity Header는 비워 두세요.

클라이언트 편집 또는 제거: 클라이언트 카드를 클릭해 필드를 편집하고 Done, Save 클릭. 제거하려면 Remove client 선택 후 Save.

config.yaml:

general_settings 아래에 mcp_allowed_clients를 추가하고 프록시를 다시 시작해야 해요.

general_settings:
  mcp_allowed_clients:
    - alias: Antigravity CLI
      value: antigravity-cli
    - alias: Claude Code
      value: claude-code

API:

curl "$LITELLM_PROXY_URL/config/field/update" \
  -H "Authorization: Bearer $LITEL..._KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "field_name": "mcp_allowed_clients",
    "field_value": [
      {"alias": "Antigravity CLI", "value": "antigravity-cli"},
      {"alias": "Claude Code", "value": "claude-code"}
    ],
    "config_type": "general_settings"
  }'

config.yaml에 정의된 설정은 우선하며 관리 UI나 API로 변경할 수 없어요. UI·API 업데이트는 데이터베이스에 저장돼요. 관리 UI나 API를 사용할 때 store_model_in_db: true를 활성화해 모든 워커가 데이터베이스 설정을 로드·새로고침하도록 해 주세요.

접근 확인 (Verify access)

허용된 클라이언트의 유효한 액세스 토큰으로 MCP REST API를 호출해 주세요:

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  "$LITELLM_PROXY_URL/mcp-rest/tools/list" \
  -H "Authorization: Bearer ***"

목록에 없는 클라이언트와 구성된 클레임이 없는 토큰을 가진 클라이언트로도 반복해 보세요.

토큰	예상 결과
클라이언트 클레임이 허용 `value`와 일치	HTTP 200
클라이언트 클레임이 목록에 없거나 누락	HTTP 403

거부된 요청은 Rejected MCP request from a disallowed client application: ...로 로깅돼요. 클라이언트 확인을 통과해도 추가 MCP 서버나 도구에 대한 접근이 부여되는 것은 아니에요.

선택적 헤더 신원 (Optional header identity)

JWT 인증을 사용하지 않는 호출자를 위해 관리 UI에서 Client Identity Header를 설정하고 Save를 클릭하거나, 구성에 추가하고 프록시를 다시 시작해 주세요:

config.yaml:

general_settings:
  mcp_client_id_header: x-mcp-client

요청의 x-mcp-client 값은 허용된 클라이언트의 value와 일치해야 해요. mcp_client_id_jwt_field가 구성되지 않은 경우에도 헤더 신원이 사용돼요. JWT 설정이 구성되면 JWT 호출자는 헤더로 폴백할 수 없어요.

클라이언트 제공 신원 — 클라이언트는 헤더 값을 변경할 수 있어요. 신뢰할 수 있는 애플리케이션 신원에는 JWT 클라이언트 클레임을 사용하세요.

범위와 기본값 (Scope and defaults)

이 확인은 /mcp, /mcp/sse, /mcp-rest/tools/list, /mcp-rest/tools/call을 다뤄요.

`mcp_allowed_clients`	동작
미설정 또는 `null`	클라이언트 필터링 비활성화.
유효한 비어 있지 않은 목록	일치하는 클라이언트 신원만 통과.
`[]` 또는 잘못된 목록	허용 목록이 적용되는 요청은 거부. 항목에는 비어 있지 않은 `alias`와 `value` 문자열이 있어야 함.

대시보드 세션 토큰은 대시보드 외부에서 사용될 때를 포함해 면제돼요. 수명은 LITELLM_UI_SESSION_DURATION(기본 24시간)로 제어돼요. 관리 UI 연결 테스트 라우트도 면제돼요.

허용 목록 제거·복구 (Remove or repair the allowlist)

관리 UI에서 클라이언트 필터링을 비활성화하려면 모든 클라이언트 카드를 제거하고 Save를 클릭하세요. 그러면 설정이 삭제돼요. 대신 API나 구성을 통해 []를 저장하면 허용 목록이 적용되는 클라이언트를 거부해요.

API로 데이터베이스에 저장된 허용 목록을 제거하려면:

curl "$LITELLM_PROXY_URL/config/field/delete" \
  -H "Authorization: Bearer $LITEL..._KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "mcp_allowed_clients", "config_type": "general_settings"}'

빈 목록이나 잘못된 저장 목록은 경고를 표시해요. 제한된 접근을 복원하려면 유효한 클라이언트 항목을 추가하고 저장하거나, 필터링을 비활성화하려면 항목 없이 저장하세요.

더 알아보기 (Learn more)

MCP 개요 — LiteLLM의 MCP 알아보기
JWT 인증 — 토큰 인증 설정