BerriAI/litellm · error · HTTPException

PROXY_ADMIN users should use POST /v1/mcp/server to create s

Error message

PROXY_ADMIN users should use POST /v1/mcp/server to create servers directly instead of the submission workflow.

What it means

Workflow-direction guard on POST /v1/mcp/server/register: the submission workflow exists for non-admin users to propose servers for review. A PROXY_ADMIN called it; admins create servers directly via POST /v1/mcp/server, so routing them into the pending-review queue is rejected with 403.

Source

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

    @router.post(
        "/server/register",
        description="Submit a new MCP server for admin review (non-admin users). Mirrors POST /guardrails/register.",
        dependencies=[Depends(user_api_key_auth)],
        response_model=LiteLLM_MCPServerTable,
        status_code=status.HTTP_201_CREATED,
    )
    @management_endpoint_wrapper
    async def register_mcp_server(
        payload: NewMCPServerRequest,
        user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
    ):
        """
        Allow team members to submit an MCP server for admin review.
        Creates the server with approval_status=pending_review.
        Requires a team-scoped API key.
        """
        if user_api_key_dict.user_role == LitellmUserRoles.PROXY_ADMIN:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail={
                    "error": "PROXY_ADMIN users should use POST /v1/mcp/server to create servers directly instead of the submission workflow."
                },
            )

        if not user_api_key_dict.team_id:
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST,
                detail={"error": "Registration requires an API key associated with a team. Use a team-scoped key."},
            )

        # stdio servers spawn a local subprocess on the proxy host with the
        # configured command + args, so accepting them from non-admin callers
        # would let a team member propose a server config that an admin could
        # rubber-stamp into local code execution. Restrict stdio submission to
        # the admin POST /v1/mcp/server path or to config.yaml.
        if payload.transport == MCPTransport.stdio:

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Use POST /v1/mcp/server directly to create the server as a proxy admin.
2. Reserve the submission workflow for non-admin users.

When it happens

Trigger: Thrown at litellm/proxy/management_endpoints/mcp_management_endpoints.py:1239 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/23bcf40e58cd10e4. Report an issue: GitHub.