跳至主要內容

MCP 權限管理

在 LiteLLM 中控制哪些 MCP 伺服器和工具可供特定金鑰、團隊或組織存取。當用戶端嘗試列出或呼叫工具時，LiteLLM 會根據已設定的權限強制執行存取控制。

概覽​

LiteLLM 為 MCP 伺服器提供細緻的權限管理，讓您可以：

  • 依實體限制 MCP 存取：控制哪些金鑰、團隊或組織可以存取特定的 MCP 伺服器
  • 工具層級篩選：根據實體權限自動篩選可用工具
  • 集中式控制：從 LiteLLM 管理員介面或 API 管理所有 MCP 權限
  • 一鍵公開 MCP：在不需要逐金鑰限制時，將特定伺服器標記為所有 LiteLLM API 金鑰皆可使用

這可確保只有獲授權的實體才能探索並使用 MCP 工具，為您的 MCP 基礎架構提供額外的安全層。

相關文件

運作方式​

LiteLLM 支援在 LiteLLM 上以金鑰、團隊、組織（實體）來管理 MCP 伺服器的權限。當 MCP 用戶端嘗試列出工具時，LiteLLM 只會回傳該實體有權存取的工具。

建立金鑰、團隊或組織時，您可以選擇該實體可存取的允許 MCP 伺服器。

權限階層​

權限可設定於六個不同層級。當多個層級同時適用於某個請求時，LiteLLM 會取交集（最嚴格者勝出），組織層級除外，其作用為上限。

層級來源組合方式
Key虛擬 key 上的 object_permission.mcp_servers / object_permission.mcp_access_groups如果 key 有明確清單，就使用該清單。
Teamteam 上相同的欄位如果 key 和 team 都有清單，結果為交集（只保留同時屬於兩者的 servers）。如果只有 team 有清單，key 會繼承該清單。
End user與 x-litellm-end-user-id 相符的 LiteLLM_EndUserTable 資料列上的相同欄位與目前結果取交集。若請求中沒有 end-user-id，則略過。
Agent由 x-litellm-agent-id 所識別的 agent 上的相同欄位，或 key 綁定的 agent（在 key 生成時設定 agent_id）與目前結果取交集。若不適用任何 agent，則略過。
Internal user請求驗證為其身分的 internal user（真人）上的相同欄位與目前結果取交集，因此只能縮小範圍。若該使用者沒有任何權益，則略過。
Organization擁有該 key/team 的 org 上相同的欄位充當上限；最終允許的 servers 集合會與 org 的清單取交集。若 org 沒有清單，則不會增加額外限制。

如果沒有任何層級有清單，請求可以存取所有 MCP 伺服器（預設為開放）。

綁定到 agent 的 key（將 agent_id 傳給 /key/generate）會獲得與帶有 x-litellm-agent-id 的請求相同的處理方式：該 agent 的清單會在 key 發出的每個請求上與 key 的清單取交集。只授予 key 本身某個 server 並不足夠；agent 也必須持有該授權（透過 Admin UI 的 agent 編輯表單或 PATCH /v1/agents/{agent_id}），否則針對該 server 的請求會被拒絕，並顯示包含 agent 名稱的錯誤。

相同的交集模型也適用於每個伺服器的工具層級字典 mcp_tool_permissions（請參閱下方的 每個實體的工具層級權限）。

要求 key 定義其自己的 MCP 存取​

預設情況下，具有空白或不存在的 mcp_servers 清單的 key 會繼承其 team 的清單，因此 team 實際上是每個 key 預設退回的對象。將 require_key_mcp_access_defined: true 設在 general_settings 下方，可翻轉這種關係：team 變成上限而不是預設值，而空清單的 key 若未明確授予任何 MCP servers（無論是直接在 object_permission.mcp_servers 中，或透過 access group），就不會獲得任何 MCP servers。

config.yaml
general_settings:
  require_key_mcp_access_defined: true

建議採用此設定。使用繼承時，在某個 team 底下發出的每個 key 都會無聲地連到該 team 能連到的每個 MCP server，因此存取會以隱含方式授予，且會隨著 team 清單擴大而擴大；啟用此旗標後，key 只會連到明確授予的內容，而 team 清單只會作為上限而非定義該授權。我們正考慮在未來版本將此設為預設行為；請持續關注並參與 deprecation discussion。當您的 keys 已具備自己的 object_permission.mcp_servers（或 access group）時再啟用此設定，因為在此之前切換會讓依賴繼承的 keys 失去 MCP 存取權。

