chore(release): backport #31029 to stable/1.89.x and cut 1.89.4

[yuneng-berri]

Relevant issues

Backports #31029 onto stable/1.89.x and cuts 1.89.4. The change adds a no-mcp-servers sentinel (mirroring no-default-models for models) so a virtual key can be scoped to zero MCP servers. Before this, an empty mcp_servers list always meant "inherit the team", so there was no value a user could set to say "this key gets none"; the sentinel is the explicit zero that overrides team inheritance, additive access-group grants, and allow_all_keys servers, and also denies toolset-scoped access.

This is a feature backport. The pick applied cleanly with no conflicts; no production logic line was altered from the staging commit.

What is included

• feat(mcp): scope a key to zero MCP servers with no-mcp-servers sentinel #31029 feat(mcp): scope a key to zero MCP servers with no-mcp-servers sentinel, cherry-picked from staging 19a29e0
• bump: version 1.89.3 -> 1.89.4
• chore: refresh uv.lock for 1.89.4

UI rebuild deferred

This pick changes production UI source (MCPServerSelector.tsx, create_key_button.tsx, MCPServerPermissions.tsx, key_edit_view.tsx, and mcp_tools/constants.ts). The proxy serves a prebuilt Next.js bundle from litellm/proxy/_experimental/out/, and that bundle is NOT rebuilt in this PR. The stable UI will be rebuilt separately on this branch after merge. Until that rebuild lands, the backend opt-out is fully functional over the API (a key whose object_permission.mcp_servers holds no-mcp-servers returns zero tools), but the "No MCP Servers" option will not yet appear in the key create/edit forms on the stable build.

Adaptation notes

The pick is patch-id ADAPTED relative to staging, but only in surrounding context; none of the PR's own added lines were modified, and there was no merge conflict. The divergences are import-block neighbors that differ between 1.89.x and staging in three source files (for example user_api_key_auth vs ip_address_utils, and a TYPE_CHECKING block vs direct repository imports in object_permission_utils.py), plus hunk line-number offsets. The PR's added SpecialMCPServerNames imports and logic are byte-identical; only the unrelated neighbor lines differ, confirmed with git range-diff.

Known noise on this line

None in the targeted set. The four test files this PR touches were all green on the line tip before picking (359 passed / 0 failed); after the pick the same four files are 368 passed / 0 failed, a clean +9 that matches the sentinel and toolset tests the PR adds.

Screenshots / Proof of Fix

Verified against a live proxy running the 1.89.x worktree code with the pick applied, with two config MCP servers (wikipedia stdio and deepwiki http) marked allow_all_keys: true, against a clean isolated Postgres stood up for the replay. The shared dev DB could not be used because its Prisma client under the shared .venv is newer than the database it points at (a client/schema mismatch unrelated to this pick), so an isolated database was used instead.

Every key that is not scoped with the sentinel sees the allow-all servers union (4 tools); only the sentinel key sees zero. Keys are created with POST /key/generate setting object_permission.mcp_servers, then tools are listed per key over GET /mcp-rest/tools/list:

master key                                  -> 4 tools  (wikipedia-fetch + 3 deepwiki-*)
team key, mcp_servers: []        (inherit)  -> 4 tools
team key, mcp_servers: ["no-mcp-servers"]   -> 0 tools   (opt-out; overrides team inheritance)
team key, mcp_servers: ["wikipedia"]        -> 4 tools  (allow_all union still applies)
direct key, mcp_servers: ["no-mcp-servers"] -> 0 tools   (overrides allow_all_keys)
direct key, no object_permission            -> 4 tools  (inherits allow_all)

Only the two sentinel keys return zero, while empty-inherit, named-server, and no-permission keys all return the full set; the worktree was verified clean (unmutated) before and after the replay. The authoritative behavioral proof is the unit-test delta above: the sentinel and toolset tests the PR adds all pass on the line, including test_no_mcp_servers_sentinel_blocks_allow_all_keys (allow-all override) and test_no_mcp_servers_sentinel_denies_toolset_access (toolset 403), which the live curl cannot easily isolate.

