MCP 권한 관리

MCP 권한 관리 (Permission Management)

LiteLLM에서 특정 키, 팀, 조직이 접근할 수 있는 MCP 서버와 도구를 제어해요. 클라이언트가 도구를 나열하거나 호출하려 하면 LiteLLM은 구성된 권한에 따라 접근 제어를 강제해요.

출처: 문서

본문

개요 (Overview)

LiteLLM은 MCP 서버에 대한 세밀한 권한 관리를 제공하며 다음을 할 수 있어요:

엔티티별 MCP 접근 제한: 특정 키, 팀, 또는 조직이 특정 MCP 서버에 접근할 수 있는지 제어
도구 레벨 필터링: 엔티티 권한에 따라 사용 가능한 도구를 자동 필터링
중앙 집중식 제어: LiteLLM 관리 UI나 API에서 모든 MCP 권한 관리
원클릭 공용 MCP: 키별 제한이 필요 없을 때 특정 서버를 모든 LiteLLM API 키에 사용 가능하게 표시

이를 통해 인증된 엔티티만 MCP 도구를 발견·사용할 수 있어 MCP 인프라에 추가 보안 레이어를 제공해요.

동작 방식 (How It Works)

LiteLLM은 키, 팀, 조직(엔티티)별로 MCP 서버 권한 관리를 지원해요. MCP 클라이언트가 도구를 나열하려 하면 LiteLLM은 엔티티가 접근할 권한이 있는 도구만 반환해요.

키, 팀, 조직을 생성할 때 엔티티가 접근할 수 있는 허용 MCP 서버를 선택할 수 있어요.

권한 계층 (Permission Hierarchy)

권한은 여섯 개의 구분된 레벨에서 설정할 수 있어요. 둘 이상의 레벨이 요청에 적용되면 LiteLLM은 목록을 교집합(가장 제한적 우선)하며, 조직 레벨은 천장(ceiling) 역할을 해요.

레벨	소스	합성 방식
키(Key)	가상 키의 `object_permission.mcp_servers` / `object_permission.mcp_access_groups`	키에 명시적 목록이 있으면 그것이 사용됨.
팀(Team)	팀의 같은 필드	키와 팀이 모두 목록이 있으면 결과는 교집합(둘 다에 있는 서버만). 팀만 목록이 있으면 키가 상속.
최종 사용자(End user)	`x-litellm-end-user-id`와 일치하는 `LiteLLM_EndUserTable` 행의 같은 필드	진행 중인 결과와 교집합. 요청에 end-user-id가 없으면 건너뜀.
에이전트(Agent)	`x-litellm-agent-id`로 식별된 에이전트 또는 키가 바인딩된 에이전트(`agent_id` 키 생성 시 설정)의 같은 필드	진행 중인 결과와 교집합. 적용되는 에이전트가 없으면 건너뜀.
내부 사용자(Internal user)	요청이 인증한 내부 사용자(사람)의 같은 필드	진행 중인 결과와 교집합이므로 좁힐 수만 있음. 그 사용자가 권한(entitlement)을 가지지 않으면 건너뜀.
조직(Organization)	키/팀을 소유한 org의 같은 필드	천장 역할; 최종 허용 서버 집합과 교집합. org에 목록이 없으면 추가 제한 없음.

어떤 레벨도 목록이 없으면 요청은 모든 MCP 서버에 접근 가능해요(기본적으로 열림).

에이전트에 바인딩된 키(agent_id를 /key/generate에 전달)는 x-litellm-agent-id를 담은 요청과 같은 취급을 받아요. 에이전트의 목록이 키가 만드는 모든 요청에서 키의 것과 교집합돼요. 서버를 키에만 부여하는 것은 부족하고, 에이전트도 부여를 보유해야 해요(관리 UI 에이전트 편집 폼 또는 PATCH /v1/agents/{agent_id}). 그렇지 않으면 그 서버로 범위가 정해진 요청이 에이전트를 이름 짓는 오류로 거부돼요.

같은 교집합 모델이 서버별 도구 레벨 dict mcp_tool_permissions에도 적용돼요(아래 Per-entity Tool-Level Permissions 참고).

키가 자체 MCP 접근을 정의하도록 요구 (Require keys to define their own MCP access)