若 team 的 mcp_servers 清單為空，即使有此旗標，也仍表示「不受限制」，因為空的 team 清單永遠不會限制。此旗標只會改變當 team 確實有清單時，空白 key 清單的含義：繼承它（預設）或不授予任何內容（旗標開啟）。key 上的 access-group 授權仍會累加，因此即使啟用旗標，附加群組仍可到達其 servers。

關於 end-user 層級的等效控制，請參閱 require_end_user_mcp_access_defined。

將 key 排除於所有 MCP servers 之外（no-mcp-servers）​

若要明確拒絕某個 key 的所有 MCP servers，請在其 mcp_servers 清單中放入 sentinel no-mcp-servers。這與用於模型存取的 no-default-models sentinel 相同。不同於空清單會繼承 team 的 servers，no-mcp-servers 會覆寫 team 繼承以及任何累加式 access-group 授權，因此無論 team 允許什麼，該 key 解析後都會是零個 MCP servers。

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

允許/禁止 MCP 工具​

控制哪些工具可從您的 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 伺服器

重要注意事項​

  • 如果您同時指定 allowed_tools 和 disallowed_tools，允許清單會優先
  • 工具名稱區分大小寫

鎖定 Server 的工具清單​

allowed_tools 相信上游對每個工具功能的描述。鎖定也會凍結工具清單、描述和輸入 schema：gateway 只提供已鎖定的工具及其已鎖定的描述與 schema，拒絕對任何其他名稱的呼叫，並在上游與鎖定內容不一致時發出警示。這可阻止工具投毒（OWASP LLM01）：某個 server 悄悄重寫描述以向模型傳遞指令，或新增您的 clients 從未核准的工具，都不會改變 clients 看到的任何內容

將 gateway 目前看到的目錄鎖定（僅限 admin，且需要 database）。使用 GET /v1/mcp/server 找到 server_id。回應會是儲存的快照：每個工具的名稱、描述與輸入 schema：

Pin
curl -s -X POST http://localhost:4000/v1/mcp/server/$SERVER_ID/pin \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"
{
  "get_note": {
    "description": "Return the saved note with the given id",
    "input_schema": {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]}
  }
}

快照會在 discovery guardrail scan 之後擷取，因此被 guardrail 阻擋的描述不會被鎖定，而被遮罩的描述會以其遮罩後的形式被鎖定；若某個 server 最後沒有任何工具可鎖定，則會回傳 400。在鎖定當下生效的 tool_name_to_description 覆寫會被一併鎖定

解除鎖定即可再次提供即時的上游目錄：

Unpin
curl -s -X DELETE http://localhost:4000/v1/mcp/server/$SERVER_ID/pin \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"
{"server_id": "<server_id>", "status": "unpinned"}

server 被鎖定後，clients 會看到：

  • tools/list（優先於 /mcp、/mcp-rest/tools/list，以及 LLM 驅動的 discovery）只會回傳已鎖定的工具，每個工具都帶有其已鎖定的描述與輸入 schema
  • 上游在鎖定後新增的工具不會列出，而且對它的呼叫會回傳 403
  • 上游在鎖定後移除的工具也不會列出，因為 gateway 沒有可呼叫的對象
  • 上游在鎖定後變更的描述或輸入 schema 會以鎖定內容提供

只要某次清單比對發現上游與鎖定內容不同，gateway 就會記錄警告並發送一則 mcp_pinned_tools_changed alert，指出新增、移除與變更的工具；每個 server 的每種不同 diff 只會發送一次。下一次相同 diff 的清單會保持靜默，不同 diff 會再次發出 alert，而當上游重新與鎖定內容一致時，alert 會自行清除。若您審查後接受某項變更，請重新鎖定

MCP server `notes`: upstream tool list drifted from the pinned catalog; serving the pinned tools and descriptions until an admin re-pins the server
added: `delete_all_notes`
changed: `get_note`

重要注意事項​

  • 鎖定涵蓋工具名稱、描述與輸入 schema；上游回報的任何其他工具資訊（annotations、output schema）都會即時提供
  • allowed_tools、disallowed_tools，以及每個 key 的工具權限仍會疊加在鎖定之上
  • discovery guardrail scan 仍會在已鎖定的 server 上執行，針對 proxy 即將提供的已鎖定文字執行：當上游文字遭到污染時，已鎖定的工具仍會提供其已鎖定的描述（並回報為已變更）；而當已鎖定的描述本身被 guardrails 阻擋時，會隱藏並回報為已阻擋，直到 admin 重新鎖定 server
  • 在鎖定後編輯的 tool_name_to_description 覆寫會被視為已變更的工具：已鎖定文字會持續提供，直到 server 重新鎖定

