BerriAI/litellm · error · HTTPException

missing_user_env_vars

missing_user_env_vars

Error message

Cannot connect to MCP server "{label}".\n\nYour administrator configured this server to require per-user variables, but you haven't set the following yet:\n{bullet_list}\n\nSet your credentials here:\n{setup_url}

What it means

An administrator can register an MCP server with per-user variables (an env-var template each user must fill with their own credentials). When the calling user has no values stored, the tool call raises MCPMissingUserEnvVarsError, which this handler converts to HTTP 412 with error code missing_user_env_vars. The response includes server_id, server_name, the list of missing variables, and a setup_url pointing at the page where the user sets them.

Source

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

                raw_headers=data.get("raw_headers"),
                litellm_logging_obj=data.get("litellm_logging_obj"),
                requested_server_id=canonical_server_id,
            )
            return await _safe_fire_mcp_tool_call_logging(
                logging_obj,
                result,
                _tool_start_time,
                datetime.now(),
                user_api_key_auth=user_api_key_dict,
                request_data=data,
            )
        except MCPMissingUserEnvVarsError as e:
            verbose_logger.info(
                "MCP tool call missing per-user env vars: server_id=%s missing=%s",
                e.server_id,
                e.missing,
            )
            raise HTTPException(
                status_code=412,
                detail={
                    "error": "missing_user_env_vars",
                    "message": str(e),
                    "server_id": e.server_id,
                    "server_name": e.server_name,
                    "missing": e.missing,
                    "setup_url": e.setup_url,
                },
            )
        except BlockedPiiEntityError as e:
            verbose_logger.error("BlockedPiiEntityError in MCP tool call: %s", e)
            raise HTTPException(
                status_code=400,
                detail={
                    "error": "blocked_pii_entity",
                    "message": str(e),
                    "entity_type": getattr(e, "entity_type", None),

View on GitHub (pinned to 77b7c6c40c)

Solutions

Open the setup_url from the error response and set the listed variables for your user.
Submit values for every entry in detail.missing (typically the API key/token the upstream server needs), then retry the call.
If per-user credentials are not wanted, have the admin replace the per-user env-var template with a static server credential.

Defensive patterns

Strategy: try-catch

Try / catch

try:
    resp = await client.post(f"{base}/mcp-rest/tools/call", json=payload)
    resp.raise_for_status()
except httpx.HTTPStatusError as e:
    if e.response.status_code == 412:
        d = e.response.json().get("detail", {})
        if d.get("error") == "missing_user_env_vars":
            # route the user to the setup page, then allow a retry
            send_user_notice(setup_url=d.get("setup_url"), missing=d.get("missing", []))
            return
    raise

Prevention

On each user's first call to a per-user-variable server, catch 412 and route them to setup_url before retrying.
Admins: document which per-user variables a server needs before granting users access.

When it happens

Trigger: Any MCP tool call (POST /mcp-rest/tools/call or the /mcp session endpoint) against a server whose configuration declares per-user env vars, made by a user who never filled them in.

Common situations: New team members calling a shared MCP server for the first time; an admin adds per-user variables to a previously open server and existing callers start failing; fresh environments where the user-env store is empty.

Related errors

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