Skip to content
Merged
Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
81 commits
Select commit Hold shift + click to select a range
e58a561
Merge pull request #27906 from BerriAI/litellm_internal_staging
shin-berri May 14, 2026
a72414a
Merge pull request #28100 from BerriAI/litellm_internal_staging
yuneng-berri May 17, 2026
79b4578
Merge pull request #28292 from BerriAI/litellm_internal_staging
yuneng-berri May 19, 2026
48a6334
feat(mcp): per-server env vars with global + per-user scopes
claude May 20, 2026
accecaf
test(mcp): add DB layer + load-user-env-vars coverage
claude May 20, 2026
35f6961
Merge pull request #28680 from BerriAI/litellm_internal_staging
yuneng-berri May 23, 2026
06f6cfc
Merge pull request #28709 from BerriAI/litellm_internal_staging
yuneng-berri May 23, 2026
28883ea
feat(mcp/ui): match env-vars UI to card-grid design from #28399
claude May 24, 2026
855cf82
test(mcp): cover per-user env-var management endpoints
claude May 24, 2026
719d562
fix(mcp): don't block tool listing on missing per-user env vars
claude May 24, 2026
1db27bd
Merge remote-tracking branch 'origin/patch/v1.87.0-rc.1' into litellm…
mateo-berri May 27, 2026
d042da1
style(mcp/ui): give env-vars section its production look
mateo-berri May 27, 2026
5ae6c82
fix(mcp): friendlier missing-per-user-env-vars error message
mateo-berri May 27, 2026
8fca9d7
chore: rename htmls
mateo-berri May 27, 2026
af63258
Merge branch 'litellm_internal_staging' into litellm_mcp_server_env_vars
mateo-berri Jun 3, 2026
48e8f40
fix(mcp): load DB-stored servers whose env_vars hydrate as MCPEnvVar …
cursoragent Jun 3, 2026
ef341b8
fix(mcp/ui): scope create-server e2e assertion to the new card grid
mateo-berri Jun 3, 2026
7d11dd7
style(mcp): black-format the env-vars deserialization regression test
cursoragent Jun 3, 2026
d781b62
fix(mcp): surface DB errors on tool-call path and redact global env v…
mateo-berri Jun 3, 2026
9764f54
fix(mcp): gate per-user env-var endpoints by server access
mateo-berri Jun 3, 2026
b38320d
fix(mcp): propagate delete DB errors; drop redundant import and dupli…
mateo-berri Jun 3, 2026
26f15b4
fix(mcp): stop echoing credential values in bulk env-var status and l…
mateo-berri Jun 3, 2026
dbc5193
style(mcp/ui): hoist MCPUserEnvVarsStatus import to top of networking…
mateo-berri Jun 3, 2026
3392cd0
fix(mcp): URL-encode server_id in env-var setup deep link
mateo-berri Jun 3, 2026
e030c24
Merge branch 'litellm_internal_staging' into litellm_mcp_server_env_vars
mateo-berri Jun 3, 2026
236407a
fix(mcp): wrap get_mcp_server result in LiteLLM_MCPServerTable
mateo-berri Jun 3, 2026
102b73a
fix(mcp): redact global env var secrets from read-only admin server v…
mateo-berri Jun 3, 2026
1f1bf4c
fix(mcp): surface env-var fetch errors and authorize before existence…
mateo-berri Jun 3, 2026
e9eeca1
fix(mcp): make per-user env var status write-only
mateo-berri Jun 3, 2026
0dcf316
fix(mcp/ui): clear value for user-scope env vars before submit
mateo-berri Jun 3, 2026
ba20078
fix(mcp): keep a created MCP server when post-write registry refresh …
mateo-berri Jun 3, 2026
8852c0d
fix(mcp): preserve env_vars in registry to table conversion
mateo-berri Jun 4, 2026
ba7cab2
fix(mcp/ui): clarify per-user env var field as a hint, not a value
mateo-berri Jun 4, 2026
e33ec2e
fix(mcp/ui): rename env vars section to Variables
mateo-berri Jun 4, 2026
8581460
fix(mcp): redact global env var secrets from read-only admin submissi…
mateo-berri Jun 4, 2026
cc6e6de
fix(mcp): convert registry env_vars to MCPEnvVar when building server…
mateo-berri Jun 4, 2026
61962af
fix(mcp): scope per-user env var overrides to currently user-scoped vars
mateo-berri Jun 4, 2026
3b1a90e
fix(mcp): encrypt global env var secrets at rest
mateo-berri Jun 4, 2026
21c7c38
fix(mcp): extract env var resolution to satisfy ruff PLR0915
mateo-berri Jun 4, 2026
4b31a6d
perf(mcp): cache per-user env var values off the hot tool-call path
mateo-berri Jun 4, 2026
ca1e837
fix(mcp): delete per-user env vars with their server and document POS…
mateo-berri Jun 4, 2026
c9cc963
refactor(mcp/ui): share normalizeEnvVars helper between create and ed…
mateo-berri Jun 4, 2026
018df7f
perf(mcp): evict oldest per-user env var cache entry instead of clear…
mateo-berri Jun 4, 2026
3527827
fix(mcp): interpolate global env vars before upstream health probes
mateo-berri Jun 4, 2026
30b0502
fix(mcp): re-check DB before raising missing-env-var 412 and correct …
mateo-berri Jun 4, 2026
f08bc13
perf(mcp): index server_id on LiteLLM_MCPUserEnvVars for orphan cleanup
mateo-berri Jun 4, 2026
de72a84
fix(mcp): drop undecryptable global env vars and merge per-user env v…
mateo-berri Jun 4, 2026
19a3cfa
fix(mcp): log best-effort user env var load failures at warning
mateo-berri Jun 4, 2026
ad07d14
Merge remote-tracking branch 'origin/litellm_internal_staging' into l…
mateo-berri Jun 4, 2026
4576c48
fix(mcp): don't re-decrypt already-decrypted global env vars in regis…
mateo-berri Jun 4, 2026
77ddd83
fix(mcp): serialize env_vars from data_dict and document reload decry…
mateo-berri Jun 4, 2026
43394c1
fix(mcp): rotate new encrypted env var columns on master-key rotation
mateo-berri Jun 4, 2026
86cf341
fix(mcp): redact global env var secrets from management telemetry
mateo-berri Jun 4, 2026
4cbf8ca
fix(mcp): drop env vars entirely for virtual keys and reuse access lo…
mateo-berri Jun 4, 2026
fe20b4b
Merge remote-tracking branch 'origin/litellm_internal_staging' into l…
mateo-berri Jun 4, 2026
63a9f00
chore(ui): satisfy frontend-lint gate on touched MCP files
mateo-berri Jun 4, 2026
3ac1c00
fix(mcp): surface DB-unavailable as a real error on per-user env var …
mateo-berri Jun 4, 2026
67e81f7
fix(ui): move MCP env-var loading to React Query to drop lint suppres…
mateo-berri Jun 4, 2026
2e94852
fix(mcp): make per-user env var cleanup best-effort on server delete
mateo-berri Jun 4, 2026
3f62063
fix(mcp): skip health check for servers with per-user env-var headers
mateo-berri Jun 4, 2026
2fb11f1
test(core-utils): skip token_counter custom-tokenizer assertion when …
mateo-berri Jun 4, 2026
2da1e5e
fix(mcp): use global fallback before raising missing per-user env var…
mateo-berri Jun 4, 2026
178af17
fix(mcp): drop env vars entirely for non-admin server views
mateo-berri Jun 4, 2026
47fa6ff
Merge branch 'litellm_internal_staging' into litellm_mcp_server_env_vars
mateo-berri Jun 4, 2026
113f6d8
Merge remote-tracking branch 'origin/litellm_internal_staging' into l…
mateo-berri Jun 4, 2026
ae026d2
fix(mcp): serialize per-user env var merge to avoid lost concurrent u…
mateo-berri Jun 4, 2026
16f1d3e
fix(mcp): warn on undecryptable per-user env vars and align status wi…
mateo-berri Jun 4, 2026
3f61004
fix(mcp): compute per-user env var lock key without hashtextextended
mateo-berri Jun 4, 2026
16bc527
Merge remote-tracking branch 'origin/litellm_internal_staging' into l…
mateo-berri Jun 4, 2026
82e69ed
mcp: decrypt env_vars on Prisma create/update rows that return JSON s…
cursoragent Jun 4, 2026
eaab1c5
fix(mcp): redact nested env_vars in submissions telemetry response
mateo-berri Jun 5, 2026
298a3ca
refactor(mcp): drop unused store_user_env_vars helper
mateo-berri Jun 5, 2026
201f40f
Merge branch 'litellm_internal_staging' into litellm_mcp_server_env_vars
mateo-berri Jun 5, 2026
faca397
Merge remote-tracking branch 'origin/litellm_internal_staging' into l…
mateo-berri Jun 5, 2026
4d7f160
chore(mcp): log master-key rotation summary counts
mateo-berri Jun 5, 2026
4929f50
refactor(ui): route MCP env-var calls through shared http client
mateo-berri Jun 5, 2026
5177f8f
fix(mcp): acquire user env-var advisory lock via execute_raw
mateo-berri Jun 5, 2026
aa78a90
Merge remote-tracking branch 'origin/litellm_internal_staging' into l…
mateo-berri Jun 5, 2026
0234405
fix(mcp): treat empty-valued global env var as unset in header resolu…
mateo-berri Jun 5, 2026
587829c
fix(mcp): trim static header whitespace and surface real connection e…
mateo-berri Jun 5, 2026
7570cc6
fix(mcp): treat empty global as unset in user env-var status too
mateo-berri Jun 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
-- AlterTable: add admin-configured env_vars to MCP server table
ALTER TABLE "LiteLLM_MCPServerTable" ADD COLUMN IF NOT EXISTS "env_vars" JSONB DEFAULT '[]';

-- CreateTable: per-user env var values for MCP servers
CREATE TABLE IF NOT EXISTS "LiteLLM_MCPUserEnvVars" (
"id" TEXT NOT NULL,
"user_id" TEXT NOT NULL,
"server_id" TEXT NOT NULL,
"values_b64" TEXT NOT NULL,
"created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,

CONSTRAINT "LiteLLM_MCPUserEnvVars_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE UNIQUE INDEX IF NOT EXISTS "LiteLLM_MCPUserEnvVars_user_id_server_id_key" ON "LiteLLM_MCPUserEnvVars"("user_id", "server_id");

-- CreateIndex
CREATE INDEX IF NOT EXISTS "LiteLLM_MCPUserEnvVars_user_id_idx" ON "LiteLLM_MCPUserEnvVars"("user_id");
19 changes: 19 additions & 0 deletions litellm-proxy-extras/litellm_proxy_extras/schema.prisma
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,11 @@ model LiteLLM_MCPServerTable {
tool_name_to_description Json? @default("{}")
extra_headers String[] @default([])
static_headers Json? @default("{}")
// Admin-configured environment variables interpolated into static_headers
// (and the URL) via ${NAME} syntax. Stored as an array of
// {name, value, scope, description}. scope is "global" (value used as-is)
// or "user" (value supplied per-user via LiteLLM_MCPUserEnvVars).
env_vars Json? @default("[]")
// Health check status
status String? @default("unknown")
last_health_check DateTime?
Expand Down Expand Up @@ -364,6 +369,20 @@ model LiteLLM_MCPUserCredentials {
@@unique([user_id, server_id])
}

// Per-user environment variable values for MCP servers.
// values_b64 is an encrypted JSON object: {VAR_NAME: "value", ...}.
model LiteLLM_MCPUserEnvVars {
id String @id @default(uuid())
user_id String
server_id String
values_b64 String
created_at DateTime @default(now())
updated_at DateTime @default(now()) @updatedAt

@@unique([user_id, server_id])
@@index([user_id])
}

// Generate Tokens for Proxy
model LiteLLM_VerificationToken {
token String @id
Expand Down
97 changes: 97 additions & 0 deletions litellm/proxy/_experimental/mcp_server/db.py
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,14 @@ def _prepare_mcp_server_data(
if data_dict.get("static_headers") is not None:
data_dict["static_headers"] = safe_dumps(data_dict["static_headers"])

# Handle env_vars serialization. Pydantic models are dumped to a list of
# plain dicts so the JSON column receives ``[{name, value, scope, ...}]``.
env_vars = getattr(data, "env_vars", None)
if env_vars is not None:
data_dict["env_vars"] = safe_dumps(
Comment thread
veria-ai[bot] marked this conversation as resolved.
Resolved
[v.model_dump() if hasattr(v, "model_dump") else dict(v) for v in env_vars]
)

if data_dict.get("mcp_info") is not None:
data_dict["mcp_info"] = safe_dumps(data_dict["mcp_info"])

Expand Down Expand Up @@ -980,3 +988,92 @@ async def get_mcp_submissions(
rejected=rejected,
items=items,
)


# ── Per-user MCP environment variables ────────────────────────────────────


async def store_user_env_vars(
prisma_client: PrismaClient,
user_id: str,
server_id: str,
values: Dict[str, str],
) -> None:
"""Persist (or overwrite) the calling user's env var values for ``server_id``.

Values are JSON-serialised and stored encrypted in ``values_b64``.
"""
encoded = encrypt_value_helper(json.dumps(values))
await prisma_client.db.litellm_mcpuserenvvars.upsert(
where={"user_id_server_id": {"user_id": user_id, "server_id": server_id}},
data={
"create": {
"user_id": user_id,
"server_id": server_id,
"values_b64": encoded,
},
"update": {"values_b64": encoded},
},
)


def _decode_user_env_vars(stored: str) -> Dict[str, str]:
"""Decrypt a ``values_b64`` blob and parse it as a flat ``{name: value}`` dict."""
decrypted = decrypt_value_helper(
value=stored,
key="mcp_user_env_vars",
exception_type="debug",
return_original_value=False,
)
if decrypted is None:
return {}
try:
parsed = json.loads(decrypted)
except (ValueError, TypeError):
return {}
if not isinstance(parsed, dict):
return {}
return {str(k): str(v) for k, v in parsed.items()}


async def get_user_env_vars(
prisma_client: PrismaClient,
user_id: str,
server_id: str,
) -> Dict[str, str]:
"""Return the calling user's env var dict for ``server_id`` (empty if none)."""
row = await prisma_client.db.litellm_mcpuserenvvars.find_unique(
where={"user_id_server_id": {"user_id": user_id, "server_id": server_id}}
)
if row is None:
return {}
return _decode_user_env_vars(row.values_b64)


async def get_user_env_vars_bulk(
prisma_client: PrismaClient,
user_id: str,
server_ids: Iterable[str],
) -> Dict[str, Dict[str, str]]:
"""Return ``{server_id: {var_name: value}}`` for one user across many servers.

Servers with no stored row are simply absent from the result.
"""
ids = list(server_ids)
if not ids:
return {}
rows = await prisma_client.db.litellm_mcpuserenvvars.find_many(
where={"user_id": user_id, "server_id": {"in": ids}}
)
return {row.server_id: _decode_user_env_vars(row.values_b64) for row in rows}


async def delete_user_env_vars(
prisma_client: PrismaClient,
user_id: str,
server_id: str,
) -> None:
"""Remove the calling user's env var values for ``server_id``."""
await prisma_client.db.litellm_mcpuserenvvars.delete(
where={"user_id_server_id": {"user_id": user_id, "server_id": server_id}}
)
152 changes: 148 additions & 4 deletions litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,14 +52,19 @@
from litellm.proxy._experimental.mcp_server.oauth2_token_cache import resolve_mcp_auth
from litellm.proxy._experimental.mcp_server.utils import (
MCP_TOOL_PREFIX_SEPARATOR,
MCPMissingUserEnvVarsError,
add_server_prefix_to_name,
build_env_var_setup_url,
collect_env_var_references,
compute_short_server_prefix,
get_server_prefix,
interpolate_headers,
is_short_mcp_tool_prefix_enabled,
is_tool_name_prefixed,
iter_known_server_prefixes,
merge_mcp_headers,
normalize_server_name,
parse_admin_env_vars,
split_server_prefix_from_name,
validate_mcp_server_name,
)
Expand Down Expand Up @@ -289,6 +294,31 @@ def _deserialize_json_dict(data: Any) -> Optional[Dict[str, str]]:
return data


def _deserialize_json_list(data: Any) -> Optional[List[Dict[str, Any]]]:
"""Deserialize a JSON array stored in the DB (``env_vars`` and friends).

Returns ``None`` for empty / null / unparseable input. Accepts strings
(raw JSON), already-materialized lists of dicts, and lists of Pydantic
models (Prisma may hydrate a JSON column such as ``env_vars`` into
``MCPEnvVar`` objects); model entries are normalized to plain dicts so
downstream consumers expecting ``List[Dict[str, Any]]`` validate.
"""
if data is None or data == "" or data == []:
return None
if isinstance(data, str):
try:
parsed = json.loads(data)
except (json.JSONDecodeError, TypeError):
return None
data = parsed
if not isinstance(data, list):
return None
return [
item.model_dump(mode="json") if hasattr(item, "model_dump") else item
for item in data
]


class MCPServerManager:
_STDIO_ENV_TEMPLATE_PATTERN = re.compile(r"^\$\{(X-[^}]+)\}$")

Expand Down Expand Up @@ -574,6 +604,7 @@ async def load_servers_from_config(
allowed_params=server_config.get("allowed_params", None),
access_groups=server_config.get("access_groups", None),
static_headers=server_config.get("static_headers", None),
env_vars=server_config.get("env_vars", None),
allow_all_keys=bool(server_config.get("allow_all_keys", False)),
available_on_public_internet=bool(
server_config.get("available_on_public_internet", True)
Expand Down Expand Up @@ -847,6 +878,7 @@ async def build_mcp_server_from_table(
static_headers_dict = _deserialize_json_dict(
getattr(mcp_server, "static_headers", None)
)
env_vars_list = _deserialize_json_list(getattr(mcp_server, "env_vars", None))
credentials_dict = _deserialize_json_dict(
getattr(mcp_server, "credentials", None)
)
Expand Down Expand Up @@ -946,6 +978,7 @@ async def build_mcp_server_from_table(
mcp_info=mcp_info,
extra_headers=getattr(mcp_server, "extra_headers", None),
static_headers=static_headers_dict,
env_vars=env_vars_list,
client_id=client_id_value or getattr(mcp_server, "client_id", None),
client_secret=client_secret_value
or getattr(mcp_server, "client_secret", None),
Expand Down Expand Up @@ -1487,6 +1520,103 @@ def _build_stdio_env(

return resolved_env

async def _resolve_static_headers_with_env_vars(
self,
server: MCPServer,
user_api_key_auth: Optional[UserAPIKeyAuth],
*,
raise_on_missing: bool = True,
) -> Optional[Dict[str, str]]:
"""Return server.static_headers with ``${NAME}`` interpolated.

Globals come from ``server.env_vars`` entries with ``scope=="global"``.
Per-user values come from the ``LiteLLM_MCPUserEnvVars`` row for the
calling user.

When ``raise_on_missing`` is ``True`` (the tool-*call* path), raises
``MCPMissingUserEnvVarsError`` if ``static_headers`` reference a per-user
variable the calling user has not yet supplied — converted into a
user-facing 412 by the REST layer.

When ``raise_on_missing`` is ``False`` (the tool-*list* path), missing
per-user vars are non-blocking: we interpolate whatever is available and
leave unfilled ``${NAME}`` references untouched, so the server's tools
still appear in the listing. The user only hits the friendly error when
they actually invoke a tool that needs the missing value.
"""
static_headers = server.static_headers
env_vars = getattr(server, "env_vars", None)
if not static_headers and not env_vars:
return static_headers

global_values, user_specs = parse_admin_env_vars(env_vars)
user_var_names = {spec["name"] for spec in user_specs}

# If no env vars are configured, return static_headers as-is.
if not global_values and not user_specs:
return static_headers

# Figure out which user-scoped vars are actually referenced.
referenced = collect_env_var_references(strings=(static_headers or {}).values())
referenced_user_vars = referenced & user_var_names

user_values: Dict[str, str] = {}
if referenced_user_vars:
user_values = await self._load_user_env_vars(server, user_api_key_auth)

if raise_on_missing:
missing = sorted(
name for name in referenced_user_vars if not user_values.get(name)
)
if missing:
raise MCPMissingUserEnvVarsError(
server_id=server.server_id,
server_name=server.server_name or server.name,
missing=missing,
setup_url=build_env_var_setup_url(server.server_id),
)

merged_vars: Dict[str, str] = {**global_values, **user_values}
if not static_headers:
return static_headers
return interpolate_headers(static_headers, merged_vars)

async def _load_user_env_vars(
self,
server: MCPServer,
Comment thread
greptile-apps[bot] marked this conversation as resolved.
Resolved
user_api_key_auth: Optional[UserAPIKeyAuth],
) -> Dict[str, str]:
"""Best-effort lookup of the calling user's env var values for ``server``.

Returns an empty dict when no user is available or the DB lookup
fails — callers detect missing values via name lookup, not by an
exception here.
"""
if user_api_key_auth is None:
return {}
user_id = getattr(user_api_key_auth, "user_id", None)
if not user_id:
return {}
from litellm.proxy.proxy_server import prisma_client # noqa: PLC0415

if prisma_client is None:
return {}
from litellm.proxy._experimental.mcp_server.db import ( # noqa: PLC0415
get_user_env_vars,
)

try:
return await get_user_env_vars(prisma_client, user_id, server.server_id)
except Exception as exc:
verbose_logger.debug(
"MCPServerManager: failed to load user env vars for "
"user=%s server=%s: %s",
user_id,
server.server_id,
exc,
)
return {}

async def _create_mcp_client(
self,
server: MCPServer,
Expand Down Expand Up @@ -1616,10 +1746,17 @@ async def _get_tools_from_server(
client = None

try:
if server.static_headers:
# Tool *listing* must not be blocked by missing per-user env vars —
# the server's tools should still appear so the client connects. The
# friendly "missing vars" error is raised only on the tool-*call*
# path (see _call_regular_mcp_tool).
resolved_static_headers = await self._resolve_static_headers_with_env_vars(
server, user_api_key_auth, raise_on_missing=False
)
if resolved_static_headers:
if extra_headers is None:
extra_headers = {}
extra_headers.update(server.static_headers)
extra_headers.update(resolved_static_headers)

# MCPJWTSigner: inject signed JWT for tools/list (list path skips pre_call_hook).
# Skip entirely when the signer is not configured (avoid an unnecessary
Expand Down Expand Up @@ -2988,10 +3125,17 @@ async def _call_regular_mcp_tool( # noqa: PLR0915
continue
extra_headers[header] = header_value

if mcp_server.static_headers:
# Interpolate env vars into static_headers. Raises
# MCPMissingUserEnvVarsError when the calling user has not filled in
# a required per-user variable — the REST layer converts that into
# a friendly 412 with a setup URL.
resolved_static_headers = await self._resolve_static_headers_with_env_vars(
mcp_server, user_api_key_auth
)
if resolved_static_headers:
if extra_headers is None:
extra_headers = {}
extra_headers.update(mcp_server.static_headers)
extra_headers.update(resolved_static_headers)

if hook_extra_headers:
if extra_headers is None:
Expand Down
Loading
Loading