BerriAI/litellm · error · HTTPException

MCP Server with id {payload.server_id} is special and cannot

Error message

MCP Server with id {payload.server_id} is special and cannot be used.

What it means

Returned (400) by the create MCP server endpoint when payload.server_id equals one of the reserved pseudo-ids SpecialMCPServerName.all_team_servers or SpecialMCPServerName.all_proxy_servers. These names are wildcard selectors used elsewhere (e.g. granting 'all servers of a team'), so they can never be a concrete server's id; the guard blocks them before the duplicate-id check.

Source

Thrown at litellm/proxy/management_endpoints/mcp_management_endpoints.py:1555

        # Validate and normalize payload fields
        validate_and_normalize_mcp_server_payload(payload)
        stamp_omitted_oauth2_flow(payload)

        # AuthZ - restrict only proxy admins to create mcp servers
        if LitellmUserRoles.PROXY_ADMIN != user_api_key_dict.user_role:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail={
                    "error": "User does not have permission to create mcp servers. You can only create mcp servers if you are a PROXY_ADMIN."
                },
            )

        # Block reserved special server IDs
        if (
            SpecialMCPServerName.all_team_servers == payload.server_id
            or SpecialMCPServerName.all_proxy_servers == payload.server_id
        ):
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST,
                detail={"error": f"MCP Server with id {payload.server_id} is special and cannot be used."},
            )

        if payload.server_id is not None:
            # fail if the mcp server with id already exists
            mcp_server: Final = await get_mcp_server(prisma_client, payload.server_id)
            if mcp_server is not None:
                raise HTTPException(
                    status_code=status.HTTP_400_BAD_REQUEST,
                    detail={"error": f"MCP Server with id {payload.server_id} already exists. Cannot create another."},
                )

        # TODO: audit log for create

        # Admin-created servers are always active — clear any submission lifecycle
        # fields the caller may have provided to prevent fake entries appearing in
        # the submissions queue.

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Choose a concrete, unique server_id (or omit server_id so one is generated) for the new server.
2. Filter the two reserved wildcard names out of any automation that derives server ids from grants or lists.
3. Use the wildcard only where a grant/list expects it, never in the create payload.

Example fix

# before
payload = {"server_id": "all-team-servers", "server_name": "my-server", ...}

# after
payload = {"server_id": "my-server-1", "server_name": "my-server", ...}

RESERVED = {"all-team-servers", "all-proxy-servers"}
assert payload.get("server_id") not in RESERVED

def is_creatable_server_id(server_id: str | None) -> bool:
    """True when the id is usable for create (not a reserved wildcard)."""
    return server_id is not None and server_id not in {"all-team-servers", "all-proxy-servers"}

try:
    create_server(payload)
except HTTPError as e:
    if e.response.status_code == 400 and "special" in e.response.text:
        payload["server_id"] = f"{payload['server_name']}-{uuid4().hex[:6]}"  # regenerate and retry
        create_server(payload)
    else:
        raise

When it happens

Trigger: POST create with server_id set to the all-team-servers or all-proxy-servers wildcard value (e.g. copying it from a team's allowed-servers list); UI or tooling auto-filling server_id from a wildcard grant entry.

Common situations: Copying an allowed_mcp_servers wildcard entry ('all-team-servers') as the id of a new server; migration scripts that iterate existing grants and try to re-create servers from them.

Related errors

• This MCP server does not support BYOK credentials
• max_budget cannot be negative. Received: {data.max_budget}
• soft_budget cannot be negative. Received: {data.soft_budget}
• soft_budget ({data.soft_budget}) must be strictly lower than
• Model '{m}' not in team's allowed models. Team allowed model

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