기본적으로 빈 mcp_servers 목록 또는 없는 목록의 키는 팀의 목록을 상속하므로 팀이 모든 키가 폴백하는 실질적 기본값이 돼요. general_settings 아래에 require_key_mcp_access_defined: true를 설정해 그 관계를 뒤집어 주세요. 팀이 기본값이 아니라 천장이 되고, 빈 목록의 키는 명시적으로 부여하지 않으면(object_permission.mcp_servers에서 직접 또는 접근 그룹 통해) MCP 서버를 하나도 얻지 못해요.

config.yaml:

general_settings:
  require_key_mcp_access_defined: true

이걸 켜는 것이 권장되는 자세예요. 상속을 사용하면 팀 아래 발급된 모든 키가 그 팀이 도달할 수 있는 모든 MCP 서버에 조용히 도달하므로 접근이 암묵적으로 부여되고 팀 목록이 커질 때마다 넓어져요. 플래그를 켜면 키는 명시적으로 부여한 것에만 도달하고 팀 목록은 그 부여를 정의하지 않고 상한으로 작동해요. 우리는 이를 미래 릴리스의 기본 동작으로 만들고 있으며 deprecation 논의를 팔로우하고 의견을 내 주세요. 키가 자체 object_permission.mcp_servers(또는 접근 그룹)를 담게 된 후에 활성화하세요. 그 전에 켜면 상속에 의존하던 키의 MCP 접근이 떨어질 수 있으니까요.

빈 mcp_servers 목록의 팀은 플래그와 무관하게 여전히 "제한 없음"을 의미해요. 빈 팀 목록이 제한하지 않으니까요. 플래그가 바꾸는 것은 팀이 목록을 가질 때 빈 키 목록이 의미하는 것뿐이에요. 상속(기본) 대 아무것도 부여하지 않음(플래그 켬). 키의 접근 그룹 부여는 가산적이므로 플래그가 켜져 있어도 그룹을 붙이면 그 서버에 도달해요.

최종 사용자 레벨의 동등 제어는 require_end_user_mcp_access_defined를 참고하세요.

모든 MCP 서버에서 키를 옵트아웃(`no-mcp-servers`)

키의 모든 MCP 서버를 명시적으로 거부하려면 그 mcp_servers 목록에 센티널 no-mcp-servers를 넣으세요. 이는 모델 접근에 쓰는 no-default-models 센티널과 유사해요. 팀 서버를 상속하는 빈 목록과 달리 no-mcp-servers는 팀 상속과 가산적 접근 그룹 부여를 모두 재정의하므로, 팀이 무엇을 허용하든 키가 0개의 MCP 서버로 해석돼요.

MCP 접근 없는 키:

curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "object_permission": {
      "mcp_servers": ["no-mcp-servers"]
    }
  }'

MCP 도구 허용/비허용 (Allow/Disallow MCP Tools)

MCP 서버에서 사용 가능한 도구를 제어해요. 특정 도구만 허용하거나 위험한 도구를 차단할 수 있어요.

특정 도구만 허용:

allowed_tools로 사용자가 접근할 수 있는 도구를 정확히 지정하세요. 다른 모든 도구는 차단돼요.

config.yaml:

mcp_servers:
  github_mcp:
    url: "https://api.githubcopilot.com/mcp"
    auth_type: oauth2
    oauth2_flow: authorization_code
    authorization_url: https://github.com/login/oauth/authorize
    token_url: https://github.com/login/oauth/access_token
    client_id: os.environ/GITHUB_OAUTH_CLIENT_ID
    client_secret: os.environ/GITHUB_OAUTH_CLIENT_SECRET
    scopes: ["public_repo", "user:email"]
    allowed_tools: ["list_tools"]
    # only list_tools will be available

이것을 사용할 때:

사용 가능한 도구를 엄격히 제어하고 싶을 때
고보안 환경일 때
제한된 도구로 새 MCP 서버를 테스트할 때

특정 도구 차단:

disallowed_tools로 특정 도구를 차단하세요. 다른 모든 도구는 사용 가능해요.

config.yaml:

mcp_servers:
  github_mcp:
    url: "https://api.githubcopilot.com/mcp"
    auth_type: oauth2
    oauth2_flow: authorization_code
    authorization_url: https://github.com/login/oauth/authorize
    token_url: https://github.com/login/oauth/access_token
    client_id: os.environ/GITHUB_OAUTH_CLIENT_ID
    client_secret: os.environ/GITHUB_OAUTH_CLIENT_SECRET
    scopes: ["public_repo", "user:email"]
    disallowed_tools: ["repo_delete"]
    # only repo_delete will be blocked

이것을 사용할 때:

대부분 도구가 안전하지만 위험한 몇 개를 차단하고 싶을 때
비싼 API 호출을 막고 싶을 때
기존 서버에 점차 제한을 추가하고 있을 때

중요한 참고 (Important Notes)

allowed_tools와 disallowed_tools를 모두 지정하면 허용 목록이 우선
도구 이름은 대소문자 구분

공용 MCP 서버 (allow_all_keys) (Public MCP Servers)

일부 MCP 서버는 광범위하게 공유하도록 만들어졌어요. 내부 지식 기반, 캘린더 통합, 모든 팀이 접근 요청 없이 연결할 수 있는 다른 저위험 유틸리티. 그 서버를 모든 키·팀·조직에 추가하는 대신 새 allow_all_keys 토글을 활성화하세요.

UI:

관리 UI에서 MCP Servers → Add / Edit 열기.
Permission Management / Access Control 펼치기.
Allow All LiteLLM Keys 켜기.

토글은 기존 접근 그룹을 건드리지 않고 서버를 "공용"으로 만들어요.

config.yaml:

allow_all_keys: true로 서버를 공용으로 표시하세요:

mcp_servers:
  deepwiki:
    url: https://mcp.deepwiki.com/mcp
    allow_all_keys: true

사용 시점 (When to use it)

세밀한 ACL이 오히려 부가 작업만 늘리는 공유 MCP 유틸리티가 있을 때.
내부 사용자에게 "기본 활성화" 경험을 원하면서 여전히 도구 레벨 제한을 겹칠 수 있을 때.
새 팀을 온보딩하고 가장 안전한 MCP를 즉시 사용 가능하게 하고 싶을 때.

활성화되면 LiteLLM이 도구 디스커버리/호출 중에 가상 키·팀 구성 없이 자동으로 서버를 모든 키에 포함해요.

MCP 도구 파라미터 허용/비허용 (Allow/Disallow MCP Tool Parameters)

allowed_params 구성으로 특정 MCP 도구에 허용되는 파라미터를 제어해요. 각 도구에 전달할 수 있는 파라미터를 제한해 도구 사용에 대한 세밀한 제어를 제공해요.

구성 (Configuration)

allowed_params는 도구 이름을 허용 파라미터 이름 목록으로 매핑하는 딕셔너리예요. 구성되면 지정된 파라미터만 그 도구에 허용되고 다른 파라미터는 403 오류로 거부돼요.

allowed_params가 있는 config.yaml:

mcp_servers:
  deepwiki_mcp:
    url: https://mcp.deepwiki.com/mcp
    transport: "http"
    auth_type: "none"
    allowed_params:
      # Tool name: list of allowed parameters
      read_wiki_contents: ["status"]
  
  my_api_mcp:
    url: "https://my-api-server.com"
    auth_type: "api_key"
    auth_value: "my-key"
    allowed_params:
      # Using unprefixed tool name
      getpetbyid: ["status"]
      # Using prefixed tool name (both formats work)
      my_api_mcp-findpetsbystatus: ["status", "limit"]
      # Another tool with multiple allowed params
      create_issue: ["title", "body", "labels"]

동작 방식 (How It Works)

도구별 필터링: 각 도구는 자체 허용 파라미터 목록을 가질 수 있음
유연한 명명: 도구 이름은 서버 접두사 유무와 무관하게 지정할 수 있음(예: "getpetbyid"와 "my_api_mcp-getpetbyid" 모두 작동)
허용 목록 접근: 허용 목록의 파라미터만 허용
목록에 없는 도구: allowed_params가 설정되지 않으면 모든 파라미터 허용
오류 처리: 비허용 파라미터가 있는 요청은 허용되거나 어떤 파라미터가 허용되는지에 대한 세부 정보와 함께 403 오류 받음

예시 요청 동작 (Example Request Behavior)

위 구성으로 요청이 이렇게 처리돼요:

