BerriAI/litellm · error · MCPServerListError

unreachable

unreachable

Error message

Listing tools from MCP server {server_name!r} failed

What it means

Logged and re-raised wrapped in MCPServerListError when client.list_tools() on an MCP server raises anything other than a timeout (timeouts get their own 'timeout' ServerListFault). This is a generic catch-all for transport/protocol failures — connection reset, malformed JSON-RPC response, server closing the stream — while listing a registered MCP server's tools; the original exception is preserved as __cause__.

Source

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

            server_name: Name of the server for logging

        Returns:
            List of tools from the server
        """
        try:
            with anyio.fail_after(MCP_TOOL_LISTING_TIMEOUT):
                tools: Final = await client.list_tools(raise_on_error=True)
                verbose_logger.debug("Tools from %s: %s", server_name, tools)
                return tools
        except TimeoutError as e:
            verbose_logger.warning("Timeout while listing tools from %s", server_name)
            raise MCPServerListError(ServerListFault(tag="timeout"), server_name) from e
        except asyncio.CancelledError as e:
            verbose_logger.warning("Task cancelled while listing tools from %s", server_name)
            raise MCPServerListError(ServerListFault(tag="internal"), server_name) from e
        except ConnectionError as e:
            verbose_logger.warning("Connection error while listing tools from %s: %s", server_name, e)
            raise MCPServerListError(ServerListFault(tag="unreachable"), server_name) from e
        except Exception as e:
            verbose_logger.warning("Error listing tools from %s: %s", server_name, e)
            raise_classified_list_failure(e, server_name)

    _SHORT_PREFIX_MAX_REHASH_ATTEMPTS = 1024

    def _assign_unique_short_prefix(
        self,
        server: MCPServer,
        registry: dict[str, MCPServer] | None = None,
    ) -> None:
        """Resolve and cache a collision-free short tool prefix on ``server``.

        Called at registration time for every MCP server entering the
        registry.  Mutates ``server.short_prefix`` in place.  No-ops when
        ``LITELLM_USE_SHORT_MCP_TOOL_PREFIX`` is disabled, when the server
        has no ``server_id`` (synthetic temp-server objects), or when a
        prefix is already cached.

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:4276 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/70f2a61e602a7532. Report an issue: GitHub.