Gauntlet (behavioral, universal, deep): SURVIVED across 2 rounds and 7 lenses, zero verified findings, seal holds. All three sub-claims survived: every symbol the pick references resolves, the pick delivers its opt-out on every reachable path, and an empty mcp_servers list still inherits the team exactly as before. The only state divergence the seal examined was the benign bump and lock commits on top of the pick (the relevant source files are byte-identical to the verified pick). Symbol closure resolves (SpecialMCPServerNames defined in _types.py, ruff clean on all touched modules).

Type

🆕 New Feature

Changes

Backport of the no-mcp-servers sentinel onto stable/1.89.x with a 1.89.4 version bump. Backend, tests, and UI source are carried; the UI bundle is rebuilt separately after merge.

[greptile-apps]

Greptile Summary

This PR backports the no-mcp-servers sentinel from staging onto stable/1.89.x and cuts version 1.89.4. The sentinel gives a virtual key an explicit zero-server scope, overriding team inheritance, allow_all_keys grants, and toolset-scoped access — mirroring how no-default-models works for model scoping.

• Backend: SpecialMCPServerNames.no_mcp_servers enum added to _types.py; enforced at three independent layers — _get_allowed_mcp_servers_for_key/get_allowed_mcp_servers in the auth handler, the MCPServerManager, and _apply_toolset_scope (which runs before the admin branch to prevent toolset rewrites from dropping the sentinel).
• Data path: _extract_requested_mcp_server_ids discards the sentinel before team-validation, while _rewrite_object_permission_mcp_servers passes it through unchanged, so it survives the alias-resolution rewrite into the stored object_permission.
• UI: NO_MCP_SERVERS_SENTINEL constant added in constants.ts (correct location); MCPServerSelector gains an allowNoMcpServers prop that renders an exclusive "No MCP Servers" option and disables all other server choices while it is selected; the sentinel is filtered out before being handed to MCPToolPermissions. UI bundle rebuild is deferred and documented.

Confidence Score: 4/5

Safe to merge; the sentinel correctly returns zero servers at every reachable code path and all nine new tests pass cleanly.

The three-layer enforcement (auth handler, server manager, toolset scope) is correctly ordered and independently tested. The validate_key_mcp_servers_against_team bypass for the sentinel-only case is intentional — opting into zero servers is more restrictive than any team ceiling. The UI bundle not being rebuilt is documented and the backend opt-out works entirely over the API without it. The interaction between the sentinel and a mcp_servers list that contains both the sentinel and real server IDs is logically consistent but not explicitly tested end-to-end: the sentinel dominates at runtime but the real server still passes key-creation validation.

object_permission_utils.py — the path where a key carries both the sentinel and real server IDs deserves a dedicated test to confirm the sentinel still dominates after the rewrite step.

Important Files Changed

