From 5ae6c825054dbc1cf600b64cc5b8d3d549323f11 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 26 May 2026 17:58:32 -0700
Subject: [PATCH] fix(mcp): friendlier missing-per-user-env-vars error message
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reword MCPMissingUserEnvVarsError so the user-facing message reads more
naturally — leads with "Cannot connect to MCP server …", explains the
admin requirement, lists the missing variables as bullets, and points
at the setup URL on its own line.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 litellm/proxy/_experimental/mcp_server/utils.py    | 12 +++++++-----
 .../_experimental/mcp_server/test_mcp_env_vars.py  | 14 +++++++-------
 2 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/utils.py b/litellm/proxy/_experimental/mcp_server/utils.py
index b44ecd54bf1..363748ea774 100644
--- a/litellm/proxy/_experimental/mcp_server/utils.py
+++ b/litellm/proxy/_experimental/mcp_server/utils.py
@@ -371,12 +371,14 @@ class MCPMissingUserEnvVarsError(Exception):
         self.missing = missing
         self.setup_url = setup_url
         label = server_name or server_id
-        vars_list = ", ".join(missing)
+        bullet_list = "\n".join(f"- {name}" for name in missing)
         message = (
-            f"MCP server '{label}' is missing the following per-user environment "
-            f"variable{'s' if len(missing) != 1 else ''} that you need to fill in "
-            f"before this server can be used: {vars_list}.\n\n"
-            f"Go to {setup_url} to set them, then try again."
+            f'Cannot connect to MCP server "{label}".\n\n'
+            f"Your administrator configured this server to require per-user "
+            f"variables, but you haven't set the following yet:\n"
+            f"{bullet_list}\n\n"
+            f"Set your credentials here:\n"
+            f"{setup_url}"
         )
         super().__init__(message)
 
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_env_vars.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_env_vars.py
index 38c8bef34dc..2316f609fb0 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_env_vars.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_env_vars.py
@@ -116,15 +116,16 @@ def test_missing_user_env_vars_error_message_is_friendly():
         )
     err = exc_info.value
     text = str(err)
-    assert "CorporateDB" in text
-    assert "CORP_USERNAME" in text
-    assert "CORP_PASSWORD" in text
+    assert 'Cannot connect to MCP server "CorporateDB".' in text
+    assert "- CORP_USERNAME" in text
+    assert "- CORP_PASSWORD" in text
     assert "fill_env_vars=abc-123" in text
+    assert "Set your credentials here:" in text
     assert err.server_id == "abc-123"
     assert err.missing == ["CORP_USERNAME", "CORP_PASSWORD"]
 
 
-def test_missing_user_env_vars_error_singular_message():
+def test_missing_user_env_vars_error_falls_back_to_server_id():
     err = _u("MCPMissingUserEnvVarsError")(
         server_id="abc",
         server_name=None,
@@ -132,10 +133,9 @@ def test_missing_user_env_vars_error_singular_message():
         setup_url="/ui/",
     )
     text = str(err)
-    # Singular "variable" rather than "variables" when only one is missing
-    assert "variable that you need to fill in" in text
     # Falls back to server_id when server_name is missing
-    assert "abc" in text
+    assert 'Cannot connect to MCP server "abc".' in text
+    assert "- X" in text
 
 
 # ── _resolve_static_headers_with_env_vars ────────────────────────────────