키·팀에 MCP 서버 접근 부여

키·팀에 MCP 서버 접근 부여 (Grant MCP Server Access to Keys and Teams)

이 가이드는 MCP 서버를 가상 키와 팀에 부여하는 절차를 관리 UI와 관리 API를 통해 안내하고, 키와 팀이 모두 부여를 가질 때 결과 접근이 어떻게 해석되는지 보여줘요. 규칙 자체(6단계 교집합, no-mcp-servers, require_key_mcp_access_defined, 접근 그룹, 엔티티별 도구 권한)는 MCP Permission Management에 있고, 이 페이지는 그들을 적용하는 절차예요.

출처: 문서

본문

시작하기 전에 (Before you start)

먼저 MCP 서버를 config.yaml의 mcp_servers 아래에 등록하거나 관리 UI의 MCP Servers에서 등록하세요(MCP Gateway 참고). 아래 모든 부여는 서버를 그 server_id(UI에서 추가한 서버는 UUID) 또는 server_name 별칭(config 키, 예: deepwiki)으로 참조해요. 두 형식 모두 API가 받아들이고 같은 서버로 해석돼요.

여러 서버를 항상 함께 부여해야 한다면 접근 그룹에 넣고 그룹을 부여하세요. 키나 팀이 서버 전반에서 직접 고른 도구 하위 집합을 봐야 한다면 툴셋을 만들고 그것을 부여하세요.

부여 필드 (The grant fields)

MCP 접근은 키 또는 팀의 object_permission 블록에 저장돼요. 동일한 네 필드가 둘 다에서 작동하며 관리 UI MCP Settings 섹션의 컨트롤에 일대일로 매핑돼요.

필드	타입	부여하는 것
`mcp_servers`	`list[str]`	엔티티가 도달할 수 있는 서버 ID 또는 별칭. 센티널 `no-mcp-servers`는 모든 MCP 접근을 차단해요(Opting a key out 참고)
`mcp_access_groups`	`list[str]`	접근 그룹 이름. 그룹의 모든 서버가 부여됨
`mcp_toolsets`	`list[str]`	툴셋 ID. 툴셋이 도구를 끌어오는 서버를 부여하되, 이름이 지정된 도구로 제한
`mcp_tool_permissions`	`dict[str, list[str]]`	서버별 도구 허용 목록. 서버 ID 또는 별칭이 키. 서버를 생략하면 그 도구 전부 허용. 여기에 이름이 있는 서버는 `mcp_servers`에 없어도 부여된 것으로 간주

이 필드 중 아무것도 설정되지 않은 키나 팀은 그 자체로 MCP 제한이 없으며, 런타임에서 무엇을 의미하는지는 다른 레벨에 달려 있어요(How key and team grants resolve 참고).

가상 키에 MCP 서버 부여 (Grant an MCP server to a virtual key)

관리 UI (Admin UI)

왼쪽 사이드바에서 Virtual Keys를 열고(http://localhost:4000/ui/api-keys) + Create New Key 클릭. 평소처럼 소유자, 키 이름, 모델을 채운 후 아래로 스크롤해 MCP Settings 아코디언을 펼치세요. Allowed MCP Servers 선택기는 등록된 모든 서버, 접근 그룹, 툴셋과 함께 키의 모든 MCP 접근을 차단하는 No MCP Servers 항목을 나열해요.

하나 이상 항목을 선택하세요. 각 선택된 서버(접근 그룹에서 해석된 서버 포함)는 아래에 도구 목록을 펼치고 모든 도구가 기본으로 켜져 있어요. 키에서 도구를 제거하려면 체크를 해제하세요. 헤더는 얼마나 많은 도구가 허용되는지 보여줍니다. Create Key 클릭 후 확인 대화상자에서 키를 복사하세요.

선택은 object_permission.mcp_servers(또는 선택에 따라 mcp_access_groups / mcp_toolsets)로, 도구 토글은 object_permission.mcp_tool_permissions로 저장돼요. GET /key/info?key=<key>로 다시 읽을 수 있어요.

기존 키를 변경하려면 Virtual Keys 표에서 키를 클릭하고 Settings 탭 열고 Edit Settings 클릭, MCP Servers / Access Groups와 도구 토글을 변경한 후 Save Changes 클릭.

API (API)

POST /key/generate는 부여를 인라인으로 받아요. 아래 예시는 하나의 서버를 부여하고 키를 그 두 도구로 제한해요:

MCP 부여로 키 생성:

curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "wiki-reader",
    "team_id": "<team-id>",
    "object_permission": {
      "mcp_servers": ["deepwiki"],
      "mcp_tool_permissions": {
        "deepwiki": ["read_wiki_structure", "read_wiki_contents"]
      }
    }
  }'