公開 MCP 伺服器（allow_all_keys）​

有些 MCP servers 是為了廣泛共享而設計的：內部知識庫、日曆整合，或其他低風險工具，讓每個 team 都能在不需申請存取權的情況下連線。與其將這些 servers 加入每個 key、team 或 organization，不如啟用新的 allow_all_keys 切換開關。

  1. 在管理員 UI 中開啟 MCP Servers → Add / Edit。
  2. 展開 Permission Management / Access Control。
  3. 將 Allow All LiteLLM Keys 切換為開啟。
管理員 UI 中的 MCP 伺服器組態

這個切換開關會讓伺服器變成「公開」，而不會影響既有的存取群組。

何時使用​

  • 您有共享的 MCP 工具，而細緻的 ACL 只會增加瑣碎工作。
  • 您希望內部使用者有「預設啟用」的體驗，同時仍能疊加工具層級的限制。
  • 您正在讓新團隊上線，希望開箱即用就能使用最安全的 MCP。

啟用後，LiteLLM 會在工具 discovery/calls 期間自動為每個 key 納入該 server，無需額外的 virtual-key 或 team 設定。

允許/禁止 MCP 工具參數​

使用 allowed_params 組態控制特定 MCP 工具允許使用哪些參數。這可透過限制可傳遞給每個工具的參數，對工具使用提供細緻控制。

組態​

allowed_params 是一個將工具名稱對應到允許參數名稱清單的字典。設定後，只有指定的參數會被該工具接受——任何其他參數都會被拒絕並回傳 403 錯誤。

config.yaml with allowed_params
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"]

運作方式​

  1. 工具專屬篩選：每個工具都可以有自己的允許參數清單
  2. 命名彈性：工具名稱可在有或沒有伺服器前綴的情況下指定（例如，"getpetbyid" 和 "my_api_mcp-getpetbyid" 都可用）
  3. 白名單方式：只允許允許清單中的參數
  4. 未列出工具：如果未設定 allowed_params，則允許所有參數
  5. 錯誤處理：帶有不允許參數的請求會收到 403 錯誤，並附上哪些參數允許的詳細資訊

範例請求行為​

使用上方組態時，請求會如何處理如下：

✅ 允許的請求：

{
  "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."
}

使用案例​

  • 安全性：防止使用者存取敏感參數或危險操作
  • 成本控管：限制昂貴參數（例如，限制結果數量）
  • 合規性：為法規需求強制執行參數使用政策
  • 階段性推出：在工具經測試後逐步啟用參數
  • 多租戶隔離：不同使用者群組有不同的參數存取權限

與工具過濾結合​

allowed_params 可與 allowed_tools 和 disallowed_tools 搭配使用，以達到完整控制：

Combined filtering example
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"]

此設定可確保：

  1. 僅有列出的三個工具可用
  2. delete_repo 工具被明確封鎖
  3. 每個工具只能使用其指定的參數

MCP 伺服器存取控制​

LiteLLM Proxy 提供兩種存取特定 MCP 伺服器的控制方式：

  1. 以 URL 為基礎的命名空間 - 使用 URL 路徑直接存取特定伺服器或存取群組
  2. 以標頭為基礎的命名空間 - 使用 x-mcp-servers 標頭指定要存取哪些伺服器

方法 1：基於 URL 的命名空間​

LiteLLM Proxy 支援對 MCP 伺服器使用以 URL 為基礎的命名空間，格式為 /<servers or access groups>/mcp。這可讓您：

  • 直接透過 URL 存取：透過 URL 將 MCP 用戶端直接指向特定伺服器或存取群組
  • 簡化設定：使用 URL 而非標頭來選擇伺服器
  • 支援存取群組：在 URL 中使用存取群組名稱，以便群組化存取伺服器

URL 格式​

<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 - 存取多個特定伺服器中的工具

使用範例​

cURL Example with URL Namespacing
curl --location 'https://api.openai.com/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $OPENAI_API_KEY" \
--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 伺服器。

