fix(mcp): extend key access-group union to MCP servers

[ryan-crabbe-berri]

Summary

A key's unified access_group_ids now extend the team's MCP scope instead of being capped by it — mirroring the model-side union shipped in LIT-2404. The override is still gated by the access group's assigned_team_ids / assigned_key_ids, so a team member cannot pull in MCPs via a foreign team's group. End-user / agent / org ceilings remain unchanged and still cap the unioned result.

A new shared helper get_authorized_resources_from_key_access_groups (in auth_checks.py) factors out the per-group fetch + assignment-gate + resource extraction. Both the existing model path and the new MCP path call it with their respective resource_field.

Screenshots

before

after

Test plan

• tests/proxy_unit_tests/test_auth_checks.py::test_key_access_group_grants_model_* (6) — model-side regression after refactor.
• tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py::test_mcp_key_access_group_extras_* (6) — mirrors the 6 model scenarios on the new MCP helper (team-authorized, key-authorized, no groups, empty grant, foreign-group escalation regression, lookup failure).
• …::test_get_allowed_mcp_servers_unions_key_access_group_extras / …::test_get_allowed_mcp_servers_no_union_when_no_authorized_extras — end-to-end on get_allowed_mcp_servers.
• Full files green: test_auth_checks.py 62/62, test_user_api_key_auth_mcp.py 123/123.
• End-to-end against a running proxy + two real FastMCP backends: team with mcp_servers=[postgres] and key holding access group with assigned_team_ids=[team], access_mcp_server_ids=[stripe]. BEFORE: GET /v1/mcp/tools returns 2 tools (postgres only). AFTER: 4 tools (postgres + stripe).

Resolves LIT-3189

[codecov]

Codecov Report

❌ Patch coverage is 82.35294% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...erimental/mcp_server/auth/user_api_key_auth_mcp.py	84.00%	4 Missing ⚠️
litellm/proxy/auth/auth_checks.py	77.77%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR extends the key access_group_ids union—previously only applied to models—to MCP servers, mirroring the LIT-2404 model-side behavior. A new shared helper get_authorized_resources_from_key_access_groups in auth_checks.py replaces the old model-only function, and get_allowed_mcp_servers now unions key/team scope with access-group extras gated by assigned_team_ids/assigned_key_ids.

• auth_checks.py: _key_access_group_grants_model is refactored to delegate to the new generic get_authorized_resources_from_key_access_groups(resource_field=...), removing the duplicated loop and deduplication logic while preserving identical semantics for the model path.
• user_api_key_auth_mcp.py: New _get_key_access_group_mcp_server_extras static method fetches MCP server IDs from authorized access groups and unions them into the final allowed server set; end-user, agent, and org ceilings are applied after the union and still cap the extended result.
• Tests: Eight new unit tests cover the happy paths, edge cases (empty groups, foreign-group escalation regression), and end-to-end get_allowed_mcp_servers behavior.

Confidence Score: 5/5

Safe to merge — the authorization gate (assigned_team_ids/assigned_key_ids) is preserved, the org/end-user/agent ceilings still cap the extended result, and the refactor of the model path is behavior-neutral.

The shared helper is a clean extraction with no logic change for the existing model path. The new MCP extras union correctly inherits all downstream ceiling filters. The foreign-group escalation regression test explicitly covers the key security boundary. Cache-first semantics via get_access_object are maintained, and global_mcp_server_manager is an initialized module-level singleton so there is no uninitialized-reference risk at runtime.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/auth/auth_checks.py	Extracts generic get_authorized_resources_from_key_access_groups helper from _key_access_group_grants_model; refactors existing model path to call the shared helper. Logic and deduplication are preserved correctly.
litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py	Adds _get_key_access_group_mcp_server_extras and wires it into get_allowed_mcp_servers as a union with the team/key base scope. End-user, agent, and org ceiling intersections correctly apply to the extended set.
tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py	Adds 8 focused tests covering the new MCP access-group extras path (team-authorized, key-authorized, no groups, empty grant, foreign-group escalation regression, lookup failure, two end-to-end scenarios). Minor parentheses cleanup in existing assertions only.

_{Reviews (1): Last reviewed commit: "fix(mcp): extend key access-group union ..." | Re-trigger Greptile}