跳至主要內容

在企業版部署 LiteAdmin MCP

將 Claude Code 或 Codex 連接到您位於 /admin/mcp 的閘道，以管理金鑰、團隊、模型和預算

企業版功能

Embedded LiteAdmin MCP需要 LiteLLM 企業版授權。立即開始 30 天免費試用或預約展示。 查看企業版完整功能。

圖片可用性

LiteLLM 1.106.x 及更新版本可用。 請從 HTTPS 部署與資料庫開始。託管預設為關閉；基礎 Enterprise 授權已涵蓋此功能

1. 啟用 MCP​

保留您現有的 DATABASE_URL、LITELLM_MASTER_KEY 和 proxy 設定。請在啟用端點之前，將任何名為 admin 的 MCP 伺服器別名重新命名，因為該端點會保留 /admin

將這些項目新增到您現有的 litellm service。請透過您的 secret store 或 Compose 環境提供授權

docker-compose.yml (service fragment)
services:
  litellm:
    environment:
      LITELLM_ENABLE_ADMIN_MCP: "true"
      LITELLM_LICENSE: ${LITELLM_LICENSE}
      PROXY_BASE_URL: https://gateway.example.com

重新建立 service：

docker compose up -d litellm

將 /admin/mcp 導向容器現有的 port，預設為 4000。這適用於 unified、database 和 non-root 映像

公開 URL 與啟動設定

將 PROXY_BASE_URL 設定為您的公開 HTTPS origin，以供 Host 與 Origin 檢查。若要使用獨立的 MCP hostname，請設定 LITELLM_MCP_PUBLIC_URL=https://admin-mcp.example.com 並連線至 https://admin-mcp.example.com/admin/mcp

選擇加入但授權無效或 enable-flag 值錯誤都會導致啟動失敗。若要停用 MCP，請將 LITELLM_ENABLE_ADMIN_MCP=false 設為 false 並重新啟動提供服務的容器

2. 連接用戶端​

若要使用原生 key 驗證，請使用由 proxy_admin 擁有的個人 virtual key 進行讀寫。Viewer 與 team-admin 角色無法連線。請將 master key 保留在伺服器上

claude mcp add --scope user --transport http litellm-admin \
  https://gateway.example.com/admin/mcp \
  --header 'Authorization: Bearer <your-personal-proxy-admin-key>'

重新啟動 Claude Code，然後執行 /mcp。此命令會將您的 key 儲存在 Claude 的設定中，並可能保留在 shell history 中

請將 client key 排除在版本控制之外。此端點不提供 codex mcp login 的瀏覽器 OAuth 登入。若使用 Claude Desktop，請使用 本機 MCP 設定

自訂 key header

即使使用 general_settings.litellm_key_header_name，也請送出 Authorization: Bearer ...。LiteLLM 會在您設定的 header 下轉送相同的 key

請將憑證 header 與身分、傳輸、稽核、網路和政策 header 分開。名稱衝突會導致啟動失敗

OAuth2 proxy 驗證

使用 general_settings.enable_oauth2_proxy_auth 時，請透過您的驗證 proxy 路由 request。原始呼叫端的直接對等端必須符合 trusted_proxy_ranges；oauth2_config_mappings 中的 header 會選取具有已儲存 proxy_admin 角色的使用者

請設定 proxy 覆寫身分 header，使其使用已驗證使用者的值。connector 需要 bearer，但原生驗證會使用身分 header。個人 admin key 不會覆寫此模式

3. 驗證​

請向您連接的用戶端詢問：

使用 LiteAdmin 列出我的團隊及其目前的預算。

確認它有呼叫 admin tool，並回傳您閘道的資料。空白的團隊清單是有效的

使用 curl 檢查

若使用原生 key 驗證，請將 ADMIN_KEY 設為您的個人 proxy-admin key：

curl --fail-with-body https://gateway.example.com/admin/mcp \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

預期會看到包含 admin key 的 tool catalog、沒有憑證的 401，以及沒有 proxy_admin 角色的 403。已停用的端點或對 gateway 元件的 request 會回傳 404

工具與回應設定​

限制工具或變更回應格式

請在 LiteLLM 或 backend 容器上設定這些變數，然後重新啟動它

變數預設值選項
LITELLM_ADMIN_READ_ONLYfalsetrue 會將探索與執行限制為經審核的讀取操作；需要 proxy_admin
LITELLM_ADMIN_TOOLS所有可用的經審核操作以逗號分隔的 tool names，例如 list_keys,list_teams；與唯讀限制結合
LITELLM_ADMIN_RESPONSE_VIEWfullfull 會以內嵌方式回傳結果；compact 可以回傳已儲存結果的參照
LITELLM_ADMIN_SCHEMA_MODEfulldiscovery 會將參數詳細資訊延後至 describe_admin_tool；執行時會驗證完整結構描述

在多個 worker 或副本的情況下，請保留 full 回應。使用 compact 時，請將 read_admin_result call 傳送到相同的 worker process；僅靠 pod affinity 並不足夠。結果會在 worker 重新啟動時到期並消失。請在重試寫入之前檢查 gateway 狀態

疑難排解​

症狀檢查項目
啟動失敗檢查啟動錯誤中的授權、enable flag，以及衝突的 header 名稱
缺少 MCP 依賴項使用 LiteLLM 1.106.x 或更新版本的 unified 或 backend 映像
404檢查映像版本、enable flag，以及容器重新啟動。將 /admin/mcp 原樣路由到 unified proxy 或 backend
key 模式下出現 401 或 403使用有效的個人 proxy_admin key
OAuth2 proxy 驗證失敗檢查受信任的直接對等端、對應的身分 header，以及已儲存的使用者角色
Host 或 Origin 被拒絕將 PROXY_BASE_URL 或 LITELLM_MCP_PUBLIC_URL 對應到您的公開 HTTPS origin
缺少工具檢查工具限制與底層管理 API 的可用性
無法使用 Compact result使用相同的 worker process，或切換為 full
寫入逾時在重試之前檢查 gateway 狀態；connector 不會重試 tool calls

關於模型建立，請參閱 新增模型部署。若要執行 Slack agent worker，請依照 LiteAdmin Slack app 設定

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