BerriAI/litellm · error · MCPServerListError

internal

internal

Error message

Listing tools from MCP server {server_name!r} failed

What it means

Carrier error in the MCP server manager: a non-auth exception while listing an upstream MCP server's tools is wrapped as MCPServerListError so single-server routes relay the status and the aggregator absorbs the failure into a per-server outcome.

Source

Thrown at litellm/proxy/_experimental/mcp_server/mcp_server_manager.py:3537

                    server_name=upstream_auth_error.server_name,
                ) from upstream_auth_error
            raise
        except HTTPException as e:
            # A v2 resolver auth challenge (token_exchange's RFC 9728 401, authorization_code's
            # browser-OAuth 401, or a 403) is raised at client-build time, inside this try. Route it
            # through the same MCPUpstreamAuthError channel as pass-through so single-server routes
            # surface the challenge (the client re-authenticates) while the aggregator keeps absorbing.
            # Non-auth HTTP errors stay absorbed so one misconfigured server can't blank the listing.
            if e.status_code in (401, 403):
                headers: Final = e.headers or {}
                challenge_header: Final = headers.get("WWW-Authenticate") or headers.get("www-authenticate")
                raise MCPUpstreamAuthError(
                    status_code=e.status_code,
                    www_authenticate=None if server.is_dcr_bridge else challenge_header,
                    server_name=server.name,
                ) from e
            verbose_logger.warning("Failed to get tools from server %s: %s", server.name, e)
            raise MCPServerListError(ServerListFault(tag="internal", status_code=e.status_code), server.name) from e
        except MCPServerListError:
            raise
        except Exception as e:
            verbose_logger.warning("Failed to get tools from server %s: %s", server.name, e)
            raise_classified_list_failure(e, server.name, suppress_challenge=server.is_dcr_bridge)

    async def get_prompts_from_server(
        self,
        server: MCPServer,
        mcp_auth_header: str | dict[str, str] | None = None,
        extra_headers: dict[str, str] | None = None,
        add_prefix: bool = True,
        raw_headers: dict[str, str] | None = None,
    ) -> list[Prompt]:
        """
        Helper method to get prompts from a single MCP server with prefixed names.

        Args:

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Check upstream server reachability and credentials; see logs for the root cause.

Example fix

Run the admin connection test for that server.

When it happens

Trigger: Thrown at litellm/proxy/_experimental/mcp_server/mcp_server_manager.py:3537 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/ea9bb9d720099f46. Report an issue: GitHub.