✅ 허용 요청:

{
  "tool": "read_wiki_contents",
  "arguments": {
    "status": "active"
  }
}

❌ 거부 요청:

{
  "tool": "read_wiki_contents",
  "arguments": {
    "status": "active",
    "limit": 10  // This parameter is not allowed
  }
}

오류 응답:

{
  "error": "Parameters ['limit'] are not allowed for tool read_wiki_contents. Allowed parameters: ['status']. Contact proxy admin to allow these parameters."
}

사용 사례 (Use Cases)

보안: 민감한 파라미터나 위험한 작업에 사용자 접근 방지
비용 제어: 비싼 파라미터 제한(예: 결과 수 제한)
컴플라이언스: 규제 요구사항에 파라미터 사용 정책 강제
단계적 롤아웃: 도구가 테스트됨에 따라 파라미터 점진 활성화
멀티테넌트 격리: 사용자 그룹마다 다른 파라미터 접근

도구 필터링과 결합 (Combining with Tool Filtering)

allowed_params는 allowed_tools·disallowed_tools와 함께 작동해 완전한 제어를 제공해요:

결합 필터링 예시:

mcp_servers:
  github_mcp:
    url: "https://api.githubcopilot.com/mcp"
    auth_type: oauth2
    oauth2_flow: authorization_code
    authorization_url: https://github.com/login/oauth/authorize
    token_url: https://github.com/login/oauth/access_token
    client_id: os.environ/GITHUB_OAUTH_CLIENT_ID
    client_secret: os.environ/GITHUB_OAUTH_CLIENT_SECRET
    scopes: ["public_repo", "user:email"]
    # Only allow specific tools
    allowed_tools: ["create_issue", "list_issues", "search_issues"]
    # Block dangerous operations
    disallowed_tools: ["delete_repo"]
    # Restrict parameters per tool
    allowed_params:
      create_issue: ["title", "body", "labels"]
      list_issues: ["state", "sort", "perPage"]
      search_issues: ["query", "sort", "order", "perPage"]

이 구성은 다음을 보장해요:

나열된 세 도구만 사용 가능
delete_repo 도구가 명시적으로 차단
각 도구가 지정된 파라미터만 사용 가능

MCP 서버 접근 제어 (MCP Server Access Control)

LiteLLM Proxy는 특정 MCP 서버에 대한 접근을 제어하는 두 가지 방법을 제공해요:

URL 기반 네임스페이싱: URL 경로로 특정 서버나 접근 그룹에 직접 접근
헤더 기반 네임스페이싱: x-mcp-servers 헤더로 접근할 서버 지정

방법 1: URL 기반 네임스페이싱 (URL-based Namespacing)

LiteLLM Proxy는 /<servers or access groups>/mcp 형식의 MCP 서버 URL 기반 네임스페이싱을 지원해요. 이를 통해:

직접 URL 접근: URL을 통해 MCP 클라이언트를 특정 서버·접근 그룹에 직접 지정
단순화된 구성: 서버 선택에 헤더 대신 URL 사용
접근 그룹 지원: 그룹 서버 접근에 URL에서 접근 그룹 이름 사용

URL 형식 (URL Format)

<your-litellm-proxy-base-url>/<server_alias_or_access_group>/mcp

예시:

/github_mcp/mcp — "github_mcp" MCP 서버의 도구 접근
/zapier/mcp — "zapier" MCP 서버의 도구 접근
/dev_group/mcp — "dev_group" 접근 그룹의 모든 서버 도구 접근
/github_mcp,zapier/mcp — 여러 특정 서버의 도구 접근

사용 예시 (Usage Examples)

OpenAI API — URL 네임스페이싱:

curl --location 'https://api.openai.com/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ***" \
--data '{
    "model": "gpt-5.6-terra",
    "tools": [
        {
            "type": "mcp",
            "server_label": "litellm",
            "server_url": "<your-litellm-proxy-base-url>/github_mcp/mcp",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

이 예시는 URL 네임스페이싱으로 "github" MCP 서버에만 접근해요.

LiteLLM Proxy — URL 네임스페이싱:

curl --location '<your-litellm-proxy-base-url>/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ***" \
--data '{
    "model": "gpt-5.6-terra",
    "tools": [
        {
            "type": "mcp",
            "server_label": "litellm",
            "server_url": "litellm_proxy",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

프록시의 /v1/responses 엔드포인트를 호출할 때는 server_url: "litellm_proxy"를 사용하세요. 전체 프록시 URL은 쓰지 마세요.

Cursor IDE — URL 네임스페이싱:

{
  "mcpServers": {
    "LiteLLM": {
      "url": "<your-litellm-proxy-base-url>/github_mcp,zapier/mcp",
      "headers": {
        "x-litellm-api-key": "Bearer sk-<your-litellm-api-key>"
      }
    }
  }
}

이 구성은 URL 네임스페이싱으로 "github"와 "zapier" MCP 서버 둘 다의 도구에 접근해요.

URL 네임스페이싱의 이점 (Benefits of URL Namespacing)

직접 접근: 서버 지정에 추가 헤더가 필요 없음
깨끗한 URL: 어떤 서버에 접근 가능한지 명확히 나타내는 자체 문서화 URL
접근 그룹 지원: 그룹 서버 접근에 접근 그룹 이름 사용
다중 서버: 쉼표 구분으로 단일 URL에 여러 서버 지정
단순화된 구성: URL 기반 구성을 선호하는 MCP 클라이언트에 쉬운 설정

방법 2: 헤더 기반 네임스페이싱 (Header-based Namespacing)

x-mcp-servers 헤더로 특정 MCP 서버에 접근하고 그 도구만 나열하도록 선택할 수 있어요. 이 헤더를 통해:

도구 접근을 하나 이상의 특정 MCP 서버로 제한
다른 환경이나 사용 사례에서 어떤 도구가 사용 가능한지 제어

헤더는 서버 별칭의 쉼표 구분 목록을 받아요: "alias_1,Server2,Server3"

참고:

헤더가 없으면 모든 사용 가능한 MCP 서버의 도구에 접근 가능
이 방법은 표준 LiteLLM MCP 엔드포인트와 함께 작동

OpenAI API — 헤더 네임스페이싱:

curl --location 'https://api.openai.com/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ***" \
--data '{
    "model": "gpt-5.6-terra",
    "tools": [
        {
            "type": "mcp",
            "server_label": "litellm",
            "server_url": "<your-litellm-proxy-base-url>/mcp/",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY",
                "x-mcp-servers": "alias_1"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

이 예시의 요청은 "alias_1" MCP 서버의 도구에만 접근할 수 있어요.

LiteLLM Proxy — 헤더 네임스페이싱:

curl --location '<your-litellm-proxy-base-url>/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ***" \
--data '{
    "model": "gpt-5.6-terra",
    "tools": [
        {
            "type": "mcp",
            "server_label": "litellm",
            "server_url": "litellm_proxy",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY",
                "x-mcp-servers": "alias_1,Server2"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

이 구성은 요청을 지정된 MCP 서버의 도구만 사용하도록 제한해요. 프록시의 /v1/responses 엔드포인트를 호출할 때는 server_url: "litellm_proxy"를 사용하세요.

Cursor IDE — 헤더 네임스페이싱:

{
  "mcpServers": {
    "LiteLLM": {
      "url": "<your-litellm-proxy-base-url>/mcp/",
      "headers": {
        "x-litellm-api-key": "Bearer sk-<your-litellm-api-key>",
        "x-mcp-servers": "alias_1,Server2"
      }
    }
  }
}

Cursor IDE 설정의 이 구성은 도구 접근을 지정된 MCP 서버로만 제한해요.

비교: 헤더 vs URL 네임스페이싱 (Comparison: Header vs URL Namespacing)

기능	헤더 네임스페이싱	URL 네임스페이싱
방법	`x-mcp-servers` 헤더 사용	URL 경로 `/<servers>/mcp` 사용
엔드포인트	표준 `litellm_proxy` 엔드포인트	사용자 지정 `/<servers>/mcp` 엔드포인트
구성	추가 헤더 필요	URL 자체에 포함
다중 서버	헤더에서 쉼표 구분	URL 경로에서 쉼표 구분
접근 그룹	헤더를 통해 지원	URL 경로 통해 지원
클라이언트 지원	모든 MCP 클라이언트에서 작동	URL 인식 MCP 클라이언트에서 작동
사용 사례	동적 서버 선택	고정 서버 구성

MCP 그룹화 (접근 그룹) (Grouping MCPs (Access Groups))

MCP 접근 그룹은 여러 MCP 서버를 함께 묶어 더 쉬운 관리를 가능하게 해요.

1. 접근 그룹 생성 (Create an Access Group)

A. Config로 접근 그룹 생성:

mcp_servers:
  "deepwiki_mcp":
    url: https://mcp.deepwiki.com/mcp
    transport: "http"
    auth_type: "none"
    access_groups: ["dev_group"]

config로 mcp_servers를 추가할 때:

access_groups 안에 문자열 목록 전달
이 그룹들은 키, 팀, MCP 클라이언트(헤더)로 접근 분리에 사용 가능

B. UI로 접근 그룹 생성:

LiteLLM UI에서 MCP Servers로 이동
"Add a New MCP Server" 클릭
"MCP Access Groups" 아래에서 타이핑해 새 그룹(예: "dev_group") 생성
서버를 함께 그룹화하려면 다른 서버에도 같은 그룹 이름 추가

2. Cursor에서 접근 그룹 사용 (Use Access Group in Cursor)

x-mcp-servers 헤더에 접근 그룹 이름 포함:

{
  "mcpServers": {
    "LiteLLM": {
      "url": "litellm_proxy",
      "headers": {
        "x-litellm-api-key": "Bearer sk-<your-litellm-api-key>",
        "x-mcp-servers": "dev_group"
      }
    }
  }
}

이것은 "dev_group" 접근 그룹의 모든 서버에 접근하게 해줘요.

즉, deepwiki 서버(그리고 dev_group 접근 그룹이 지정된 다른 서버)가 도구 호출에 사용 가능해져요.

고급: API 키에 접근 그룹 연결 (Connecting Access Groups to API Keys)

API 키 생성 시 권한 관리를 위해 키에 특정 접근 그룹을 지정할 수 있어요:

LiteLLM UI에서 "Keys"로 이동하고 "Create Key" 클릭
드롭다운에서 원하는 MCP 접근 그룹 선택
키가 그 그룹의 모든 MCP 서버에 접근 가능
이는 Test Key 페이지에 반영

엔티티별 도구 레벨 권한 (Per-entity Tool-Level Permissions)

같은 MCP 서버에서 다른 팀이 접근할 수 있는 도구를 제어해요. 예를 들어 Engineering 팀에 list_repositories, create_issue, search_code를 주고 Sales는 search_code와 close_issue만 주는 식이에요.

`mcp_tool_permissions` API

object_permission.mcp_tool_permissions는 키, 팀, 최종 사용자, 에이전트, 내부 사용자, 조직의 Dict[server_id, List[tool_name]]이에요. 서버 레벨 접근이 해석된 후에 평가되며(위 Permission Hierarchy 참고) 같은 여섯 레벨 교집합을 적용해요. 가장 제한적 우선, 조직은 천장 역할.

이것은 서버 등록 레벨 allowed_tools / disallowed_tools와 다릅니다(그것들은 서버의 모든 호출자에게 적용). mcp_tool_permissions는 서버 구성을 바꾸지 않고 팀별 하위 집합을 만들어 줘요.

Engineering 키 — 전체 GitHub 접근:

curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "object_permission": {
      "mcp_servers": ["github_mcp"],
      "mcp_tool_permissions": {
        "github_mcp": ["list_repositories", "create_issue", "search_code"]
      }
    }
  }'

Sales 키 — 같은 서버에서 읽기 전용:

curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "object_permission": {
      "mcp_servers": ["github_mcp"],
      "mcp_tool_permissions": {
        "github_mcp": ["search_code", "close_issue"]
      }
    }
  }'

팀 전체 도구 하위 집합(모든 키 상속):

curl -X POST "http://localhost:4000/team/new" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "team_alias": "engineering",
    "object_permission": {
      "mcp_servers": ["github_mcp", "deepwiki_mcp"],
      "mcp_tool_permissions": {
        "github_mcp": ["list_repositories", "create_issue", "search_code"]
      }
    }
  }'

키가 github_mcp에 대해 mcp_tool_permissions도 설정하면 결과 도구 목록은 둘의 교집합이에요.

에이전트(x-litellm-agent-id로 식별)가 MCP 도구를 호출할 때 에이전트 자신의 mcp_tool_permissions가 교집합에 참여해요. 자율 에이전트가 원래 어느 키가 호출했든 무엇을 할 수 있는지 상한을 두는 데 유용해요.

curl -X PATCH "http://localhost:4000/v1/agents/{agent_id}" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "object_permission": {
      "mcp_servers": ["github_mcp"],
      "mcp_tool_permissions": {
        "github_mcp": ["search_code"]
      }
    }
  }'

내부 사용자의 권한은 그 사람 이 어떤 키를 들고 있든 어떤 도구들을 실행할 수 있는지 말해줘요. 이것은 항상 좁히기만 해요. 서버에서 그들이 얻는 도구는 키, 팀, 에이전트, 조직이 이미 허용하는 것과 권한의 교집합이에요.

한 사람에게 한 서버의 한 도구 부여:

curl -X POST "http://localhost:4000/user/update" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "object_permission": {
      "mcp_servers": ["github_mcp"],
      "mcp_tool_permissions": {"github_mcp": ["list_issues"]}
    }
  }'

/user/new는 생성 시점에 같은 object_permission 블록을 받아요. read-back과 해석 세부 사항은 아래 Entitling a person rather than a credential 참고.

자격 증명이 아니라 사람 엔타이틀(Entitling a person rather than a credential)

다른 모든 레벨은 자격 증명이나 그룹을 설명해요. 키의 범위, 팀의 범위, 조직의 천장. 내부 사용자 레벨은 그 사람을 설명하므로 관리자가 사람들이 가진 모든 키를 쫓지 않고 어떤 사람이 어떤 MCP 도구 호출을 수행할 수 있는지 말할 수 있어요.

부여는 내부 사용자의 object_permission에 있으며 다른 곳과 같은 필드, mcp_servers, mcp_access_groups, mcp_tool_permissions을 사용해요. 두 축 모두에서 천장으로 해석돼요. 사람이 도달하는 서버는 키, 팀, 에이전트, 조직이 허용하는 것과 교집합되고, 그 각 서버에서 실행할 수 있는 도구도 마찬가지예요. 키가 부여하지 않는 서버에 엔타이틀된 사람도 여전히 도달할 수 없어요. 해석 순서에서 키와 팀이 먼저, 그다음 최종 사용자, 그다음 에이전트, 그다음 내부 사용자, 그다음 조직 천장.

권한이 없는 사용자는 천장을 두지 않으므로, 관리자가 누군가에게 부여하기 전까지는 기존 배포에 아무것도 바뀌지 않아요. mcp_tool_permissions의 키로만 이름이 지정된 서버는 엔타이틀된 것으로 간주되므로, 도구 하나를 부여해도 서버를 두 번 이름 지을 필요가 없어요.

GET /v2/user/info로 부여를 읽을 수 있으며, 이제 연결된 object_permission을 반환해요:

curl -X GET "http://localhost:4000/v2/user/info?user_id=alice" \
  -H "Authorization: Bearer ***" \
  | jq '.object_permission | {mcp_servers, mcp_tool_permissions}'

{
  "mcp_servers": ["github_mcp"],
  "mcp_tool_permissions": {"github_mcp": ["list_issues"]}
}

전체 블록에는 object_permission_id, mcp_access_groups와 나머지 object-permission 필드도 있어요.

권한은 tools/list 시점과 다시 tools/call 시점에 적용되므로, 그 밖의 도구는 절대 광고되지 않고 이름을 하드코딩하는 클라이언트도 여전히 거부돼요. 거부는 isError: true와 함께 MCP 결과 안에 도착해요:

Tool 'delete_repo' is not allowed for your key/team on server 'issue_tracker'. Contact proxy admin for access.

같은 부여는 관리 UI의 Internal Users 아래 내부 사용자 상세 페이지에서 편집할 수 있어요.

프록시 관리자만 설정 가능 — /user/new와 /user/update는 프록시 관리자에게서만 object_permission을 받아요. 관리자가 아닌 사람이 자기 레코드를 편집하는 것은 거부되는데, 빈 부여 목록이 "제한 없음"을 의미하고 자체 쓰기라면 관리자가 두 천장을 들어 올리게 되니까요.

관리자 역할도 면제가 아님 — 명시적 키 레벨 mcp_servers 목록이 없는 관리자 역할 호출자는 보통 전체 MCP 서버 레지스트리를 봅니다. 그 사람이 자체 권한을 가지면 그 지름길은 더 이상 적용되지 않고 권한이 그를 묶어요. 관리자 역할은 자격 증명이 도달하는 것을 넓히고, 사람에 붙은 범위는 그대로 둡니다.

MCP 서버별 속도 제한 (Rate Limiting per MCP Server)

mcp_rpm_limit으로 키나 팀이 특정 MCP 서버에 분당 만들 수 있는 도구 호출 수를 상한 해요. 이것은 MCP 서버 이름이 키인 Dict[str, int]이며, 이름은 별칭이 설정되면 별칭, 아니면 구성된 서버 이름이에요. 각 항목이 그 한 서버의 분당 요청 한도를 설정하므로 github의 한도는 slack 호출에 영향을 주지 않아요. 항목이 없는 서버는 무제한이에요.

창 내에서 한도를 초과하면 그 서버에 대한 추가 도구 호출은 창이 지나갈 때까지 429 Too Many Requests를 반환해요. 상한은 실제 MCP 도구 호출에만 적용되며 일반 LLM 요청에는 영향이 없어요.

키를 분당 github 100 + slack 200 호출로 상한:

curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_rpm_limit": {"github": 100, "slack": 200},
    "object_permission": {"mcp_servers": ["github", "slack"]}
  }'

팀을 분당 github 500 호출로 상한(모든 키가 카운터 공유):

curl -X POST "http://localhost:4000/team/new" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "team_alias": "engineering",
    "mcp_rpm_limit": {"github": 500},
    "object_permission": {"mcp_servers": ["github"]}
  }'

mcp_rpm_limit은 /key/update, /team/update, /user/new, /user/update에서도 받아들여져요. 같은 서버에 대해 키 레벨 한도가 팀 레벨 한도보다 우선하며, 그 외에는 팀 한도가 팀의 모든 키에 공유 카운터로 적용돼요.

대시보드 보기 모드 (Dashboard View Modes)

프록시 관리자는 general_settings.user_mcp_management_mode로 MCP 대시보드에서 비관리자가 보는 것을 제어할 수 있어요:

restricted (기본) – 사용자는 팀이 명시적으로 접근 권한이 있는 서버만 봄.
view_all – 모든 대시보드 사용자가 전체 MCP 서버 목록을 볼 수 있음.

Config 예시:

general_settings:
  user_mcp_management_mode: view_all

이것은 추가 실행 권한을 부여하지 않고 MCP 제공에 대한 발견 가능성(discoverability)을 원할 때 유용해요.

MCP 레지스트리 게시 (Publish MCP Registry)

다른 시스템(예: 네트워크 밖에서 실행되는 MCP 지원 IDE 같은 외부 에이전트 프레임워크)이 LiteLLM에 호스팅된 MCP 서버를 자동으로 발견하게 하려면 Model Context Protocol Registry 엔드포인트를 노출할 수 있어요. 이 레지스트리는 공식 MCP Registry 스펙을 사용해, 내장 LiteLLM MCP 서버와 구성한 모든 서버를 나열해요.

프록시 config(또는 DB 설정)의 general_settings 아래에 enable_mcp_registry: true를 설정하고 프록시를 다시 시작하세요.
LiteLLM이 레지스트리를 GET /v1/mcp/registry.json에 제공해요.
각 항목은 /mcp(내장 서버) 또는 사용자 지정 서버용 /{mcp_server_name}/mcp를 가리키므로 클라이언트가 광고된 Streamable HTTP URL로 직접 연결할 수 있어요.

권한은 여전히 적용됩니다 — 레지스트리는 서버 URL만 광고해요. 실제 접근 제어는 클라이언트가 /mcp나 /{server}/mcp에 연결할 때 LiteLLM이 여전히 강제하므로, 레지스트리 게시가 키별 권한을 우회하지 않아요.

더 알아보기 (Learn more)

MCP 개요 — LiteLLM의 MCP 알아보기
키·팀에 MCP 접근 부여 — 부여 절차
MCP Toolsets — 명명된 도구 컬렉션

MCP 권한 관리