URL 命名空間的優點​

  • 直接存取：無需額外標頭來指定伺服器
  • 簡潔 URL：具備自我說明性的 URL，可清楚指出哪些伺服器可供存取
  • 存取群組支援：使用存取群組名稱來進行分組伺服器存取
  • 多個伺服器：在單一 URL 中以逗號分隔指定多個伺服器
  • 簡化設定：對偏好以 URL 為基礎設定的 MCP 用戶端而言，更容易完成設定

方法 2：基於標頭的命名空間​

您可以使用 x-mcp-servers 標頭來存取特定 MCP 伺服器，並且只列出它們的工具。此標頭可讓您：

  • 將工具存取限制為一個或多個特定的 MCP 伺服器
  • 控制在不同環境或使用情境中可用的工具

此標頭接受以逗號分隔的伺服器別名清單："alias_1,Server2,Server3"

注意：

  • 如果未提供此標頭，所有可用 MCP 伺服器的工具都將可存取
  • 此方法可搭配標準 LiteLLM MCP 端點運作
cURL Example with Header Namespacing
curl --location 'https://api.openai.com/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $OPENAI_API_KEY" \
--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 伺服器的工具。

比較：標頭與 URL 命名空間​

功能標頭命名空間URL 命名空間
方法使用 x-mcp-servers 標頭使用 URL 路徑 /<servers>/mcp
端點標準 litellm_proxy 端點自訂 /<servers>/mcp 端點
設定需要額外標頭URL 內建自包含
多個伺服器在標頭中以逗號分隔在 URL 路徑中以逗號分隔
存取群組透過標頭支援透過 URL 路徑支援
用戶端支援適用於所有 MCP 用戶端適用於可識別 URL 的 MCP 用戶端
使用情境動態伺服器選擇固定伺服器設定
cURL Example with Server Segregation
curl --location 'https://api.openai.com/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $OPENAI_API_KEY" \
--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 伺服器的工具。

分組 MCP（存取群組）​

MCP 存取群組可讓您將多個 MCP 伺服器分組，以便更容易管理。

1. 建立存取群組​

A. 使用設定建立存取群組：​
Creating access groups for MCP using the config
mcp_servers:
  "deepwiki_mcp":
    url: https://mcp.deepwiki.com/mcp
    transport: "http"
    auth_type: "none"
    access_groups: ["dev_group"]

在使用設定加入 mcp_servers 時：

  • 在 access_groups 中傳入字串清單
  • 接著可使用這些群組，透過金鑰、團隊與使用標頭的 MCP 用戶端來分隔存取權限
B. 使用 UI 建立存取群組​

若要建立存取群組：

  • 前往 LiteLLM UI 中的 MCP Servers
  • 點選 "Add a New MCP Server"
  • 在 "MCP Access Groups" 下，透過輸入建立新群組（例如 "dev_group"）
  • 將相同的群組名稱加入其他伺服器，將它們分組在一起

2. 在 Cursor 中使用存取群組​

在 x-mcp-servers 標頭中包含存取群組名稱：

Cursor Configuration with Access Groups
{
  "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 金鑰​

建立 API 金鑰時，您可以將它們指派給特定的存取群組以進行權限管理：

  • 前往 LiteLLM UI 中的 "Keys" 並點選 "Create Key"
  • 從下拉選單選取所需的 MCP 存取群組
  • 這個金鑰將可存取這些群組中的所有 MCP 伺服器
  • 這會反映在 Test Key 頁面中

每個實體的工具層級權限​

控制不同團隊可從同一個 MCP 伺服器存取哪些工具。例如，讓您的工程團隊可存取 list_repositories、create_issue 與 search_code，而銷售團隊則只可存取 search_code 與 close_issue。

這段影片示範如何為 Key、Team 或 Organization 設定允許的工具。

mcp_tool_permissions API​

object_permission.mcp_tool_permissions 是設定在金鑰、團隊、終端使用者、代理程式、內部使用者或組織上的 Dict[server_id, List[tool_name]]。它會在伺服器層級存取已解析之後才評估（請參閱上方的 權限階層），並套用相同的六層交集：最嚴格者勝出，組織作為上限。

這與伺服器註冊層級的 allowed_tools / disallowed_tools 不同（後者適用於伺服器的每一位呼叫者）。mcp_tool_permissions 可讓您在不變更伺服器設定的情況下，切出每個團隊的子集合。

Engineering key — full GitHub access
curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer sk-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "object_permission": {
      "mcp_servers": ["github_mcp"],
      "mcp_tool_permissions": {
        "github_mcp": ["list_repositories", "create_issue", "search_code"]
      }
    }
  }'