Filename	Overview
litellm/proxy/_types.py	Adds SpecialMCPServerNames enum with no_mcp_servers = "no-mcp-servers", mirroring the existing SpecialModelNames pattern.
litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py	Adds sentinel short-circuit at two points: _get_allowed_mcp_servers_for_key surfaces the sentinel unexpanded; get_allowed_mcp_servers returns [] when sentinel detected, before consulting the team.
litellm/proxy/_experimental/mcp_server/mcp_server_manager.py	Adds sentinel guard at the top of MCPServerManager.get_allowed_mcp_servers, returning [] before allow_all_keys layering — prevents allow-all servers from overriding an explicit opt-out.
litellm/proxy/_experimental/mcp_server/server.py	Adds sentinel check at the top of _apply_toolset_scope, raising 403 before the admin branch — prevents toolset-scoped access from bypassing the sentinel by replacing mcp_servers.
litellm/proxy/management_helpers/object_permission_utils.py	Passes sentinel through _rewrite_object_permission_mcp_servers unchanged; discards it from _extract_requested_mcp_server_ids so team-validation logic skips it — both changes are correct.
ui/litellm-dashboard/src/components/mcp_server_management/MCPServerSelector.tsx	Adds allowNoMcpServers prop; handler enforces exclusivity (sentinel clears all else); disabled overlay applied to real-server options when sentinel is active.
ui/litellm-dashboard/src/components/permissions/MCPServerPermissions.tsx	Filters sentinel from display list; renders a "Blocked" badge and red callout when sentinel is present — correct and informative.
ui/litellm-dashboard/src/components/organisms/create_key_button.tsx	Passes allowNoMcpServers to selector; filters sentinel before handing servers to MCPToolPermissions to avoid querying tool-level permissions for a blocked key.
ui/litellm-dashboard/src/components/templates/key_edit_view.tsx	Same sentinel-filter applied to MCPToolPermissions in the edit view; consistent with create_key_button.tsx.
ui/litellm-dashboard/src/components/mcp_tools/constants.ts	New file; exports NO_MCP_SERVERS_SENTINEL = "no-mcp-servers" — correctly placed in constants.ts and matches the backend enum value.
tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py	Adds two new mock-only tests: sentinel returns empty across varied team configurations, and _get_allowed_mcp_servers_for_key surfaces the sentinel unexpanded.
tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py	Adds test_no_mcp_servers_sentinel_blocks_allow_all_keys — verifies sentinel short-circuits before MCPRequestHandler.get_allowed_mcp_servers is called and with allow_all_keys servers present.
tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py	Adds test_no_mcp_servers_sentinel_denies_toolset_access parameterized over regular and admin roles, confirming 403 before the toolset resolver is consulted.
tests/test_litellm/proxy/management_helpers/test_object_permission_utils.py	Adds three tests: sentinel excluded from validation set, sentinel preserved through rewrite, and sentinel passes team validation without rejection.
ui/litellm-dashboard/src/components/mcp_server_management/MCPServerSelector.test.tsx	New test file covering: sentinel hidden by default, exclusive sentinel emission on selection, and real-server options disabled while sentinel is active.

Comments Outside Diff (1)

1. litellm/proxy/management_helpers/object_permission_utils.py, line 483-526 (link)

   Untested mixed-sentinel case in validation path

   When a key's mcp_servers contains both the sentinel and real server IDs — e.g. ["no-mcp-servers", "server-1"] — _extract_requested_mcp_server_ids discards the sentinel and validates only "server-1". If that server is allowed, the permission write-back in _rewrite_object_permission_mcp_servers will store both the sentinel and the resolved server ID. At runtime the sentinel dominates and the key sees zero servers, but during key-creation the real server silently passes validation, making the stored state harder to reason about. A test covering this combination (sentinel + valid server → sentinel still dominates at auth time) would make the invariant explicit and guard against future changes to the validation order.

_{Reviews (1): Last reviewed commit: "chore: refresh uv.lock for 1.89.4" | Re-trigger Greptile}

[veria-ai]

Medium: MCP opt-out bypass through Responses toolsets

This guard covers _apply_toolset_scope, but the Responses API uses LiteLLM_Proxy_MCP_Handler._apply_toolset_permissions() in litellm/responses/mcp/litellm_proxy_mcp_handler.py, which replaces object_permission.mcp_servers with the resolved toolset server IDs and drops the new sentinel. A user with a key containing mcp_servers: ["no-mcp-servers"] and an mcp_toolsets grant can request litellm_proxy/mcp/<toolset> through Responses and still get those MCP tools; add the same sentinel check before resolving or applying toolset permissions there, or centralize the check so all toolset-scoping paths share it.

[veria-ai]

PR overview

This PR backports changes from #31029 to the stable/1.89.x branch and prepares the LiteLLM 1.89.4 release. The touched code includes LiteLLM proxy MCP server and toolset permission handling.

There is one open security issue remaining. The MCP opt-out sentinel is not consistently enforced on the Responses API toolset path, so a key configured to opt out of MCP servers but also granted an MCP toolset can still reach those tools through that route. This is an authenticated permission-bypass scenario with a constrained scope, but it should be fixed before release.

Open issues (1)

• Medium: MCP opt-out bypass through Responses toolsets — litellm/proxy/_experimental/mcp_server/server.py:3308

Fixed/addressed: 0 · PR risk: 6/10