POST /key/update는 같은 블록과 변경할 key를 받아요. 보내는 필드는 그 필드의 저장 값을 대체하고 생략한 필드는 유지하므로, 위 키에 툴셋을 추가하면 mcp_servers와 mcp_tool_permissions는 그대로 남아요:

기존 키에 툴셋 추가:

curl -X POST "http://localhost:4000/key/update" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "sk-...",
    "object_permission": {
      "mcp_toolsets": ["<toolset-id>"]
    }
  }'

접근 그룹의 모든 서버를 부여하려면 mcp_servers 대신 "mcp_access_groups": ["research"]를 보내세요. 모든 MCP 접근을 차단하려면 "mcp_servers": ["no-mcp-servers"]를 보냅니다.

키로 도구를 나열해 키가 보는 것을 확인하세요:

curl -s "http://localhost:4000/mcp-rest/tools/list" \
  -H "Authorization: Bearer ***" | jq '[.tools[] | .name]'

["read_wiki_contents", "read_wiki_structure"]

팀에 MCP 서버 부여 (Grant an MCP server to a team)

관리 UI (Admin UI)

왼쪽 사이드바에서 Teams를 열고(http://localhost:4000/ui/teams) Create Team 클릭. 팀 이름과 모델을 채운 후 MCP Settings 아코디언을 펼치세요. Allowed MCP Servers 선택기는 키 폼과 같은 서버, 접근 그룹, 툴셋을 제공해요. 접근 그룹을 선택하면 그룹 이름으로 태깅된 각 서버가 보여서 서버별로 여전히 도구를 토글할 수 있어요. Create Team 클릭.

기존 팀을 변경하려면 Teams 표에서 팀을 클릭하고 Settings 탭 열고 Edit Settings 클릭, MCP Servers / Access Groups와 도구 토글을 변경한 후 Save Changes 클릭. 팀에 속한 키는 새 부여를 상속하며 키에서 편집할 것이 없어요.

API (API)

POST /team/new와 POST /team/update는 키 엔드포인트와 같은 object_permission 블록을 받고, 업데이트 시 team_id가 팀을 식별해요.

MCP 부여로 팀 생성:

curl -X POST "http://localhost:4000/team/new" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "team_alias": "research-team",
    "object_permission": {
      "mcp_servers": ["deepwiki"],
      "mcp_access_groups": ["research"],
      "mcp_toolsets": ["<toolset-id>"],
      "mcp_tool_permissions": {
        "deepwiki": ["read_wiki_structure", "read_wiki_contents"]
      }
    }
  }'

팀 서버 목록 교체(나머지는 유지):

curl -X POST "http://localhost:4000/team/update" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "<team-id>",
    "object_permission": {
      "mcp_servers": ["deepwiki"]
    }
  }'

/team/update는 /key/update처럼 병합해요. 보낸 필드만 대체됩니다. 저장된 부여는 GET /team/info?team_id=<team-id>로 다시 읽을 수 있고, team_info.object_permission 아래 반환돼요.

키·팀 부여가 해석되는 방식 (How key and team grants resolve)

전체 규칙 집합은 Permission Hierarchy와 Per-entity Tool-Level Permissions에 있어요. 아래 경우는 키와 그 팀만 부여를 가질 때 직면하는 경우로, LiteLLM이 적용하는 순서대로요.

