{"record":{"id":"6a477f9f2022525a","repo":"BerriAI/litellm","slug":"listing-tools-from-mcp-server-server-name-r-fail","errorCode":null,"errorMessage":"Listing tools from MCP server {server_name!r} failed","messagePattern":"Listing tools from MCP server (.+?) failed","errorType":"exception","errorClass":"MCPServerListError","httpStatus":null,"severity":"error","filePath":"litellm/proxy/_experimental/mcp_server/faults/list_outcomes.py","lineNumber":114,"sourceCode":"    exc: BaseException,\n    server_name: str,\n    suppress_challenge: bool = False,\n) -> NoReturn:\n    \"\"\"The one place a failed server fetch chooses its carrier: an upstream 401/403 travels as\n    ``MCPUpstreamAuthError`` with the upstream's own challenge preserved (a challenge is only ever\n    fabricated at the HTTP edge, and only for a 401), everything else as ``MCPServerListError`` with\n    a classified fault. Every fetch site delegates here so the two channels cannot drift apart per\n    call site. ``suppress_challenge`` is for dcr_bridge servers, whose upstream challenge points\n    clients at the wrong protected-resource metadata and must never relay.\"\"\"\n    auth: Final = upstream_auth_challenge(exc)\n    if auth is not None:\n        status_code, challenge = auth\n        raise MCPUpstreamAuthError(\n            status_code=status_code,\n            www_authenticate=None if suppress_challenge else challenge,\n            server_name=server_name,\n        ) from exc\n    raise MCPServerListError(classify_list_exception(exc), server_name) from exc\n\n\ndef classify_list_exception(exc: BaseException) -> ServerListFault:\n    \"\"\"Classify a per-server listing failure into exactly one outcome. Total: an exception this\n    function cannot recognize is the gateway's own fault (``internal``), never a re-raise.\"\"\"\n    if isinstance(exc, MCPServerListError) and isinstance(exc.fault, ServerListFault):\n        return exc.fault\n    if isinstance(exc, MCPUpstreamAuthError):\n        tag: Final = \"forbidden\" if exc.status_code == 403 else \"auth_required\"\n        return ServerListFault(tag=tag, status_code=exc.status_code)\n    if isinstance(exc, TimeoutError):\n        return ServerListFault(tag=\"timeout\")\n    if isinstance(exc, ConnectionError):\n        return ServerListFault(tag=\"unreachable\")\n    auth: Final = upstream_auth_challenge(exc)\n    if auth is not None:\n        status_code, _ = auth\n        return ServerListFault(","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/_experimental/mcp_server/faults/list_outcomes.py#L96-L132","documentation":"Carrier error raised by the shared MCP server-list failure router: listing tools from an upstream MCP server failed for a non-auth reason, classified into a ServerListFault; the server name identifies which upstream is at fault.","triggerScenarios":"Thrown at litellm/proxy/_experimental/mcp_server/faults/list_outcomes.py:114 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Check upstream server reachability and credentials.","See proxy logs for the underlying list-tools error."],"exampleFix":"Test the server connection via the admin test endpoint.","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}