BerriAI/litellm · error · HTTPException

Restricted virtual keys cannot query team-scoped MCP servers

Error message

Restricted virtual keys cannot query team-scoped MCP servers.

What it means

Scope guard on the team-filtered server list: a restricted virtual key (a key with object_permission-level MCP restrictions) attempted GET /v1/mcp/server?team_id=..., which would let it enumerate team-scoped servers. Restricted keys are only allowed their explicitly granted server set, not team-scoped listings.

Source

Thrown at litellm/proxy/management_endpoints/mcp_management_endpoints.py:1092

        """
        Get all of the configured mcp servers for the user in the db with their associated teams
        ```
        curl --location 'http://localhost:4000/v1/mcp/server' \
        --header 'Authorization: Bearer your_api_key_here'

        # Filter by team scope (for Create Key UI)
        curl --location 'http://localhost:4000/v1/mcp/server?team_id=team-123' \
        --header 'Authorization: Bearer your_api_key_here'
        ```
        """

        # If team_id is provided, return team-scoped servers + allow_all_keys servers
        is_restricted_virtual_key: Final = _is_restricted_virtual_key_request(user_api_key_dict)
        if team_id is not None and isinstance(team_id, str) and team_id.strip():
            # Restricted virtual keys must not use the team_id filter to
            # bypass their own access limitations.
            if is_restricted_virtual_key:
                raise HTTPException(
                    status_code=403,
                    detail="Restricted virtual keys cannot query team-scoped MCP servers.",
                )

            # Only proxy admins may query another team's MCP servers.
            # Non-admins must belong to the requested team.
            sanitized_team_id: Final = team_id.strip()
            is_admin: Final = _user_has_admin_view(user_api_key_dict)
            if not is_admin:
                from litellm.proxy.auth.auth_checks import get_team_object
                from litellm.proxy.proxy_server import (
                    prisma_client,
                    user_api_key_cache,
                )

                team_obj: Final = await get_team_object(
                    team_id=sanitized_team_id,
                    prisma_client=prisma_client,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Use a non-restricted (full-access) virtual key to query team-scoped MCP servers.
2. Ask a proxy admin to grant the key access to the required routes.

When it happens

Trigger: Thrown at litellm/proxy/management_endpoints/mcp_management_endpoints.py:1092 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/1ab7f193af667ebb. Report an issue: GitHub.