자체 MCP 부여가 없는 키는 팀의 부여를 상속해요. 팀이 허용하는 모든 서버와 모든 도구가 키에 제공되고 그 외에는 없어요. general_settings의 require_key_mcp_access_defined: true가 있으면 같은 키는 명시적으로 부여받기 전까지 MCP 서버가 전혀 없어요(Require keys to define their own MCP access 참고).

키와 팀이 모두 서버를 나열하면 키는 교집합에 도달해요. 도구 권한도 서버별로 교집합돼요. deepwiki에서 팀이 두 도구를 허용하고 키가 그중 하나를 허용하면 그 하나의 도구를 얻게 돼요. 한쪽만 서버에 대해 mcp_tool_permissions를 설정하면 그쪽 목록이 그대로 적용돼요.

단일 레벨 내에서 툴셋과 직접 mcp_tool_permissions 항목은 레벨이 교집합되기 전에 합집합됩니다. 툴셋 wiki_readonly(읽기 도구 2개)에 mcp_tool_permissions: {"deepwiki": ["read_wiki_structure"]}가 부여된 키는 직접 이름이 지정된 하나가 아니라 두 읽기 도구 모두를 봐요.

키의 no-mcp-servers는 어떤 팀 부여보다 우선해요. 팀이 서버를 허용해도 tools/list는 빈 목록을 반환하고 tools/call은 거부돼요.

팀 안의 키는 팀이 이미 허용하는 서버(또는 allow_all_keys로 표시된 서버)만 부여받을 수 있어요. /key/generate와 /key/update는 쓰기 시점에 이를 강제하고(관리 UI도 같은 엔드포인트로 저장) 403으로 응답해요:

Key requests MCP servers not allowed by team '<team-id>': ['<server-id>']. Team allows: ['<server-id>']. Global (allow_all_keys) servers: [].

팀에 없는 키는 프록시 관리자가 어떤 서버든 부여할 수 있고, 관리자가 아닌 호출자는 그런 키에 allow_all_keys 서버만 부여할 수 있어요. 키가 이미 보유한 서버는 /key/update에서 기존대로 유지되므로, 팀 목록을 줄여도 새 서버를 추가하려 하기 전까지는 기존 키를 깨지 않아요.

조직, 내부 사용자, 최종 사용자, 에이전트 부여는 키와 팀 위에 있으며 결과를 더 좁힐 뿐이에요. 좁히기는 tools/list 시점과 다시 tools/call 시점에 발생하므로, 유효 집합 밖의 도구는 광고되지도 호출될 수도 없어요.

실전 예시 (Worked example)

팀 research-team은 deepwiki를 mcp_tool_permissions: {"deepwiki": ["read_wiki_structure", "read_wiki_contents"]}와 툴셋 wiki_readonly(같은 두 도구)로 허용해요.

키 부여	`deepwiki`의 유효 도구
없음	`read_wiki_structure`, `read_wiki_contents`(팀에서 상속)
`mcp_servers: ["deepwiki"]`, `mcp_tool_permissions: {"deepwiki": ["read_wiki_structure"]}`	`read_wiki_structure`(교집합)
위 행에 `mcp_toolsets: ["wiki_readonly"]` 추가	`read_wiki_structure`, `read_wiki_contents`(키 레벨 합집합 후 팀과 교집합)
`mcp_servers: ["no-mcp-servers"]`	없음, `tools/list` 비어 있음
`mcp_servers: ["deepwiki_backup"]`(팀이 허용하지 않음)	쓰기 거부 `403`

MCP Permission Management — 규칙과 나머지 레벨(조직, 내부 사용자, 최종 사용자, 에이전트), MCP Toolsets — 툴셋 생성, Agent Permission Management — 에이전트 부여, MCP Gateway — 서버 등록.

더 알아보기 (Learn more)

MCP 권한 관리 — 접근 규칙과 계층
MCP Toolsets — 툴셋 생성

키·팀에 MCP 서버 접근 부여