BerriAI/litellm · warning · HTTPException

MCP server for tool '{name}' is not available; refusing to d

Error message

MCP server for tool '{name}' is not available; refusing to dispatch without authorization checks. Retry once the server is registered.

What it means

Tools generated from OpenAPI specs live in a local registry but must pass the same pre_call_tool_check as managed tools (allowed/banned-tool lists, key/team tool permissions, parameter validation). Those checks need the owning server; if the tool is in the registry but its server cannot be resolved, LiteLLM refuses dispatch with HTTP 503 instead of skipping authorization. The source comment notes this keeps an earlier auth-bypass gap closed: a missing mapping means initialization has not finished or the entry is orphaned.

Source

Thrown at litellm/proxy/_experimental/mcp_server/server.py:2802

                # External auth header supplied; still enforce user-identity check.
                await _check_byok_credential(mcp_server, user_api_key_auth)

        # Check if tool exists in local registry first (for OpenAPI-based tools)
        # These tools are registered with their prefixed names
        #########################################################
        local_tool: Final = global_mcp_tool_registry.get_tool(name)
        if local_tool:
            # OpenAPI-backed tools used to bypass `pre_call_tool_check` —
            # only the managed path ran allowed/banned-tool checks, key/team
            # tool permissions, and parameter validation. Run the same checks
            # before dispatching to the local registry. Refuse the call if
            # we cannot resolve a server: tools registered via
            # openapi_to_mcp_generator are always tied to a server, so a
            # missing mcp_server here means the tool->server mapping has
            # not finished initializing or the registry entry is orphaned.
            # Skipping the check would re-open the same authorization gap.
            if mcp_server is None:
                raise HTTPException(
                    status_code=503,
                    detail=(
                        f"MCP server for tool '{name}' is not available; "
                        "refusing to dispatch without authorization checks. "
                        "Retry once the server is registered."
                    ),
                )

            # `pre_call_tool_check` calls into `proxy_logging_obj` for the
            # pre-call guardrail hooks, so source it from the canonical
            # `proxy_server` module the same way `_handle_managed_mcp_tool`
            # does. `kwargs.get("proxy_logging_obj")` is None on the MCP
            # entry path and would crash with AttributeError after the
            # security checks pass.
            from litellm.proxy.proxy_server import proxy_logging_obj

            hook_result = await global_mcp_server_manager.pre_call_tool_check(
                name=original_tool_name,

View on GitHub (pinned to 77b7c6c40c)

Solutions

Retry the call once the server registration completes — the message explicitly says this.
If it persists, restart the proxy or re-add the MCP server so the tool-to-server mapping rebuilds.
If the server was intentionally deleted, remove the orphaned tool entry so clients stop discovering it.

Defensive patterns

Strategy: retry

Validate before calling

async def tool_server_ready(client: httpx.AsyncClient, tool_name: str) -> bool:
    tools = (await client.get(f"{base}/mcp-rest/tools/list")).json().get("tools", [])
    return any(t.get("name") == tool_name for t in tools)

Try / catch

async def call_with_backoff(call, payload, attempts: int = 5):
    for i in range(attempts):
        try:
            return await call(payload)
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 503 and "refusing to dispatch" in e.response.text:
                await asyncio.sleep(min(2 ** i, 10))  # registration race; settles shortly
                continue
            raise
    raise

Prevention

Gate client traffic on a post-startup readiness check after proxy restarts or MCP config reloads.
Do not call OpenAPI-generated tools until the owning server's registration completes — check the tool listing first.
Clean up orphaned tools when deleting a server so clients stop discovering dead entries.

When it happens

Trigger: A tool call racing server registration during proxy startup or config reload; an orphaned registry entry left behind after its server was removed from the registry.

Common situations: Clients reconnecting immediately after a proxy restart; hot-reloading MCP config while traffic flows; a partially failed server registration.

Related errors

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