{"record":{"id":"2b1103aa4c5db2df","repo":"BerriAI/litellm","slug":"mcp-server-with-id-payload-server-id-is-special","errorCode":null,"errorMessage":"MCP Server with id {payload.server_id} is special and cannot be used.","messagePattern":"MCP Server with id (.+?) is special and cannot be used\\.","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"litellm/proxy/management_endpoints/mcp_management_endpoints.py","lineNumber":1555,"sourceCode":"        # Validate and normalize payload fields\n        validate_and_normalize_mcp_server_payload(payload)\n        stamp_omitted_oauth2_flow(payload)\n\n        # AuthZ - restrict only proxy admins to create mcp servers\n        if LitellmUserRoles.PROXY_ADMIN != user_api_key_dict.user_role:\n            raise HTTPException(\n                status_code=status.HTTP_403_FORBIDDEN,\n                detail={\n                    \"error\": \"User does not have permission to create mcp servers. You can only create mcp servers if you are a PROXY_ADMIN.\"\n                },\n            )\n\n        # Block reserved special server IDs\n        if (\n            SpecialMCPServerName.all_team_servers == payload.server_id\n            or SpecialMCPServerName.all_proxy_servers == payload.server_id\n        ):\n            raise HTTPException(\n                status_code=status.HTTP_400_BAD_REQUEST,\n                detail={\"error\": f\"MCP Server with id {payload.server_id} is special and cannot be used.\"},\n            )\n\n        if payload.server_id is not None:\n            # fail if the mcp server with id already exists\n            mcp_server: Final = await get_mcp_server(prisma_client, payload.server_id)\n            if mcp_server is not None:\n                raise HTTPException(\n                    status_code=status.HTTP_400_BAD_REQUEST,\n                    detail={\"error\": f\"MCP Server with id {payload.server_id} already exists. Cannot create another.\"},\n                )\n\n        # TODO: audit log for create\n\n        # Admin-created servers are always active — clear any submission lifecycle\n        # fields the caller may have provided to prevent fake entries appearing in\n        # the submissions queue.","sourceCodeStart":1537,"sourceCodeEnd":1573,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/management_endpoints/mcp_management_endpoints.py#L1537-L1573","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Choose a concrete, unique server_id (or omit server_id so one is generated) for the new server.","Filter the two reserved wildcard names out of any automation that derives server ids from grants or lists.","Use the wildcard only where a grant/list expects it, never in the create payload."],"exampleFix":"# before\npayload = {\"server_id\": \"all-team-servers\", \"server_name\": \"my-server\", ...}\n\n# after\npayload = {\"server_id\": \"my-server-1\", \"server_name\": \"my-server\", ...}","handlingStrategy":"type-guard","validationCode":"RESERVED = {\"all-team-servers\", \"all-proxy-servers\"}\nassert payload.get(\"server_id\") not in RESERVED","typeGuard":"def is_creatable_server_id(server_id: str | None) -> bool:\n    \"\"\"True when the id is usable for create (not a reserved wildcard).\"\"\"\n    return server_id is not None and server_id not in {\"all-team-servers\", \"all-proxy-servers\"}","tryCatchPattern":"try:\n    create_server(payload)\nexcept HTTPError as e:\n    if e.response.status_code == 400 and \"special\" in e.response.text:\n        payload[\"server_id\"] = f\"{payload['server_name']}-{uuid4().hex[:6]}\"  # regenerate and retry\n        create_server(payload)\n    else:\n        raise","preventionTips":["Filter the two wildcard names out of any automation deriving ids from grants.","Generate unique concrete ids instead of copying values from allowed-server lists."],"tags":["litellm","mcp","reserved-id","validation"],"backgroundTag":"reserved-identifier","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}