Sales key — read-only on the same server
curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer sk-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "object_permission": {
      "mcp_servers": ["github_mcp"],
      "mcp_tool_permissions": {
        "github_mcp": ["search_code", "close_issue"]
      }
    }
  }'

授權某個人而非憑證​

其他每個層級都在描述憑證或群組：金鑰的範圍、團隊的範圍、組織的上限。內部使用者層級描述的是人，因此管理員可以說明哪些人可執行哪些 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 sk-master-key" \
  | 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 以及其餘的物件權限欄位。

此權限會在 tools/list 時套用，並再次於 tools/call 時套用，因此範圍外的工具永遠不會被公告，而硬編碼該名稱的用戶端仍會遭到拒絕。拒絕結果會在 MCP 回應中，並帶有 isError: true：

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

同一個授與內容也可在管理員介面中的內部使用者詳細資料頁面，透過 Internal Users 編輯。

MCP entitlements section on the internal user detail page
只有代理伺服器管理員才能設定此項

/user/new 和 /user/update 只接受來自代理伺服器管理員的 object_permission。非管理員編輯自己的記錄會被拒絕，因為空白的授與清單代表「不受限制」，而如果允許自我寫入，原本由管理員設定給他的上限就會被解除。

管理員角色不是豁免

具有管理員角色但沒有明確金鑰層級 mcp_servers 清單的呼叫者，通常會看到完整的 MCP 伺服器登錄。當該人本身帶有自己的權限時，這個捷徑就不再適用，而該權限會約束他們；管理員角色會擴大憑證可存取的範圍，並維持附加在個人身上的範圍不變。

每個 MCP 伺服器的速率限制​

使用 mcp_rpm_limit 將金鑰或團隊每分鐘可對特定 MCP 伺服器發出的工具呼叫數量設上限。這是一個以 MCP 伺服器名稱為鍵的 Dict[str, int]；名稱若有設定別名，則使用伺服器別名，否則使用設定的伺服器名稱。每個項目都為該伺服器設定每分鐘請求數上限，因此對 github 的限制不會影響對 slack 的呼叫。未設定項目的伺服器不受上限限制。

一旦在該時間窗內超過上限，之後對該伺服器的工具呼叫會回傳 429 Too Many Requests，直到時間窗重新開始。此上限僅套用於實際的 MCP 工具呼叫；對一般 LLM 請求沒有影響。

Cap a key at 100 github + 200 slack calls per minute
curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer sk-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_rpm_limit": {"github": 100, "slack": 200},
    "object_permission": {"mcp_servers": ["github", "slack"]}
  }'

mcp_rpm_limit 也可用於 /key/update、/team/update、/user/new 與 /user/update。對同一伺服器而言，金鑰層級的限制優先於團隊層級的限制；否則團隊限制會作為共享計數器套用到該團隊中的每個金鑰。

儀表板檢視模式​

代理閘道管理員也可以透過 general_settings.user_mcp_management_mode 控制非管理員在 MCP 儀表板中看到的內容：

  • restricted (預設) – 使用者只會看到其團隊明確擁有存取權的伺服器。
  • view_all – 每位儀表板使用者都能看到完整的 MCP 伺服器清單。
Config example
general_settings:
  user_mcp_management_mode: view_all

當您希望 MCP 供應項目具備可發現性，但又不授予額外的執行權限時，這很有用。

發布 MCP 登錄檔​

如果您希望其他系統（例如在您網路外執行、具備 MCP 功能的 IDE 等外部代理程式框架）能自動探索 LiteLLM 上託管的 MCP 伺服器，您可以公開一個 Model Context Protocol Registry 端點。此登錄會列出內建的 LiteLLM MCP 伺服器以及您已設定的每一台伺服器，並使用 官方 MCP Registry 規格。

  1. 在您的 proxy 設定（或 DB 設定）中的 enable_mcp_registry: true 下設定 general_settings，然後重新啟動 proxy。
  2. LiteLLM 會在 GET /v1/mcp/registry.json 提供 registry。
  3. 每個項目都會指向 /mcp（內建伺服器）或您的自訂伺服器的 /{mcp_server_name}/mcp，因此用戶端可以使用公布的 Streamable HTTP URL 直接連線。
權限仍然適用

registry 只會公布伺服器 URL。實際的存取控制仍會在用戶端連線到 /mcp 或 /{server}/mcp 時由 LiteLLM 強制執行，因此發布 registry 不會繞過每個金鑰的權限。

LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →