BerriAI/litellm · error · HTTPException

Server name cannot contain '{MCP_TOOL_PREFIX_SEPARATOR}'. Us

Error message

Server name cannot contain '{MCP_TOOL_PREFIX_SEPARATOR}'. Use an alternative character instead Found: {server_name}

What it means

validate_mcp_server_name rejects names containing MCP_TOOL_PREFIX_SEPARATOR ('/') because the separator is how tool names are prefixed per server; allowing it would make prefixed tool names ambiguous. Raised as Exception or HTTPException depending on the flag.

Source

Thrown at litellm/proxy/_experimental/mcp_server/utils.py:502

def validate_mcp_server_name(server_name: str, raise_http_exception: bool = False) -> None:
    """
    Validate that MCP server name does not contain 'MCP_TOOL_PREFIX_SEPARATOR'.

    Args:
        server_name: The server name to validate
        raise_http_exception: If True, raises HTTPException instead of generic Exception

    Raises:
        Exception or HTTPException: If server name contains 'MCP_TOOL_PREFIX_SEPARATOR'
    """
    if server_name and MCP_TOOL_PREFIX_SEPARATOR in server_name:
        error_message = f"Server name cannot contain '{MCP_TOOL_PREFIX_SEPARATOR}'. Use an alternative character instead Found: {server_name}"
        if raise_http_exception:
            from fastapi import HTTPException
            from starlette import status

            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail={"error": error_message})
        else:
            raise Exception(error_message)


def extract_mcp_tool_result_error_message(result: object) -> str | None:
    """The first text content of an ``isError=True`` tool result, or ``None``
    when the result is not an error.

    Accepts both ``mcp.types.CallToolResult`` objects and their dict
    equivalents, duck-typed so the ``mcp`` package is not required.
    """
    is_error: Final[object] = result.get("isError") if isinstance(result, Mapping) else getattr(result, "isError", None)
    if is_error is not True:
        return None
    content: Final[object] = result.get("content") if isinstance(result, Mapping) else getattr(result, "content", None)
    if isinstance(content, (list, tuple)):
        for item in content:
            text: object = item.get("text") if isinstance(item, Mapping) else getattr(item, "text", None)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Rename the MCP server to remove the prefix separator character.

Example fix

Use letters/digits/underscores in the server name.

When it happens

Trigger: Thrown at litellm/proxy/_experimental/mcp_server/utils.py:502 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/bc30ef25b9bafbcc. Report an issue: GitHub.