BerriAI/litellm · error · HTTPException

User does not have permission to test MCP server connections

Error message

User does not have permission to test MCP server connections. Only PROXY_ADMIN users can perform this action.

What it means

POST /mcp-rest/test/connection lets an admin pre-flight connectivity to an MCP server before registering it. Because it makes the proxy connect to arbitrary hosts, it is restricted: any caller whose user_api_key_dict.user_role is not PROXY_ADMIN gets HTTP 403 with this message.

Source

Thrown at litellm/proxy/_experimental/mcp_server/rest_endpoints.py:1326

        except Exception as e:
            verbose_logger.error("Error previewing OpenAPI tools: %s", e, exc_info=True)
            return {
                "tools": [],
                "error": True,
                "message": f"Failed to load OpenAPI spec: {e}",
            }

    @router.post("/test/connection", dependencies=[Depends(user_api_key_auth)])
    async def test_connection(
        request: Request,
        new_mcp_server_request: NewMCPServerRequest,
        user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
    ):
        """
        Test if we can connect to the provided MCP server before adding it
        """
        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 test MCP server connections. Only PROXY_ADMIN users can perform this action."
                },
            )

        async def _test_connection_operation(client):
            async def _noop(session):
                return "ok"

            await client.run_with_session(_noop)
            return {"status": "ok"}

        return await _execute_with_mcp_client(
            new_mcp_server_request,
            _test_connection_operation,
            raw_headers=_safe_get_request_headers(request),
        )

View on GitHub (pinned to 77b7c6c40c)

Solutions

Call the endpoint with a key whose user has the PROXY_ADMIN role.
Grant PROXY_ADMIN to the intended user in the admin UI (Internal Users → edit → role) and retry.
If non-admin onboarding must be supported, expose your own wrapper endpoint that runs with an admin service account.

Defensive patterns

Strategy: validation

Validate before calling

async def can_test_connections(client: httpx.AsyncClient) -> bool:
    info = (await client.get(f"{base}/key/info")).json()
    return info.get("key_info", {}).get("user_role") == "proxy_admin"

Type guard

def is_proxy_admin_key(key_info: dict) -> bool:
    return key_info.get("user_role") == "proxy_admin"

Try / catch

except httpx.HTTPStatusError as e:
    if e.response.status_code == 403 and "PROXY_ADMIN" in e.response.text:
        raise PermissionError("test/connection requires a PROXY_ADMIN key") from e
    raise

Prevention

Check /key/info for user_role == proxy_admin before calling admin-only MCP test endpoints.
Keep a dedicated admin key for onboarding scripts; never reuse team keys for these calls.

When it happens

Trigger: Calling POST /mcp-rest/test/connection with an internal-user, team, or external-tester virtual key; scripts or CI smoke tests that use a non-admin key against this endpoint.

Common situations: Teams automating MCP server onboarding with their own keys; dashboards calling the endpoint on behalf of non-admin users; service accounts created for testing.

Related errors

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