diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20261020000000_add_tools_ttl_ms_to_mcp/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20261020000000_add_tools_ttl_ms_to_mcp/migration.sql
new file mode 100644
index 00000000000..44887d6855e
--- /dev/null
+++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20261020000000_add_tools_ttl_ms_to_mcp/migration.sql
@@ -0,0 +1,4 @@
+SET LOCAL lock_timeout = '10s';
+
+ALTER TABLE "LiteLLM_MCPServerTable" ADD COLUMN IF NOT EXISTS "tools_ttl_ms" INTEGER;
+ALTER TABLE "LiteLLM_MCPToolsetTable" ADD COLUMN IF NOT EXISTS "tools_ttl_ms" INTEGER;
diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
index 83a0e6f9e05..b0171d6fced 100644
--- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
+++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
@@ -367,6 +367,7 @@ model LiteLLM_MCPServerTable {
instructions String?
url String?
spec_path String?
+ tools_ttl_ms Int?
transport String @default("sse")
auth_type String?
credentials Json? @default("{}")
@@ -434,6 +435,7 @@ model LiteLLM_MCPToolsetTable {
toolset_id String @id @default(uuid())
toolset_name String @unique
description String?
+ tools_ttl_ms Int?
tools Json @default("[]") // [{server_id: string, tool_name: string}]
created_at DateTime @default(now())
created_by String?
diff --git a/litellm/constants.py b/litellm/constants.py
index 2901b7d8948..9d50f1c9b4b 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -278,6 +278,7 @@ AGENT_HEALTH_CHECK_TIMEOUT_SECONDS: Final = get_env_float("LITELLM_AGENT_HEALTH_
AGENT_HEALTH_CHECK_GATHER_TIMEOUT_SECONDS: Final = get_env_float("LITELLM_AGENT_HEALTH_CHECK_GATHER_TIMEOUT", 30.0)
MCP_UPSTREAM_SESSION_SHUTDOWN_TIMEOUT_SECONDS: Final = 5.0
MCP_TOOL_LISTING_MAX_PAGES: Final = 1000
+MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES: Final = 10000
MCP_GATEWAY_SESSION_ID_PREFIX_LENGTH: Final = 8
MCP_BYOK_CREDENTIAL_CACHE_TTL_SECONDS: Final = 60
MCP_BYOK_CREDENTIAL_CACHE_MAX_SIZE: Final = 4096
diff --git a/litellm/models/mcp_server.py b/litellm/models/mcp_server.py
index cdbda7b1b70..519d5c43dda 100644
--- a/litellm/models/mcp_server.py
+++ b/litellm/models/mcp_server.py
@@ -56,6 +56,7 @@ class LiteLLM_MCPServerTable(LiteLLMPydanticObjectBase):
description: str | None = None
url: str | None = None
spec_path: str | None = None
+ tools_ttl_ms: int | None = Field(default=None, ge=0)
transport: MCPTransportType
auth_type: MCPAuthType | None = None
credentials: MCPCredentials | None = None
diff --git a/litellm/proxy/_experimental/mcp_server/catalog.py b/litellm/proxy/_experimental/mcp_server/catalog.py
index 2db548f5863..216096ba939 100644
--- a/litellm/proxy/_experimental/mcp_server/catalog.py
+++ b/litellm/proxy/_experimental/mcp_server/catalog.py
@@ -24,9 +24,11 @@ from pydantic import BaseModel, ConfigDict, JsonValue, TypeAdapter
from litellm._logging import verbose_logger
from litellm.caching.in_memory_cache import InMemoryCache
from litellm.proxy._experimental.mcp_server.result_conversion import age_freshness, aggregate_freshness
+from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
if TYPE_CHECKING:
from mcp.types import ListToolsResult, PaginatedRequestParams, PaginatedResult
+ from mcp.types import Tool as MCPWireTool
from litellm.proxy._experimental.mcp_server.contracts import CatalogListRequest, CatalogListResult, OperationContext
from litellm.proxy._experimental.mcp_server.db import OAuthCredentialPayload
@@ -858,6 +860,7 @@ async def get_filtered_server_tools(
proxy_logging_obj=proxy_logging_obj,
catalog_auth_header=catalog_auth_header,
record_listing=False,
+ wire_compat=context.wire_compat,
)
)
else:
@@ -875,6 +878,7 @@ async def get_filtered_server_tools(
catalog_auth_header=catalog_auth_header,
record_listing=False,
listing_updates=listing_updates,
+ wire_compat=context.wire_compat,
)
tools: Final = page.tools
filtered_tools = filter_tools_by_allowed_tools(tools, server)
@@ -907,20 +911,29 @@ async def get_filtered_server_tools(
else:
listing_updates.callback(record)
- if mcp_proxy_mode:
+ def with_proxy_identity(tool: MCPWireTool) -> MCPWireTool:
from litellm.proxy._experimental.mcp_server.tool_search import with_mcp_proxy_identity
- filtered_tools = [with_mcp_proxy_identity(tool, server.server_id) for tool in filtered_tools]
- else:
- filtered_tools = apply_display_name_overrides(filtered_tools, server)
+ return with_mcp_proxy_identity(tool, server.server_id)
+
+ listed_tools: Final = (
+ tuple(with_proxy_identity(tool) for tool in filtered_tools)
+ if mcp_proxy_mode
+ else apply_display_name_overrides(filtered_tools, server, wire_compat=context.wire_compat)
+ )
+ response_tools: Final = (
+ [tool.model_copy(update={"output_schema": None, "title": None}) for tool in listed_tools]
+ if not mcp_proxy_mode and server.spec_path and context.wire_compat == WireCompat.LEGACY
+ else list(listed_tools)
+ )
verbose_logger.debug(
"Successfully fetched %s tools from server %s, %s after filtering",
len(tools),
server.name,
- len(filtered_tools),
+ len(response_tools),
)
- return page.model_copy(update={"tools": filtered_tools}), ServerListOk(tool_count=len(filtered_tools))
+ return page.model_copy(update={"tools": response_tools}), ServerListOk(tool_count=len(response_tools))
except MCPUpstreamAuthError as e:
# Absorb so one unauthenticated server does not empty every other server's
# tools. Surfacing the upstream 401 to the client as a re-auth challenge is
@@ -1067,6 +1080,7 @@ async def list_gateway_tools(
from litellm.proxy._experimental.mcp_server.faults.list_outcomes import (
SERVER_OUTCOMES_META_KEY,
+ ServerListOk,
listing_failed_outright,
outcome_wire_value,
)
@@ -1096,10 +1110,13 @@ async def list_gateway_tools(
message="Every MCP server in scope failed to list tools",
data={SERVER_OUTCOMES_META_KEY: wire_outcomes},
)
+ toolset_ttl: Final = context.toolset_tools_ttl_ms
+ complete: Final = not any(not isinstance(outcome, ServerListOk) for outcome in listing.outcomes.values())
+ ttl_ms: Final = toolset_ttl if toolset_ttl is not None and complete else listing.ttl_ms
return ListToolsResult(
tools=listing.tools,
next_cursor=listing.next_cursor,
- ttl_ms=listing.ttl_ms,
+ ttl_ms=ttl_ms,
cache_scope="private",
_meta={SERVER_OUTCOMES_META_KEY: wire_outcomes} if wire_outcomes else None,
)
diff --git a/litellm/proxy/_experimental/mcp_server/contracts.py b/litellm/proxy/_experimental/mcp_server/contracts.py
index 84cd2751444..16858f7bdb5 100644
--- a/litellm/proxy/_experimental/mcp_server/contracts.py
+++ b/litellm/proxy/_experimental/mcp_server/contracts.py
@@ -70,6 +70,7 @@ class OperationContext:
mcp_proxy_mode: bool = False
wire_compat: WireCompat = WireCompat.LEGACY
protocol_version: str | None = None
+ toolset_tools_ttl_ms: int | None = None
incoming_bearer_token: SecretStr | None | EllipsisType = field(default=..., repr=False)
def __post_init__(self) -> None:
diff --git a/litellm/proxy/_experimental/mcp_server/mcp_context.py b/litellm/proxy/_experimental/mcp_server/mcp_context.py
index 8ec44f65bdf..e05e4e9404e 100644
--- a/litellm/proxy/_experimental/mcp_server/mcp_context.py
+++ b/litellm/proxy/_experimental/mcp_server/mcp_context.py
@@ -28,6 +28,9 @@ def get_active_mcp_request_ctx() -> "ServerRequestContext | None":
# /toolset/{name}/mcp or the toolset fallback in dynamic_mcp_route.
# Never populated from client-supplied headers.
mcp_active_toolset_id: Final[ContextVar[str | None]] = ContextVar("_mcp_active_toolset_id", default=None)
+mcp_active_toolset_tools_ttl_ms: Final[ContextVar[int | None]] = ContextVar(
+ "_mcp_active_toolset_tools_ttl_ms", default=None
+)
_mcp_active_toolset_id: Final = mcp_active_toolset_id
diff --git a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
index db70c7d77de..efcd5b5d8a3 100644
--- a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
+++ b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
@@ -409,8 +409,10 @@ class MCPServerConfig(TypedDict, total=False):
mcp_info: MCPInfo
url: str
spec_path: str
+ tools_ttl_ms: ReadOnly[int | None]
transport: MCPTransportType
auth_type: MCPAuthType
+ tool_name_to_display_name: ReadOnly[_StringMap]
authentication_token: str
auth_value: str
instructions: str
@@ -2768,6 +2770,8 @@ class MCPServerManager:
alias=alias,
server_name=server_name,
spec_path=server_config.get("spec_path", None),
+ tools_ttl_ms=server_config.get("tools_ttl_ms", None),
+ tool_name_to_display_name=server_config.get("tool_name_to_display_name", None),
url=server_url,
command=server_config.get("command", None) or "",
args=server_config.get("args", None) or [],
@@ -2921,6 +2925,7 @@ class MCPServerManager:
"""
from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import (
build_input_schema,
+ build_output_schema,
create_tool_function,
load_openapi_spec_async,
resolve_operation_params,
@@ -3032,6 +3037,8 @@ class MCPServerManager:
description=description,
input_schema=input_schema,
handler=tool_func,
+ output_schema=build_output_schema(operation, spec),
+ title=operation.get("summary"),
server_id=server.server_id,
)
@@ -3351,6 +3358,7 @@ class MCPServerManager:
server_name=getattr(mcp_server, "server_name", None),
url=mcp_server.url,
spec_path=getattr(mcp_server, "spec_path", None),
+ tools_ttl_ms=getattr(mcp_server, "tools_ttl_ms", None),
transport=cast(MCPTransportType, mcp_server.transport),
auth_type=auth_type,
authentication_token=auth_value,
@@ -4420,6 +4428,7 @@ class MCPServerManager:
*,
catalog_auth_header: str | dict[str, str] | None | EllipsisType = ...,
record_listing: bool = False,
+ wire_compat: WireCompat = WireCompat.LEGACY,
) -> list[MCPTool]:
result: Final = await self.get_tools_page(
server=server,
@@ -4433,6 +4442,7 @@ class MCPServerManager:
proxy_logging_obj=proxy_logging_obj,
catalog_auth_header=catalog_auth_header,
record_listing=record_listing,
+ wire_compat=wire_compat,
)
return result.tools
@@ -4454,6 +4464,7 @@ class MCPServerManager:
catalog_auth_header: str | dict[str, str] | None | EllipsisType = ...,
record_listing: bool = False,
listing_updates: ExitStack | None = None,
+ wire_compat: WireCompat = WireCompat.LEGACY,
) -> ListToolsResult:
from litellm.proxy._experimental.mcp_server.tool_registry import (
global_mcp_tool_registry,
@@ -4557,7 +4568,8 @@ class MCPServerManager:
# active at registration time — fetch by that same prefix.
registry_prefix: Final = normalize_server_name(get_server_prefix(server)) + MCP_TOOL_PREFIX_SEPARATOR
registered: Final = global_mcp_tool_registry.convert_tools_to_mcp_sdk_tool_type(
- global_mcp_tool_registry.list_tools(tool_prefix=registry_prefix)
+ global_mcp_tool_registry.list_tools(tool_prefix=registry_prefix),
+ wire_compat=wire_compat,
)
registered_names: Final = MappingProxyType(
{t.name.removeprefix(registry_prefix): t.name for t in registered}
@@ -4577,9 +4589,13 @@ class MCPServerManager:
server, guarded_openapi, listed_caller, listed_generation, record_listing=record_listing
)
if not add_prefix:
- return ListToolsResult(tools=list(guarded_openapi))
+ return ListToolsResult(
+ tools=list(guarded_openapi),
+ ttl_ms=server.tools_ttl_ms if server.tools_ttl_ms is not None else 0,
+ )
return ListToolsResult(
- tools=[t.model_copy(update={"name": registered_names[t.name]}) for t in guarded_openapi]
+ tools=[t.model_copy(update={"name": registered_names[t.name]}) for t in guarded_openapi],
+ ttl_ms=server.tools_ttl_ms if server.tools_ttl_ms is not None else 0,
)
else:
page: Final = (
@@ -7598,6 +7614,8 @@ class MCPServerManager:
alias=server.alias,
description=(server.mcp_info.get("description") if server.mcp_info else None),
url=server.url,
+ spec_path=server.spec_path,
+ tools_ttl_ms=server.tools_ttl_ms,
transport=server.transport,
auth_type=server.auth_type,
created_at=server.created_at,
@@ -7711,6 +7729,7 @@ class MCPServerManager:
description=(server.mcp_info.get("description") if server.mcp_info else None),
url=server.url,
spec_path=server.spec_path,
+ tools_ttl_ms=server.tools_ttl_ms,
transport=server.transport,
auth_type=server.auth_type,
credentials=({"scopes": list(server.configured_scopes)} if server.configured_scopes else None),
diff --git a/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py b/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
index f0353f309a9..38c1051775c 100644
--- a/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
+++ b/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
@@ -8,13 +8,17 @@ import json
import os
import re
from collections.abc import Mapping, Sequence
+from functools import reduce
+from itertools import chain
from pathlib import PurePosixPath
from typing import Final, Literal, Protocol, TypeAlias, TypedDict, overload
from urllib.parse import quote
import httpx
+from pydantic import TypeAdapter, ValidationError
from typing_extensions import ReadOnly, Required
+from litellm import constants
from litellm.llms.custom_httpx.http_handler import MaskedHTTPStatusError
from litellm.proxy._experimental.mcp_server.exceptions import (
MCPOpenApiUpstreamError,
@@ -31,6 +35,8 @@ OPENAPI_TOOL_NAME_MAX_LEN: Final = 128
_OPENAPI_TOOL_NAME_MAX_LEN: Final = OPENAPI_TOOL_NAME_MAX_LEN
+_OPENAPI_SCHEMA_RESOLUTION_CHUNK_SIZE: Final = 32
+
def sanitize_openapi_tool_name(raw_name: str) -> str:
"""Map an OpenAPI operationId / fallback to a provider-safe tool name.
@@ -74,7 +80,11 @@ class _OpenAPIParameter(TypedDict, total=False):
class _OpenAPIMediaType(TypedDict, total=False):
- schema: _OpenAPIJSONSchema
+ schema: ReadOnly[Mapping[str, object]]
+
+
+class _OpenAPIResponse(TypedDict, total=False):
+ content: ReadOnly[Mapping[str, _OpenAPIMediaType]]
class _OpenAPIRequestBody(TypedDict, total=False):
@@ -89,6 +99,7 @@ class _OpenAPIOperation(TypedDict, total=False):
description: str
parameters: Sequence[_OpenAPIParameter]
requestBody: _OpenAPIRequestBody
+ responses: ReadOnly[Mapping[str, _OpenAPIResponse]]
_OpenAPIMethod: TypeAlias = Literal["get", "post", "put", "delete", "patch"]
@@ -110,6 +121,7 @@ class _OpenAPIPathItem(Protocol):
class _OpenAPIComponents(TypedDict, total=False):
parameters: Mapping[str, _OpenAPIParameter]
+ schemas: ReadOnly[Mapping[str, Mapping[str, object]]]
class _OpenAPIServer(TypedDict):
@@ -125,6 +137,10 @@ class _OpenAPISpec(TypedDict, total=False):
basePath: ReadOnly[str]
+_OPENAPI_OBJECT_ADAPTER: Final = TypeAdapter(dict[str, object])
+_OPENAPI_ARRAY_ADAPTER: Final = TypeAdapter(list[object])
+
+
# Store the base URL and headers globally
BASE_URL: Final = ""
HEADERS: Final[dict[str, str]] = {}
@@ -379,7 +395,7 @@ def build_input_schema(operation: _OpenAPIOperation) -> dict[str, object]:
# Try to get JSON schema
if "application/json" in content:
- schema: Final[_OpenAPIJSONSchema] = content["application/json"].get("schema", {})
+ schema: Final = content["application/json"].get("schema", {})
properties["body"] = {
"type": "object",
"description": request_body.get("description", "Request body"),
@@ -395,6 +411,246 @@ def build_input_schema(operation: _OpenAPIOperation) -> dict[str, object]:
}
+def _resolve_openapi_schema_value(
+ value: object, spec: _OpenAPISpec, seen: frozenset[str], budget: int
+) -> tuple[bool, object, int]:
+ remaining: Final = budget - 1
+ if remaining < 0:
+ return False, None, remaining
+ if isinstance(value, Mapping):
+ try:
+ mapping_value: Final = _OPENAPI_OBJECT_ADAPTER.validate_python(value)
+ except ValidationError:
+ return False, None, remaining
+ return _resolve_openapi_schema_mapping(mapping_value, spec, seen, remaining)
+ if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+ try:
+ sequence_value: Final = _OPENAPI_ARRAY_ADAPTER.validate_python(value)
+ except ValidationError:
+ return False, None, remaining
+ return _resolve_openapi_schema_sequence(sequence_value, spec, seen, remaining)
+ return True, value, remaining
+
+
+def _resolve_openapi_schema_mapping(
+ value: Mapping[str, object], spec: _OpenAPISpec, seen: frozenset[str], budget: int
+) -> tuple[bool, object, int]:
+ ref: Final = value.get("$ref")
+ if ref is not None:
+ ref_result: Final = _resolve_openapi_schema_value(ref, spec, seen, budget)
+ if not ref_result[0]:
+ return False, None, ref_result[2]
+ return _resolve_openapi_schema_reference(ref_result[1], spec, seen, ref_result[2])
+ mapping_items: Final = tuple(value.items())
+ child_values: Final = tuple(item for _, item in mapping_items)
+ resolved_items: Final = _resolve_openapi_schema_children(child_values, spec, seen, budget)
+ if not resolved_items[0] or resolved_items[1] is None:
+ return False, None, resolved_items[2]
+ resolved_values: Final = resolved_items[1]
+ return (
+ True,
+ {key: item for (key, _), item in zip(mapping_items, resolved_values)},
+ resolved_items[2],
+ )
+
+
+def _resolve_openapi_schema_reference(
+ ref: object, spec: _OpenAPISpec, seen: frozenset[str], budget: int
+) -> tuple[bool, object, int]:
+ if not isinstance(ref, str) or not ref.startswith("#/components/schemas/") or ref in seen:
+ return False, None, budget
+ schema_name: Final = ref.rsplit("/", 1)[-1]
+ components: Final = spec.get("components")
+ if components is None:
+ return False, None, budget
+ schemas: Final = components.get("schemas")
+ if schemas is None:
+ return False, None, budget
+ target: Final = schemas.get(schema_name)
+ if target is None:
+ return False, None, budget
+ return _resolve_openapi_schema_value(target, spec, seen | {ref}, budget)
+
+
+def _resolve_openapi_schema_sequence(
+ value: Sequence[object], spec: _OpenAPISpec, seen: frozenset[str], budget: int
+) -> tuple[bool, object, int]:
+ resolved_items: Final = _resolve_openapi_schema_children(value, spec, seen, budget)
+ if not resolved_items[0] or resolved_items[1] is None:
+ return False, None, resolved_items[2]
+ resolved_values: Final = resolved_items[1]
+ return True, list(resolved_values), resolved_items[2]
+
+
+def _resolve_openapi_schema_children(
+ values: Sequence[object],
+ spec: _OpenAPISpec,
+ seen: frozenset[str],
+ budget: int,
+) -> tuple[bool, tuple[object, ...] | None, int]:
+ def resolve_child(
+ accumulator: tuple[bool, tuple[tuple[object, ...], ...], tuple[object, ...], int],
+ value: object,
+ ) -> tuple[bool, tuple[tuple[object, ...], ...], tuple[object, ...], int]:
+ if not accumulator[0]:
+ return accumulator
+ child_result: Final = _resolve_openapi_schema_value(value, spec, seen, accumulator[3])
+ if not child_result[0]:
+ return False, accumulator[1], accumulator[2], child_result[2]
+ current_chunk: Final = (*accumulator[2], child_result[1])
+ if len(current_chunk) < _OPENAPI_SCHEMA_RESOLUTION_CHUNK_SIZE:
+ return True, accumulator[1], current_chunk, child_result[2]
+ return True, (*accumulator[1], current_chunk), (), child_result[2]
+
+ resolved: Final = reduce(resolve_child, values, (True, (), (), budget))
+ if not resolved[0]:
+ return False, None, resolved[3]
+ chunks: Final = (*resolved[1], resolved[2]) if resolved[2] else resolved[1]
+ return True, tuple(chain.from_iterable(chunks)), resolved[3]
+
+
+def _get_openapi_output_schema(operation: _OpenAPIOperation) -> Mapping[str, object] | None:
+ responses: Final = operation.get("responses")
+ if responses is None:
+ return None
+ response_codes: Final = tuple(
+ sorted((code for code in responses if code.isdigit() and 200 <= int(code) < 300), key=int)
+ )
+ selected_code: Final = response_codes[0] if response_codes else ("2XX" if "2XX" in responses else None)
+ if selected_code is None:
+ return None
+ response: Final = responses.get(selected_code)
+ if response is None:
+ return None
+ content: Final = response.get("content")
+ if content is None:
+ return None
+ media_type: Final = next(
+ (
+ value
+ for key, value in content.items()
+ if key == "application/json" or (key.startswith("application/") and key.endswith("+json"))
+ ),
+ None,
+ )
+ if media_type is None:
+ return None
+ return media_type.get("schema")
+
+
+_OPENAPI_SCHEMA_CHILD_KEYS: Final = frozenset(
+ {
+ "additionalItems",
+ "additionalProperties",
+ "contains",
+ "contentSchema",
+ "else",
+ "if",
+ "items",
+ "not",
+ "propertyNames",
+ "then",
+ "unevaluatedItems",
+ "unevaluatedProperties",
+ }
+)
+_OPENAPI_SCHEMA_MAP_KEYS: Final = frozenset(
+ {"$defs", "definitions", "dependentSchemas", "patternProperties", "properties"}
+)
+_OPENAPI_SCHEMA_SEQUENCE_KEYS: Final = frozenset({"allOf", "anyOf", "oneOf", "prefixItems"})
+_OPENAPI_SCHEMA_KEYS: Final = _OPENAPI_SCHEMA_CHILD_KEYS | _OPENAPI_SCHEMA_MAP_KEYS | _OPENAPI_SCHEMA_SEQUENCE_KEYS
+
+
+def _normalize_openapi_exclusive_bound(
+ value: Mapping[str, object], bound_key: str, exclusive_key: str
+) -> dict[str, object]:
+ bound: Final = value.get(bound_key)
+ exclusive: Final = value.get(exclusive_key)
+ bound_fields: Final = {bound_key: bound} if bound_key in value else {}
+ if isinstance(exclusive, bool):
+ if exclusive and isinstance(bound, (int, float)) and not isinstance(bound, bool):
+ return {exclusive_key: bound}
+ return bound_fields
+ if exclusive_key in value:
+ return {**bound_fields, exclusive_key: exclusive}
+ return bound_fields
+
+
+def _normalize_openapi_nullable_schema(value: object) -> object:
+ if isinstance(value, Mapping):
+ schema_mapping: Final = _OPENAPI_OBJECT_ADAPTER.validate_python(value)
+ nullable: Final = schema_mapping.get("nullable") is True
+ schema_type: Final = schema_mapping.get("type")
+ schema_children: Final = {
+ key: _normalize_openapi_nullable_schema_children(item)
+ if key in _OPENAPI_SCHEMA_MAP_KEYS
+ else _normalize_openapi_nullable_schema(item)
+ for key, item in schema_mapping.items()
+ if key in _OPENAPI_SCHEMA_KEYS
+ }
+ schema_fields: Final = {
+ key: item
+ for key, item in schema_mapping.items()
+ if key not in _OPENAPI_SCHEMA_KEYS
+ and key not in ("nullable", "type", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum")
+ }
+ normalized_fields: Final = {
+ **schema_fields,
+ **schema_children,
+ **_normalize_openapi_exclusive_bound(schema_mapping, "minimum", "exclusiveMinimum"),
+ **_normalize_openapi_exclusive_bound(schema_mapping, "maximum", "exclusiveMaximum"),
+ }
+ if nullable and isinstance(schema_type, str):
+ return {**normalized_fields, "type": [schema_type, "null"]}
+ if nullable and isinstance(schema_type, Sequence) and not isinstance(schema_type, (str, bytes, bytearray)):
+ type_values: Final = _OPENAPI_ARRAY_ADAPTER.validate_python(schema_type)
+ normalized_types: Final = tuple(_normalize_openapi_nullable_schema(item) for item in type_values)
+ nullable_types: Final = (
+ list(normalized_types) if "null" in normalized_types else [*normalized_types, "null"]
+ )
+ return {**normalized_fields, "type": nullable_types}
+ if nullable:
+ return {"anyOf": [normalized_fields, {"type": "null"}]}
+ if "type" in schema_mapping:
+ return {
+ **normalized_fields,
+ "type": _normalize_openapi_nullable_schema(schema_type),
+ }
+ return normalized_fields
+ if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+ schema_sequence: Final = _OPENAPI_ARRAY_ADAPTER.validate_python(value)
+ return [_normalize_openapi_nullable_schema(item) for item in schema_sequence]
+ return value
+
+
+def _normalize_openapi_nullable_schema_children(value: object) -> object:
+ if not isinstance(value, Mapping):
+ return value
+ schema_children: Final = _OPENAPI_OBJECT_ADAPTER.validate_python(value)
+ return {key: _normalize_openapi_nullable_schema(item) for key, item in schema_children.items()}
+
+
+def build_output_schema(
+ operation: _OpenAPIOperation, spec: _OpenAPISpec
+) -> dict[str, object] | None: # mutable-ok: MCP SDK output schemas require a copied dict
+ schema: Final = _get_openapi_output_schema(operation)
+ if schema is None:
+ return None
+ resolved: Final = _resolve_openapi_schema_value(
+ schema, spec, frozenset(), constants.MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES
+ )
+ if not resolved[0]:
+ return None
+ try:
+ normalized_schema: Final = _normalize_openapi_nullable_schema(resolved[1])
+ resolved_schema: Final = _OPENAPI_OBJECT_ADAPTER.validate_python(normalized_schema)
+ except ValidationError:
+ return None
+ if resolved_schema.get("type") != "object":
+ return None
+ return resolved_schema
+
+
async def _drop_credential_across_origin(request: httpx.Request) -> None:
"""Apply this request's cross-origin credential guard, if it needs one.
@@ -677,5 +933,7 @@ def register_tools_from_openapi(spec: _OpenAPISpec, base_url: str) -> None:
description=description,
input_schema=input_schema,
handler=tool_func,
+ output_schema=build_output_schema(operation, spec),
+ title=operation.get("summary"),
)
verbose_logger.debug("Registered tool: %s", tool_name)
diff --git a/litellm/proxy/_experimental/mcp_server/operations.py b/litellm/proxy/_experimental/mcp_server/operations.py
index 39e882fcab0..283fe081a19 100644
--- a/litellm/proxy/_experimental/mcp_server/operations.py
+++ b/litellm/proxy/_experimental/mcp_server/operations.py
@@ -123,6 +123,7 @@ from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import ( #
request_auth_header,
request_extra_headers,
request_resolved_auth_headers,
+ sanitize_openapi_tool_name,
)
from litellm.proxy._experimental.mcp_server.result_conversion import (
WireCompat,
@@ -827,18 +828,39 @@ def filter_tools_by_allowed_tools(
def apply_display_name_overrides(
tools: list[MCPTool],
mcp_server: MCPServer,
+ *,
+ wire_compat: WireCompat = WireCompat.LEGACY,
) -> list[MCPTool]:
"""Apply admin-configured display name overrides, keyed by the unprefixed tool name like allowed_tools."""
display_name_map: Final = mcp_server.tool_name_to_display_name or {}
if not display_name_map:
return tools
- for tool in tools:
- unprefixed = strip_known_server_prefix(tool.name, mcp_server)
- lookup_key = unprefixed or tool.name
- if lookup_key in display_name_map:
- tool.name = display_name_map[lookup_key]
- return tools
+ modern_openapi: Final = mcp_server.spec_path is not None and wire_compat == WireCompat.MODERN
+
+ def apply_override(tool: MCPTool) -> MCPTool:
+ unprefixed: Final = strip_known_server_prefix(tool.name, mcp_server)
+ lookup_key: Final = unprefixed or tool.name
+ raw_display_name: Final = display_name_map.get(lookup_key)
+ display_name: Final[str | None] = (
+ raw_display_name
+ if raw_display_name is not None
+ else next(
+ (
+ override
+ for key, override in display_name_map.items()
+ if mcp_server.spec_path and sanitize_openapi_tool_name(key) == lookup_key
+ ),
+ None,
+ )
+ )
+ if display_name is None:
+ return tool
+ if modern_openapi:
+ return tool.model_copy(update={"title": display_name})
+ return tool.model_copy(update={"name": display_name})
+
+ return [apply_override(tool) for tool in tools]
@catalog_operation(lambda: global_mcp_server_manager)
@@ -1367,6 +1389,7 @@ async def _get_tools_from_mcp_servers(
)
from litellm.proxy._experimental.mcp_server.catalog import get_filtered_server_tools
+ from litellm.proxy._experimental.mcp_server.result_conversion import wire_compat_for
context: Final = OperationContext(
_caller=user_api_key_auth,
@@ -1377,6 +1400,7 @@ async def _get_tools_from_mcp_servers(
raw_headers=raw_headers,
client_ip=client_ip,
mcp_proxy_mode=mcp_proxy_mode,
+ wire_compat=wire_compat_for(protocol_version) if protocol_version is not None else WireCompat.LEGACY,
protocol_version=protocol_version,
)
@@ -1884,7 +1908,10 @@ def _resolve_display_name_to_original(
display_map = server.tool_name_to_display_name or {}
for unprefixed_name, display_name in display_map.items():
if display_name == name:
- return add_server_prefix_to_name(unprefixed_name, get_server_prefix(server))
+ return add_server_prefix_to_name(
+ sanitize_openapi_tool_name(unprefixed_name) if server.spec_path else unprefixed_name,
+ get_server_prefix(server),
+ )
return name
@@ -3665,6 +3692,7 @@ def prepare_context(
wire_compat: WireCompat = WireCompat.LEGACY,
protocol_version: str | None = None,
incoming_bearer_token: SecretStr | None | EllipsisType = ...,
+ toolset_tools_ttl_ms: int | None = None,
) -> OperationContext:
return OperationContext(
_caller=user_api_key_auth,
@@ -3677,6 +3705,7 @@ def prepare_context(
mcp_proxy_mode=mcp_proxy_mode,
wire_compat=wire_compat,
protocol_version=protocol_version,
+ toolset_tools_ttl_ms=toolset_tools_ttl_ms,
incoming_bearer_token=incoming_bearer_token,
)
diff --git a/litellm/proxy/_experimental/mcp_server/server.py b/litellm/proxy/_experimental/mcp_server/server.py
index 7207c4150ad..be17198b599 100644
--- a/litellm/proxy/_experimental/mcp_server/server.py
+++ b/litellm/proxy/_experimental/mcp_server/server.py
@@ -59,6 +59,7 @@ from litellm.proxy._experimental.mcp_server.mcp_context import ( # noqa: F401
active_mcp_request_ctx_var,
get_active_mcp_request_ctx,
mcp_active_toolset_id,
+ mcp_active_toolset_tools_ttl_ms,
mcp_gateway_initialize_instructions,
mcp_gateway_server_name,
)
@@ -899,6 +900,7 @@ if MCP_AVAILABLE:
if isinstance(request, StarletteRequest)
else None
),
+ toolset_tools_ttl_ms=mcp_active_toolset_tools_ttl_ms.get(),
)
async def handle_list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams) -> ListToolsResult:
diff --git a/litellm/proxy/_experimental/mcp_server/tool_registry.py b/litellm/proxy/_experimental/mcp_server/tool_registry.py
index 1f1d952f96c..992cf9fc1f1 100644
--- a/litellm/proxy/_experimental/mcp_server/tool_registry.py
+++ b/litellm/proxy/_experimental/mcp_server/tool_registry.py
@@ -1,11 +1,14 @@
import asyncio
import json
-from collections.abc import Callable, Generator, Mapping
+from collections.abc import Callable, Generator, Mapping, Sequence
from contextlib import contextmanager
from contextvars import ContextVar
from typing import TYPE_CHECKING, Final
+from pydantic import TypeAdapter
+
from litellm._logging import verbose_logger
+from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
from litellm.proxy.types_utils.utils import get_instance_fn
from litellm.types.mcp_server.tool_registry import MCPTool
@@ -60,6 +63,8 @@ class MCPToolRegistry:
handler: Callable,
*,
server_id: str | None = None,
+ output_schema: Mapping[str, object] | None = None,
+ title: str | None = None,
) -> None:
"""
Register a new tool in the registry
@@ -70,6 +75,8 @@ class MCPToolRegistry:
input_schema=input_schema,
handler=handler,
server_id=server_id,
+ output_schema=dict(output_schema) if output_schema is not None else None,
+ title=title,
)
verbose_logger.debug("Registered tool: %s", name)
@@ -103,14 +110,20 @@ class MCPToolRegistry:
verbose_logger.debug("Unregistered MCP tool %s", name)
return removed
- def convert_tools_to_mcp_sdk_tool_type(self, tools: list[MCPTool]) -> list["MCPToolSDKTool"]:
+ def convert_tools_to_mcp_sdk_tool_type(
+ self, tools: Sequence[MCPTool], *, wire_compat: WireCompat = WireCompat.LEGACY
+ ) -> Sequence["MCPToolSDKTool"]:
if MCPToolSDKTool is None:
raise ImportError("MCP SDK is not installed. Please install it with: pip install 'litellm[proxy]'")
return [
- MCPToolSDKTool(
- name=tool.name,
- description=tool.description,
- inputSchema=tool.input_schema,
+ MCPToolSDKTool.model_validate(
+ {
+ "name": tool.name,
+ "description": tool.description,
+ "inputSchema": tool.input_schema,
+ "outputSchema": tool.output_schema if wire_compat is WireCompat.MODERN else None,
+ "title": tool.title if wire_compat is WireCompat.MODERN else None,
+ }
)
for tool in tools
]
@@ -140,16 +153,23 @@ class MCPToolRegistry:
name = tool_config.get("name")
description = tool_config.get("description")
- input_schema = tool_config.get("input_schema", {})
+ raw_input_schema = tool_config.get("input_schema", {})
handler_name = tool_config.get("handler")
- if not all([name, description, handler_name]):
+ if (
+ not isinstance(name, str)
+ or not name
+ or not isinstance(description, str)
+ or not description
+ or not isinstance(handler_name, str)
+ or not handler_name
+ ):
continue
+ input_schema = TypeAdapter(dict[str, object]).validate_python(raw_input_schema)
+
# Try to resolve the handler
# First check if it's a module path (e.g., "module.submodule.function")
- if handler_name is None:
- raise ValueError(f"handler is required for tool {name}")
handler = get_instance_fn(handler_name, config_file_path)
if handler is None:
@@ -157,11 +177,6 @@ class MCPToolRegistry:
continue
# Register the tool
- if name is None:
- raise ValueError(f"name is required for tool {name}")
- if description is None:
- raise ValueError(f"description is required for tool {name}")
-
self.register_tool(
name=name,
description=description,
diff --git a/litellm/proxy/_experimental/mcp_server/toolset_db.py b/litellm/proxy/_experimental/mcp_server/toolset_db.py
index 35906c793b4..40226f1ba92 100644
--- a/litellm/proxy/_experimental/mcp_server/toolset_db.py
+++ b/litellm/proxy/_experimental/mcp_server/toolset_db.py
@@ -23,6 +23,7 @@ class MCPToolsetFields(TypedDict):
toolset_id: ReadOnly[str]
toolset_name: ReadOnly[str]
description: NotRequired[ReadOnly[str | None]]
+ tools_ttl_ms: NotRequired[ReadOnly[int | None]]
tools: NotRequired[ReadOnly[list[MCPToolsetTool]]]
created_at: NotRequired[ReadOnly[datetime | None]]
created_by: NotRequired[ReadOnly[str | None]]
@@ -36,6 +37,7 @@ class MCPToolsetRowData(TypedDict):
toolset_id: ReadOnly[str]
toolset_name: ReadOnly[str]
description: NotRequired[ReadOnly[str | None]]
+ tools_ttl_ms: NotRequired[ReadOnly[int | None]]
tools: NotRequired[ReadOnly[str | list[MCPToolsetTool]]]
created_at: NotRequired[ReadOnly[datetime | None]]
created_by: NotRequired[ReadOnly[str | None]]
diff --git a/litellm/proxy/_lazy_openapi_snapshot.json b/litellm/proxy/_lazy_openapi_snapshot.json
index 166072e9613..9d9bc5e9738 100644
--- a/litellm/proxy/_lazy_openapi_snapshot.json
+++ b/litellm/proxy/_lazy_openapi_snapshot.json
@@ -36482,6 +36482,18 @@
],
"title": "Tool Name To Display Name"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"transport": {
"default": "sse",
"enum": [
@@ -38406,6 +38418,18 @@
],
"title": "Tool Name To Display Name"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"transport": {
"enum": [
"sse",
@@ -39310,6 +39334,18 @@
],
"title": "Tool Name To Display Name"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"transport": {
"default": "sse",
"enum": [
@@ -41605,6 +41641,18 @@
],
"title": "Tool Name To Display Name"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"transport": {
"enum": [
"sse",
@@ -43353,6 +43401,18 @@
],
"title": "Tool Name To Display Name"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"transport": {
"default": "sse",
"enum": [
@@ -43399,6 +43459,18 @@
"title": "Tools",
"type": "array"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"toolset_name": {
"title": "Toolset Name",
"type": "string"
@@ -43876,6 +43948,18 @@
],
"title": "Tool Name To Display Name"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"transport": {
"default": "sse",
"enum": [
@@ -43931,6 +44015,18 @@
],
"title": "Tools"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"toolset_id": {
"title": "Toolset Id",
"type": "string"
@@ -46817,6 +46913,18 @@
],
"title": "Tool Name To Display Name"
},
+ "tools_ttl_ms": {
+ "anyOf": [
+ {
+ "minimum": 0.0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Tools Ttl Ms"
+ },
"transport": {
"default": "sse",
"enum": [
diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py
index 49d23d82aa9..b0f3d6f7152 100644
--- a/litellm/proxy/_types.py
+++ b/litellm/proxy/_types.py
@@ -1379,6 +1379,7 @@ class NewMCPServerRequest(LiteLLMPydanticObjectBase):
credentials: MCPCredentials | None = None
url: str | None = None
spec_path: str | None = None
+ tools_ttl_ms: int | None = Field(default=None, ge=0)
mcp_info: MCPInfo | None = None
mcp_access_groups: list[str] = Field(default_factory=list)
allowed_tools: list[str] | None = None
@@ -1487,6 +1488,7 @@ class UpdateMCPServerRequest(LiteLLMPydanticObjectBase):
credentials: MCPCredentials | None = None
url: str | None = None
spec_path: str | None = None
+ tools_ttl_ms: int | None = Field(default=None, ge=0)
mcp_info: MCPInfo | None = None
mcp_access_groups: list[str] = Field(default_factory=list)
allowed_tools: list[str] | None = None
diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py
index ca0f8892b9d..1465b998662 100644
--- a/litellm/proxy/proxy_server.py
+++ b/litellm/proxy/proxy_server.py
@@ -21822,12 +21822,15 @@ async def toolset_mcp_route(toolset_name: str, request: Request):
will be rejected with a 403.
"""
try:
+ from litellm.proxy._experimental.mcp_server.mcp_context import (
+ mcp_active_toolset_id,
+ mcp_active_toolset_tools_ttl_ms,
+ )
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
global_mcp_server_manager,
)
from litellm.proxy._experimental.mcp_server.server import (
handle_streamable_http_mcp,
- mcp_active_toolset_id,
)
if prisma_client is None:
@@ -21843,9 +21846,11 @@ async def toolset_mcp_route(toolset_name: str, request: Request):
scope: Final = {**request.scope, "_original_path": request.scope.get("path", ""), "path": "/mcp"}
token: Final = mcp_active_toolset_id.set(toolset.toolset_id)
+ ttl_token: Final = mcp_active_toolset_tools_ttl_ms.set(toolset.tools_ttl_ms)
try:
return await _stream_mcp_asgi_response(handle_streamable_http_mcp, scope, request.receive)
finally:
+ mcp_active_toolset_tools_ttl_ms.reset(ttl_token)
mcp_active_toolset_id.reset(token)
except HTTPException as e:
@@ -21987,9 +21992,12 @@ async def dynamic_mcp_route(mcp_server_name: str, request: Request):
# 3. Toolset name (cached)
if prisma_client is not None:
+ from litellm.proxy._experimental.mcp_server.mcp_context import (
+ mcp_active_toolset_id,
+ mcp_active_toolset_tools_ttl_ms,
+ )
from litellm.proxy._experimental.mcp_server.server import (
handle_streamable_http_mcp,
- mcp_active_toolset_id,
)
toolset: Final = await global_mcp_server_manager.get_toolset_by_name_cached(prisma_client, mcp_server_name)
@@ -21998,9 +22006,11 @@ async def dynamic_mcp_route(mcp_server_name: str, request: Request):
scope["_original_path"] = scope.get("path", "")
scope["path"] = "/mcp"
token: Final = mcp_active_toolset_id.set(toolset.toolset_id)
+ ttl_token: Final = mcp_active_toolset_tools_ttl_ms.set(toolset.tools_ttl_ms)
try:
return await _stream_mcp_asgi_response(handle_streamable_http_mcp, scope, request.receive)
finally:
+ mcp_active_toolset_tools_ttl_ms.reset(ttl_token)
mcp_active_toolset_id.reset(token)
# 4. MCP access group tag (cached)
diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma
index 83a0e6f9e05..b0171d6fced 100644
--- a/litellm/proxy/schema.prisma
+++ b/litellm/proxy/schema.prisma
@@ -367,6 +367,7 @@ model LiteLLM_MCPServerTable {
instructions String?
url String?
spec_path String?
+ tools_ttl_ms Int?
transport String @default("sse")
auth_type String?
credentials Json? @default("{}")
@@ -434,6 +435,7 @@ model LiteLLM_MCPToolsetTable {
toolset_id String @id @default(uuid())
toolset_name String @unique
description String?
+ tools_ttl_ms Int?
tools Json @default("[]") // [{server_id: string, tool_name: string}]
created_at DateTime @default(now())
created_by String?
diff --git a/litellm/types/mcp_server/mcp_server_manager.py b/litellm/types/mcp_server/mcp_server_manager.py
index d29e4db55a4..b389583139a 100644
--- a/litellm/types/mcp_server/mcp_server_manager.py
+++ b/litellm/types/mcp_server/mcp_server_manager.py
@@ -100,6 +100,7 @@ class MCPServer(LiteLLMBaseModel):
transport: MCPTransportType
protocol_version: MCPUpstreamProtocol = "auto"
spec_path: str | None = None
+ tools_ttl_ms: int | None = Field(default=None, ge=0)
auth_type: MCPAuthType | None = None
authentication_token: str | None = None
instructions: str | None = None
diff --git a/litellm/types/mcp_server/mcp_toolset.py b/litellm/types/mcp_server/mcp_toolset.py
index 2eab0af161f..bee079d585f 100644
--- a/litellm/types/mcp_server/mcp_toolset.py
+++ b/litellm/types/mcp_server/mcp_toolset.py
@@ -15,6 +15,7 @@ class MCPToolset(LiteLLMBaseModel):
toolset_id: str
toolset_name: str
description: str | None = None
+ tools_ttl_ms: int | None = Field(default=None, ge=0)
tools: list[MCPToolsetTool] = Field(default=[])
created_at: datetime | None = None
created_by: str | None = None
@@ -25,6 +26,7 @@ class MCPToolset(LiteLLMBaseModel):
class NewMCPToolsetRequest(LiteLLMBaseModel):
toolset_name: str
description: str | None = None
+ tools_ttl_ms: int | None = Field(default=None, ge=0)
tools: list[MCPToolsetTool] = Field(default=[])
@@ -32,4 +34,5 @@ class UpdateMCPToolsetRequest(LiteLLMBaseModel):
toolset_id: str
toolset_name: str | None = None
description: str | None = None
+ tools_ttl_ms: int | None = Field(default=None, ge=0)
tools: list[MCPToolsetTool] | None = None
diff --git a/litellm/types/mcp_server/tool_registry.py b/litellm/types/mcp_server/tool_registry.py
index 738d37c9503..c7079511cf2 100644
--- a/litellm/types/mcp_server/tool_registry.py
+++ b/litellm/types/mcp_server/tool_registry.py
@@ -13,6 +13,8 @@ class MCPTool(LiteLLMBaseModel):
input_schema: dict[str, Any]
handler: Callable
server_id: str | None = Field(default=None, frozen=True)
+ output_schema: dict[str, object] | None = None # mutable-ok: SDK tools require a dict-shaped output schema
+ title: str | None = None
class ToolSchema(LiteLLMBaseModel):
diff --git a/schema.prisma b/schema.prisma
index 83a0e6f9e05..b0171d6fced 100644
--- a/schema.prisma
+++ b/schema.prisma
@@ -367,6 +367,7 @@ model LiteLLM_MCPServerTable {
instructions String?
url String?
spec_path String?
+ tools_ttl_ms Int?
transport String @default("sse")
auth_type String?
credentials Json? @default("{}")
@@ -434,6 +435,7 @@ model LiteLLM_MCPToolsetTable {
toolset_id String @id @default(uuid())
toolset_name String @unique
description String?
+ tools_ttl_ms Int?
tools Json @default("[]") // [{server_id: string, tool_name: string}]
created_at DateTime @default(now())
created_by String?
diff --git a/tests/code_coverage_tests/recursive_detector.py b/tests/code_coverage_tests/recursive_detector.py
index a5bb5e0b340..2dcf2082a06 100644
--- a/tests/code_coverage_tests/recursive_detector.py
+++ b/tests/code_coverage_tests/recursive_detector.py
@@ -2,6 +2,7 @@ import ast
import os
IGNORE_FUNCTIONS = [
+ "_normalize_openapi_nullable_schema", # input bounded by MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES.
"_json_cost", # bounded at depth 32 and consumed under byte/node limits.
"_format_type",
"remove_additional_properties",
diff --git a/tests/unit/proxy/_experimental/mcp_server/test_catalog.py b/tests/unit/proxy/_experimental/mcp_server/test_catalog.py
index 4f6530e5de1..abfecbd269f 100644
--- a/tests/unit/proxy/_experimental/mcp_server/test_catalog.py
+++ b/tests/unit/proxy/_experimental/mcp_server/test_catalog.py
@@ -723,6 +723,54 @@ async def test_tool_catalog_preserves_upstream_freshness() -> None:
assert result.cache_scope == "private"
+@pytest.mark.asyncio
+async def test_toolset_ttl_overrides_complete_listing_and_keeps_private_cache_scope(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from litellm.proxy._experimental.mcp_server import operations
+ from litellm.proxy._experimental.mcp_server.faults.list_outcomes import AggregateToolListing
+
+ listing_result: Final = AggregateToolListing(
+ tools=[],
+ outcomes={"server": ServerListOk(tool_count=0)},
+ ttl_ms=9000,
+ )
+ monkeypatch.setattr(operations, "_list_mcp_tools", AsyncMock(return_value=listing_result))
+ result: Final = await catalog.list_gateway_tools(
+ operations.prepare_context(toolset_tools_ttl_ms=0),
+ PaginatedRequestParams(),
+ log_list_tools_to_spendlogs=False,
+ )
+
+ assert result.ttl_ms == 0
+ assert result.model_dump(mode="json", by_alias=True, exclude_none=True)["ttlMs"] == 0
+ assert result.cache_scope == "private"
+
+
+@pytest.mark.asyncio
+async def test_toolset_ttl_does_not_override_partial_listing(monkeypatch: pytest.MonkeyPatch) -> None:
+ from litellm.proxy._experimental.mcp_server import operations
+ from litellm.proxy._experimental.mcp_server.faults.list_outcomes import AggregateToolListing, ServerListFault
+
+ listing_result: Final = AggregateToolListing(
+ tools=[],
+ outcomes={
+ "healthy": ServerListOk(tool_count=0),
+ "failed": ServerListFault(tag="timeout"),
+ },
+ ttl_ms=0,
+ )
+ monkeypatch.setattr(operations, "_list_mcp_tools", AsyncMock(return_value=listing_result))
+ result: Final = await catalog.list_gateway_tools(
+ operations.prepare_context(toolset_tools_ttl_ms=9000),
+ PaginatedRequestParams(),
+ log_list_tools_to_spendlogs=False,
+ )
+
+ assert result.ttl_ms == 0
+ assert result.cache_scope == "private"
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize("upstream_ttl,limit,expected_ttl", [(1000, 60, 1000), (90000, 1, 1000), (0, 60, 0)])
async def test_discovery_cache_uses_upstream_freshness_and_configured_cap(
diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_partial_update.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_partial_update.py
index d6894979906..1d99fd80e54 100644
--- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_partial_update.py
+++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_partial_update.py
@@ -90,6 +90,13 @@ async def test_partial_update_omits_unset_defaultful_fields():
)
+@pytest.mark.asyncio
+async def test_server_ttl_update_sets_clears_and_omits():
+ assert (await _run_update(UpdateMCPServerRequest(server_id="s", tools_ttl_ms=2400)))["tools_ttl_ms"] == 2400
+ assert (await _run_update(UpdateMCPServerRequest(server_id="s", tools_ttl_ms=None)))["tools_ttl_ms"] is None
+ assert "tools_ttl_ms" not in await _run_update(UpdateMCPServerRequest(server_id="s", allowed_tools=["tool"]))
+
+
@pytest.mark.asyncio
async def test_partial_update_null_tool_name_maps_clear_to_empty_json():
"""Explicit null on Json map fields must clear overrides (UI legacy)."""
@@ -900,6 +907,38 @@ async def test_toolset_partial_update_clears_description_on_explicit_null():
assert await _run_toolset_update({"toolset_id": "ts-1", "description": None}) == {"description": None}
+@pytest.mark.asyncio
+async def test_toolset_partial_update_persists_zero_ttl_and_clears_null_ttl():
+ assert await _run_toolset_update({"toolset_id": "ts-1", "tools_ttl_ms": 0}) == {"tools_ttl_ms": 0}
+ assert await _run_toolset_update({"toolset_id": "ts-1", "tools_ttl_ms": None}) == {"tools_ttl_ms": None}
+
+
+@pytest.mark.asyncio
+async def test_toolset_ttl_create_update_and_omission():
+ from litellm.proxy._experimental.mcp_server.toolset_db import create_mcp_toolset
+ from litellm.types.mcp_server.mcp_toolset import NewMCPToolsetRequest
+
+ mock_prisma = _mock_toolset_prisma()
+ created_row = MagicMock()
+ created_row.model_dump.return_value = {
+ "toolset_id": "ts-1",
+ "toolset_name": "ops",
+ "tools_ttl_ms": 1200,
+ "tools": "[]",
+ }
+ mock_prisma.db.litellm_mcptoolsettable.create = AsyncMock(return_value=created_row)
+
+ created = await create_mcp_toolset(
+ mock_prisma,
+ NewMCPToolsetRequest(toolset_name="ops", tools=[], tools_ttl_ms=1200),
+ "test-user",
+ )
+ assert mock_prisma.db.litellm_mcptoolsettable.create.call_args.kwargs["data"]["tools_ttl_ms"] == 1200
+ assert created.tools_ttl_ms == 1200
+ assert await _run_toolset_update({"toolset_id": "ts-1", "tools_ttl_ms": 2400}) == {"tools_ttl_ms": 2400}
+ assert await _run_toolset_update({"toolset_id": "ts-1"}) == {}
+
+
@pytest.mark.asyncio
async def test_toolset_partial_update_omits_the_fields_the_caller_left_out():
tools = [{"server_id": "s1", "tool_name": "alpha"}]
diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server.py
index de711d737d0..cd861229005 100644
--- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server.py
+++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server.py
@@ -981,6 +981,7 @@ async def test_get_tools_from_mcp_servers():
proxy_logging_obj=None,
catalog_auth_header=None,
record_listing=True,
+ wire_compat=None,
):
if server.server_id == "server1_id":
return [mock_tool_1]
diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py
index ecd08e17cda..cab8a0845e7 100644
--- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py
+++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_manager.py
@@ -1077,6 +1077,42 @@ class TestMCPServerManager:
assert server.alias == "friendly_alias"
assert server.server_name == "validserver"
+ @pytest.mark.asyncio
+ async def test_load_servers_from_config_preserves_openapi_display_name_overrides(
+ self, config_only_mcp_manager_factory, tmp_path
+ ):
+ manager = config_only_mcp_manager_factory()
+ spec_path = tmp_path / "petstore.json"
+ spec_path.write_text(
+ json.dumps(
+ {
+ "openapi": "3.0.0",
+ "paths": {
+ "/pets/{petId}": {
+ "get": {
+ "operationId": "getPetById",
+ "summary": "Find pet by ID",
+ "responses": {"200": {"description": "Success"}},
+ }
+ }
+ },
+ }
+ )
+ )
+
+ await manager.load_servers_from_config(
+ {
+ "petstore": {
+ "url": "https://petstore.test",
+ "spec_path": str(spec_path),
+ "tool_name_to_display_name": {"getPetById": "Get Pet"},
+ }
+ }
+ )
+
+ server: Final = next(iter(manager.config_mcp_servers.values()))
+ assert server.tool_name_to_display_name == {"getPetById": "Get Pet"}
+
def _oauth2_config(self, **overrides):
base = {
"url": "https://example.com/mcp",
@@ -16864,6 +16900,174 @@ async def test_openapi_listing_finds_tools_registered_under_the_normalized_prefi
assert [t.name for t in listed] == ["list"]
+@pytest.mark.asyncio
+@pytest.mark.parametrize(("configured_ttl", "expected_ttl"), ((0, 0), (2500, 2500), (None, 0)))
+async def test_openapi_listing_uses_configured_tools_ttl(configured_ttl: int | None, expected_ttl: int) -> None:
+ from litellm.proxy._experimental.mcp_server.tool_registry import global_mcp_tool_registry
+
+ manager: Final = MCPServerManager()
+ manager.create_mcp_client = AsyncMock(return_value=AsyncMock())
+ global_mcp_tool_registry.unregister_tools_with_prefix("pet-")
+ _register_local_tool("pet-list", "Pet tool")
+ server: Final = _openapi_server("pet").model_copy(update={"tools_ttl_ms": configured_ttl})
+ try:
+ listed: Final = await manager.get_tools_page(server=server, add_prefix=False)
+ finally:
+ global_mcp_tool_registry.unregister_tools_with_prefix("pet-")
+
+ assert listed.ttl_ms == expected_ttl
+ assert listed.model_dump(mode="json", by_alias=True, exclude_none=True)["ttlMs"] == expected_ttl
+
+
+@pytest.mark.asyncio
+async def test_openapi_listing_serializes_metadata_only_for_modern_revision() -> None:
+ from litellm.proxy._experimental.mcp_server.tool_registry import global_mcp_tool_registry
+ from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
+
+ manager: Final = MCPServerManager()
+ manager.create_mcp_client = AsyncMock(return_value=AsyncMock())
+ global_mcp_tool_registry.unregister_tools_with_prefix("pet-")
+
+ async def handler(**kwargs: object) -> None:
+ return None
+
+ global_mcp_tool_registry.register_tool(
+ name="pet-list",
+ description="Pet tool",
+ input_schema={"type": "object"},
+ handler=handler,
+ output_schema={"type": "object", "properties": {"count": {"type": "integer"}}},
+ title="List pets",
+ )
+ try:
+ modern: Final = await manager.get_tools_page(
+ server=_openapi_server("pet"), add_prefix=False, wire_compat=WireCompat.MODERN
+ )
+ legacy: Final = await manager.get_tools_page(
+ server=_openapi_server("pet"), add_prefix=False, wire_compat=WireCompat.LEGACY
+ )
+ finally:
+ global_mcp_tool_registry.unregister_tools_with_prefix("pet-")
+
+ modern_wire: Final = modern.model_dump(mode="json", by_alias=True, exclude_none=True)
+ legacy_wire: Final = legacy.model_dump(mode="json", by_alias=True, exclude_none=True)
+ assert modern_wire["tools"][0]["title"] == "List pets"
+ assert modern_wire["tools"][0]["outputSchema"] == {
+ "type": "object",
+ "properties": {"count": {"type": "integer"}},
+ }
+ assert "title" not in legacy_wire["tools"][0]
+ assert "outputSchema" not in legacy_wire["tools"][0]
+
+
+@pytest.mark.asyncio
+async def test_manager_openapi_registration_lists_response_metadata_for_modern_revision(tmp_path: Path) -> None:
+ from litellm.proxy._experimental.mcp_server.tool_registry import global_mcp_tool_registry
+ from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
+
+ spec_path: Final = tmp_path / "openapi.json"
+ spec_path.write_text(
+ json.dumps(
+ {
+ "openapi": "3.0.0",
+ "info": {"title": "Demo", "version": "1.0.0"},
+ "components": {
+ "schemas": {
+ "Pet": {
+ "type": "object",
+ "properties": {"owner": {"$ref": "#/components/schemas/Owner"}},
+ },
+ "Owner": {"type": "object", "properties": {"name": {"type": "string"}}},
+ }
+ },
+ "paths": {
+ "/pets": {
+ "get": {
+ "operationId": "list_pets",
+ "summary": "List pets",
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {"$ref": "#/components/schemas/Pet"},
+ }
+ }
+ }
+ },
+ }
+ }
+ },
+ }
+ )
+ )
+ server: Final = _openapi_server("pet").model_copy(update={"spec_path": str(spec_path)})
+ manager: Final = MCPServerManager()
+ manager.create_mcp_client = AsyncMock(return_value=AsyncMock())
+ global_mcp_tool_registry.unregister_tools_with_prefix("pet-")
+
+ try:
+ await manager._register_openapi_tools(str(spec_path), server, "https://example.com")
+ modern: Final = await manager.get_tools_page(server=server, add_prefix=False, wire_compat=WireCompat.MODERN)
+ legacy: Final = await manager.get_tools_page(server=server, add_prefix=False, wire_compat=WireCompat.LEGACY)
+ finally:
+ global_mcp_tool_registry.unregister_tools_with_prefix("pet-")
+
+ modern_wire: Final = modern.model_dump(mode="json", by_alias=True, exclude_none=True)
+ legacy_wire: Final = legacy.model_dump(mode="json", by_alias=True, exclude_none=True)
+ assert modern_wire["tools"][0]["outputSchema"] == {
+ "type": "object",
+ "properties": {"owner": {"type": "object", "properties": {"name": {"type": "string"}}}},
+ }
+ assert modern_wire["tools"][0]["title"] == "List pets"
+ assert "outputSchema" not in legacy_wire["tools"][0]
+ assert "title" not in legacy_wire["tools"][0]
+
+
+@pytest.mark.asyncio
+async def test_toolset_name_cache_round_trips_configured_tools_ttl(monkeypatch: pytest.MonkeyPatch) -> None:
+ from litellm.proxy._experimental.mcp_server import toolset_db
+ from litellm.types.mcp_server.mcp_toolset import MCPToolset
+
+ cache: Final = DualCache()
+ toolset: Final = MCPToolset(toolset_id="ttl-toolset", toolset_name="ttl-toolset", tools_ttl_ms=0)
+ fetch: Final = AsyncMock(return_value=toolset)
+ monkeypatch.setattr(proxy_server, "user_api_key_cache", cache)
+ monkeypatch.setattr(toolset_db, "get_mcp_toolset_by_name", fetch)
+ manager: Final = MCPServerManager()
+
+ first: Final = await manager.get_toolset_by_name_cached(None, "ttl-toolset")
+ second: Final = await manager.get_toolset_by_name_cached(None, "ttl-toolset")
+
+ assert first is not None and first.tools_ttl_ms == 0
+ assert second is not None and second.tools_ttl_ms == 0
+ fetch.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_toolset_name_cache_returns_updated_ttl_after_invalidation(monkeypatch: pytest.MonkeyPatch) -> None:
+ from litellm.proxy._experimental.mcp_server import toolset_db
+ from litellm.types.mcp_server.mcp_toolset import MCPToolset
+
+ cache: Final = DualCache()
+ old_toolset: Final = MCPToolset(toolset_id="ttl-toolset", toolset_name="ttl-toolset", tools_ttl_ms=0)
+ updated_toolset: Final = MCPToolset(toolset_id="ttl-toolset", toolset_name="ttl-toolset", tools_ttl_ms=2400)
+ await cache.async_set_cache(
+ key="toolset_name:ttl-toolset",
+ value=old_toolset.model_dump(mode="json"),
+ ttl=60,
+ )
+ fetch: Final = AsyncMock(return_value=updated_toolset)
+ monkeypatch.setattr(proxy_server, "user_api_key_cache", cache)
+ monkeypatch.setattr(toolset_db, "get_mcp_toolset_by_name", fetch)
+ manager: Final = MCPServerManager()
+
+ manager.invalidate_toolset_cache("ttl-toolset")
+ result: Final = await manager.get_toolset_by_name_cached(None, "ttl-toolset")
+
+ assert result is not None and result.tools_ttl_ms == 2400
+ fetch.assert_awaited_once()
+
+
@pytest.mark.asyncio
async def test_discovery_cache_retries_cancelled_fetches() -> None:
from litellm.proxy._experimental.mcp_server.catalog import _DiscoveryCache
diff --git a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_tool_calls_and_headers.py b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_tool_calls_and_headers.py
index a873e2ab1ae..ca503a94fff 100644
--- a/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_tool_calls_and_headers.py
+++ b/tests/unit/proxy/_experimental/mcp_server/test_mcp_server_tool_calls_and_headers.py
@@ -1018,6 +1018,9 @@ async def test_get_resource_templates_from_mcp_servers_success():
server.server_id = "server-id"
server.auth_type = None
server.extra_headers = None
+ server.spec_path = None
+ server.tools_ttl_ms = None
+ server.tool_name_to_display_name = None
with (
patch(
@@ -4490,6 +4493,9 @@ async def test_list_tools_single_server_unprefixed_names():
server.server_name = "server1"
server.auth_type = None
server.extra_headers = None
+ server.spec_path = None
+ server.tools_ttl_ms = None
+ server.tool_name_to_display_name = None
# Mock manager: allow just one server and return a tool based on add_prefix flag
mock_manager = MagicMock()
@@ -4558,6 +4564,9 @@ async def test_list_tools_multiple_servers_prefixed_names():
server1.server_name = "server1"
server1.auth_type = None
server1.extra_headers = None
+ server1.spec_path = None
+ server1.tools_ttl_ms = None
+ server1.tool_name_to_display_name = None
server2 = MagicMock()
server2.server_id = "server2"
@@ -4568,6 +4577,9 @@ async def test_list_tools_multiple_servers_prefixed_names():
server2.server_name = "server2"
server2.auth_type = None
server2.extra_headers = None
+ server2.spec_path = None
+ server2.tools_ttl_ms = None
+ server2.tool_name_to_display_name = None
# Mock manager
mock_manager = MagicMock()
@@ -4981,6 +4993,9 @@ async def test_list_tools_filters_by_key_team_permissions():
server.server_name = "server1"
server.auth_type = None
server.extra_headers = None
+ server.spec_path = None
+ server.tools_ttl_ms = None
+ server.tool_name_to_display_name = None
# Mock manager
mock_manager = MagicMock()
@@ -5092,6 +5107,9 @@ async def test_list_tools_with_team_tool_permissions_inheritance():
server.server_name = "server1"
server.auth_type = None
server.extra_headers = None
+ server.spec_path = None
+ server.tools_ttl_ms = None
+ server.tool_name_to_display_name = None
# Mock manager
mock_manager = MagicMock()
@@ -5189,6 +5207,9 @@ async def test_list_tools_with_no_tool_permissions_shows_all():
server.server_name = "server1"
server.auth_type = None
server.extra_headers = None
+ server.spec_path = None
+ server.tools_ttl_ms = None
+ server.tool_name_to_display_name = None
# Mock manager
mock_manager = MagicMock()
@@ -5290,6 +5311,9 @@ async def test_list_tools_strips_prefix_when_matching_permissions():
server.server_name = "GITMCP"
server.allowed_tools = None
server.disallowed_tools = None
+ server.spec_path = None
+ server.tools_ttl_ms = None
+ server.tool_name_to_display_name = None
# Mock manager
mock_manager = MagicMock()
@@ -5497,6 +5521,74 @@ def test_apply_display_name_overrides_no_overrides():
assert result[0].description == "Original description"
+def test_apply_display_name_overrides_modern_openapi_preserves_name_and_matches_camel_case() -> None:
+ from mcp.types import Tool
+
+ from litellm.proxy._experimental.mcp_server.operations import apply_display_name_overrides
+ from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
+ from litellm.types.mcp import MCPTransport
+ from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+ mcp_server = MCPServer(
+ server_id="my_api_mcp",
+ name="my_api_mcp",
+ transport=MCPTransport.http,
+ spec_path="https://api.example.com/openapi.json",
+ tool_name_to_display_name={"getPetById": "Get Pet"},
+ )
+ tool = Tool(
+ name="my_api_mcp-getpetbyid",
+ title="Get a pet",
+ description="Original description",
+ inputSchema={"type": "object", "properties": {}},
+ outputSchema={"type": "object"},
+ annotations=None,
+ )
+
+ result = apply_display_name_overrides([tool], mcp_server, wire_compat=WireCompat.MODERN)
+
+ assert result[0].name == tool.name
+ assert result[0].title == "Get Pet"
+ assert tool.title == "Get a pet"
+
+
+def test_resolve_display_name_to_original_sanitizes_openapi_operation_id() -> None:
+ from litellm.proxy._experimental.mcp_server.operations import _resolve_display_name_to_original
+ from litellm.types.mcp import MCPTransport
+ from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+ server = MCPServer(
+ server_id="my_api_mcp",
+ name="my_api_mcp",
+ transport=MCPTransport.http,
+ spec_path="https://api.example.com/openapi.json",
+ tool_name_to_display_name={"getPetById": "Get Pet"},
+ )
+
+ assert _resolve_display_name_to_original("Get Pet", [server]) == "my_api_mcp-getpetbyid"
+
+
+def test_convert_tools_to_mcp_sdk_tool_type_serializes_modern_metadata() -> None:
+ from litellm.proxy._experimental.mcp_server.tool_registry import MCPToolRegistry
+ from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
+ from litellm.types.mcp_server.tool_registry import MCPTool
+
+ tool = MCPTool(
+ name="getpetbyid",
+ description="Get a pet",
+ input_schema={"type": "object"},
+ handler=lambda: None,
+ output_schema={"type": "object", "properties": {"id": {"type": "string"}}},
+ title="Get Pet",
+ )
+
+ serialized = MCPToolRegistry().convert_tools_to_mcp_sdk_tool_type([tool], wire_compat=WireCompat.MODERN)[0]
+
+ wire_value = serialized.model_dump(mode="json", by_alias=True)
+ assert wire_value["outputSchema"] == tool.output_schema
+ assert wire_value["title"] == "Get Pet"
+
+
def _make_db_mcp_server(server_id: str, updated_at: datetime) -> LiteLLM_MCPServerTable:
return LiteLLM_MCPServerTable(
server_id=server_id,
@@ -5832,6 +5924,9 @@ async def test_get_tools_from_mcp_servers_logs_list_tools_to_spendlogs_when_enab
server_a.server_id = "a"
server_a.auth_type = None
server_a.extra_headers = None
+ server_a.spec_path = None
+ server_a.tools_ttl_ms = None
+ server_a.tool_name_to_display_name = None
tool_1 = MCPTool(
name="server_a-tool_1",
@@ -5990,6 +6085,9 @@ async def test_get_tools_from_mcp_servers_returns_tools_when_success_logging_fai
server_a.server_id = "a"
server_a.auth_type = None
server_a.extra_headers = None
+ server_a.spec_path = None
+ server_a.tools_ttl_ms = None
+ server_a.tool_name_to_display_name = None
tool_1 = Tool(name="placeholder", inputSchema={})
tool_1.name = "server_a-tool_1"
@@ -6313,6 +6411,9 @@ async def test_get_tools_from_mcp_servers_injects_stored_oauth2_token():
oauth2_server.server_id = SERVER_ID
oauth2_server.auth_type = MCPAuth.oauth2
oauth2_server.extra_headers = None
+ oauth2_server.spec_path = None
+ oauth2_server.tools_ttl_ms = None
+ oauth2_server.tool_name_to_display_name = None
# Simulate the DB returning a valid credential for this user+server
prefetched_creds = {SERVER_ID: {"access_token": STORED_TOKEN, "server_id": SERVER_ID}}
diff --git a/tests/unit/proxy/_experimental/mcp_server/test_openapi_to_mcp_generator.py b/tests/unit/proxy/_experimental/mcp_server/test_openapi_to_mcp_generator.py
index 9f3db632db1..223649b5366 100644
--- a/tests/unit/proxy/_experimental/mcp_server/test_openapi_to_mcp_generator.py
+++ b/tests/unit/proxy/_experimental/mcp_server/test_openapi_to_mcp_generator.py
@@ -9,6 +9,8 @@ This test suite ensures that:
5. Path parameters are properly URL encoded
"""
+from copy import deepcopy
+from time import perf_counter
from types import SimpleNamespace
from typing import Final
from unittest.mock import AsyncMock, patch
@@ -17,27 +19,346 @@ import pytest
from fastapi import HTTPException
from respx import MockRouter
-from litellm.types.mcp import MCPAuth, MCPAuthType
-
+from litellm import constants
from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import (
- request_auth_header,
- request_extra_headers,
- request_resolved_auth_headers,
+ _OpenAPISpec,
_request_upstream_url,
_resolve_param_list,
_resolve_ref,
build_input_schema,
+ build_output_schema,
create_tool_function,
extract_parameters,
get_base_url,
+ request_auth_header,
+ request_extra_headers,
+ request_resolved_auth_headers,
resolve_operation_params,
)
-from litellm.proxy._experimental.mcp_server.tool_outcome import JsonResult, TextResult
+from litellm.types.mcp import MCPAuth, MCPAuthType
+
+
+def _doubling_openapi_spec(levels: int) -> _OpenAPISpec:
+ schemas: Final = {
+ **{
+ f"Level{index}": {
+ "type": "object",
+ "properties": {
+ "left": {"$ref": f"#/components/schemas/Level{index + 1}"},
+ "right": {"$ref": f"#/components/schemas/Level{index + 1}"},
+ },
+ }
+ for index in range(levels)
+ },
+ f"Level{levels}": {"type": "object", "properties": {"leaf": {"type": "string"}}},
+ }
+ return {
+ "components": {"schemas": schemas},
+ "paths": {
+ "/doubling": {
+ "get": {
+ "operationId": "openapi-budget-doubling",
+ "summary": "Budgeted doubling",
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {"$ref": "#/components/schemas/Level0"},
+ }
+ }
+ }
+ },
+ }
+ }
+ },
+ }
+
+
+def test_build_output_schema_resolves_nested_json_refs_without_mutating_spec() -> None:
+ spec = {
+ "components": {
+ "schemas": {
+ "Pet": {
+ "type": "object",
+ "properties": {"owner": {"$ref": "#/components/schemas/Owner"}},
+ },
+ "Owner": {"type": "object", "properties": {"name": {"type": "string"}}},
+ }
+ }
+ }
+ operation = {
+ "responses": {
+ "201": {"content": {"application/vnd.api+json": {"schema": {"$ref": "#/components/schemas/Pet"}}}},
+ "204": {"content": {"application/json": {"schema": {"type": "string"}}}},
+ }
+ }
+ original = deepcopy(spec)
+
+ result = build_output_schema(operation, spec)
+
+ assert result == {
+ "type": "object",
+ "properties": {
+ "owner": {"type": "object", "properties": {"name": {"type": "string"}}},
+ },
+ }
+ assert spec == original
+
+
+@pytest.mark.asyncio
+async def test_build_output_schema_normalizes_nullable_values_for_sdk_validation() -> None:
+ import anyio
+ from mcp import ClientSession
+ from mcp.shared.message import SessionMessage
+ from mcp.types import CallToolResult, ListToolsResult, TextContent, Tool
+
+ spec = {
+ "components": {
+ "schemas": {
+ "Pet": {
+ "type": "object",
+ "properties": {"tag": {"type": "string", "nullable": True}},
+ },
+ }
+ }
+ }
+ operation = {
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {"$ref": "#/components/schemas/Pet"},
+ }
+ }
+ }
+ }
+ }
+
+ result = build_output_schema(operation, spec)
+
+ assert result is not None
+ send, receive = anyio.create_memory_object_stream[SessionMessage](1)
+ async with send, receive:
+ client = ClientSession(receive, send)
+ client._absorb_tool_listing(
+ ListToolsResult(
+ tools=[
+ Tool(
+ name="get-pet",
+ inputSchema={"type": "object"},
+ outputSchema=result,
+ )
+ ]
+ ),
+ complete=True,
+ )
+ await client.validate_tool_result(
+ "get-pet",
+ CallToolResult(
+ content=[TextContent(type="text", text="{}")],
+ structuredContent={"tag": None},
+ isError=False,
+ ),
+ )
+ assert result == {
+ "type": "object",
+ "properties": {"tag": {"type": ["string", "null"]}},
+ }
+
+
+async def _validate_output_schema_result(
+ output_schema: dict[str, object], structured_content: dict[str, object]
+) -> None:
+ import anyio
+ from mcp import ClientSession
+ from mcp.shared.message import SessionMessage
+ from mcp.types import CallToolResult, ListToolsResult, TextContent, Tool
+
+ send, receive = anyio.create_memory_object_stream[SessionMessage](1)
+ async with send, receive:
+ client = ClientSession(receive, send)
+ client._absorb_tool_listing(
+ ListToolsResult(
+ tools=[
+ Tool(
+ name="get-pet",
+ inputSchema={"type": "object"},
+ outputSchema=output_schema,
+ )
+ ]
+ ),
+ complete=True,
+ )
+ await client.validate_tool_result(
+ "get-pet",
+ CallToolResult(
+ content=[TextContent(type="text", text="{}")],
+ structuredContent=structured_content,
+ isError=False,
+ ),
+ )
+
+
+@pytest.mark.asyncio
+async def test_build_output_schema_normalizes_nullable_allof_ref_for_sdk_validation() -> None:
+ spec = {
+ "components": {
+ "schemas": {
+ "Owner": {"type": "object", "properties": {"name": {"type": "string"}}},
+ "Pet": {
+ "type": "object",
+ "properties": {
+ "owner": {
+ "allOf": [{"$ref": "#/components/schemas/Owner"}],
+ "nullable": True,
+ }
+ },
+ },
+ }
+ }
+ }
+ operation = {
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {"$ref": "#/components/schemas/Pet"},
+ }
+ }
+ }
+ }
+ }
+
+ result = build_output_schema(operation, spec)
+
+ assert result == {
+ "type": "object",
+ "properties": {
+ "owner": {
+ "anyOf": [
+ {
+ "allOf": [
+ {"type": "object", "properties": {"name": {"type": "string"}}},
+ ]
+ },
+ {"type": "null"},
+ ]
+ }
+ },
+ }
+ await _validate_output_schema_result(result, {"owner": None})
+
+
+@pytest.mark.asyncio
+async def test_build_output_schema_normalizes_boolean_exclusive_minimum_for_sdk_validation() -> None:
+ spec = {
+ "components": {
+ "schemas": {
+ "Pet": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "minimum": 0,
+ "exclusiveMinimum": True,
+ }
+ },
+ },
+ }
+ }
+ }
+ operation = {
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {"$ref": "#/components/schemas/Pet"},
+ }
+ }
+ }
+ }
+ }
+
+ result = build_output_schema(operation, spec)
+
+ assert result == {
+ "type": "object",
+ "properties": {"id": {"type": "integer", "exclusiveMinimum": 0}},
+ }
+ await _validate_output_schema_result(result, {"id": 1})
+
+
+@pytest.mark.parametrize(
+ ("response", "expected"),
+ [
+ ({"200": {"content": {"application/json": {"schema": {"type": "array"}}}}}, None),
+ ({"200": {"content": {"text/plain": {"schema": {"type": "object"}}}}}, None),
+ ({"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Missing"}}}}}, None),
+ (
+ {"2XX": {"content": {"application/json": {"schema": {"type": "object", "properties": {}}}}}},
+ {"type": "object", "properties": {}},
+ ),
+ ],
+)
+def test_build_output_schema_rejects_invalid_or_uses_range_response(
+ response: dict[str, object], expected: dict[str, object] | None
+) -> None:
+ assert build_output_schema({"responses": response}, {}) == expected
+
+
+def test_build_output_schema_rejects_cyclic_refs_and_selects_lowest_numeric_2xx() -> None:
+ spec = {
+ "components": {
+ "schemas": {
+ "Cycle": {"type": "object", "properties": {"next": {"$ref": "#/components/schemas/Cycle"}}},
+ }
+ }
+ }
+ operation = {
+ "responses": {
+ "201": {"content": {"application/json": {"schema": {"type": "object", "properties": {}}}}},
+ "204": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Cycle"}}}},
+ }
+ }
+
+ assert build_output_schema(operation, spec) == {"type": "object", "properties": {}}
+ assert (
+ build_output_schema(
+ {"responses": {"200": operation["responses"]["204"]}},
+ spec,
+ )
+ is None
+ )
+
+
+def test_build_output_schema_stops_doubling_chain_within_default_budget(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(constants, "MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES", 10000)
+ spec: Final = _doubling_openapi_spec(20)
+ operation: Final = {
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {"$ref": "#/components/schemas/Level0"},
+ }
+ }
+ }
+ }
+ }
+
+ start: Final = perf_counter()
+ result: Final = build_output_schema(operation, spec)
+ elapsed: Final = perf_counter() - start
+
+ assert result is None
+ assert elapsed < 2.0
+
from litellm.proxy._experimental.mcp_server.exceptions import (
MCPOpenApiUpstreamError,
MCPUpstreamAuthError,
)
+from litellm.proxy._experimental.mcp_server.tool_outcome import JsonResult, TextResult
GET_ASYNC_CLIENT_TARGET = "litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator.get_async_httpx_client"
@@ -1114,6 +1435,80 @@ class TestSanitizeOpenAPIToolName:
class TestRegisterToolsFromOpenAPI:
"""Verify register_tools_from_openapi emits provider-safe tool names."""
+ def test_registration_passes_openapi_response_schema_and_summary(self) -> None:
+ from litellm.proxy._experimental.mcp_server import openapi_to_mcp_generator
+ from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
+
+ registry: Final = openapi_to_mcp_generator.global_mcp_tool_registry
+ tool_prefix: Final = "litellm9923-"
+ registry.unregister_tools_with_prefix(tool_prefix)
+
+ output_schema: Final = {"type": "object", "properties": {"pets": {"type": "array"}}}
+ spec: Final = {
+ "paths": {
+ "/pets": {
+ "get": {
+ "operationId": f"{tool_prefix}list-pets",
+ "summary": "List pets",
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {"schema": output_schema},
+ }
+ }
+ },
+ }
+ }
+ }
+ }
+ try:
+ openapi_to_mcp_generator.register_tools_from_openapi(spec, base_url="https://api.example.com")
+ registered: Final = registry.list_tools(tool_prefix=tool_prefix)
+ sdk_tools: Final = registry.convert_tools_to_mcp_sdk_tool_type(registered, wire_compat=WireCompat.MODERN)
+ wire_tool: Final = sdk_tools[0].model_dump(mode="json", by_alias=True, exclude_none=True)
+ finally:
+ registry.unregister_tools_with_prefix(tool_prefix)
+
+ assert wire_tool["name"] == "litellm9923-list-pets"
+ assert wire_tool["outputSchema"] == output_schema
+ assert wire_tool["title"] == "List pets"
+
+ def test_schema_budget_keeps_registered_tool_name_and_title(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from litellm.proxy._experimental.mcp_server import openapi_to_mcp_generator
+ from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
+
+ monkeypatch.setattr(constants, "MCP_OPENAPI_OUTPUT_SCHEMA_MAX_NODES", 50)
+ spec: Final = _doubling_openapi_spec(7)
+ operation: Final = {
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {"$ref": "#/components/schemas/Level0"},
+ }
+ }
+ }
+ }
+ }
+ assert build_output_schema(operation, spec) is None
+
+ registry: Final = openapi_to_mcp_generator.global_mcp_tool_registry
+ tool_prefix: Final = "openapi-budget-"
+ registry.unregister_tools_with_prefix(tool_prefix)
+ try:
+ openapi_to_mcp_generator.register_tools_from_openapi(spec, base_url="https://api.example.com")
+ registered: Final = registry.list_tools(tool_prefix=tool_prefix)
+ sdk_tools: Final = registry.convert_tools_to_mcp_sdk_tool_type(registered, wire_compat=WireCompat.MODERN)
+ wire_tool: Final = sdk_tools[0].model_dump(mode="json", by_alias=True, exclude_none=True)
+ registered_tool: Final = registered[0]
+ finally:
+ registry.unregister_tools_with_prefix(tool_prefix)
+
+ assert registered_tool.output_schema is None
+ assert wire_tool["name"] == "openapi-budget-doubling"
+ assert wire_tool["title"] == "Budgeted doubling"
+ assert "outputSchema" not in wire_tool
+
def test_github_style_operation_ids_are_sanitized(self, monkeypatch):
import re
@@ -1121,7 +1516,7 @@ class TestRegisterToolsFromOpenAPI:
registered: list = []
- def _capture(name, description, input_schema, handler): # noqa: ANN001
+ def _capture(name, description, input_schema, handler, **kwargs): # noqa: ANN001
registered.append(name)
monkeypatch.setattr(
@@ -1169,7 +1564,7 @@ class TestRegisterToolsFromOpenAPI:
registered: list = []
- def _capture(name, description, input_schema, handler): # noqa: ANN001
+ def _capture(name, description, input_schema, handler, **kwargs): # noqa: ANN001
registered.append(name)
monkeypatch.setattr(
@@ -1572,6 +1967,7 @@ class TestBoundedOpenAPISpecLoading:
@pytest.mark.parametrize("headers", [{"content-length": "1000000"}, {"content-encoding": "gzip"}])
async def test_unsafe_response_headers_reject_before_reading(self, respx_mock, monkeypatch, headers):
import httpx
+
from litellm.llms.custom_httpx.http_handler import HTTPResponseLimitError
from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import (
load_openapi_spec_async,
@@ -1596,6 +1992,7 @@ class TestBoundedOpenAPISpecLoading:
@pytest.mark.asyncio
async def test_chunked_response_is_bounded_and_closed(self, respx_mock, monkeypatch):
import httpx
+
from litellm.llms.custom_httpx.http_handler import HTTPResponseLimitError
from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import (
load_openapi_spec_async,
diff --git a/tests/unit/proxy/_experimental/mcp_server/test_operations.py b/tests/unit/proxy/_experimental/mcp_server/test_operations.py
index 6f7437c90dc..56e78e6b094 100644
--- a/tests/unit/proxy/_experimental/mcp_server/test_operations.py
+++ b/tests/unit/proxy/_experimental/mcp_server/test_operations.py
@@ -368,24 +368,32 @@ async def test_legacy_adapter_cleans_context_after_cancelled_operation():
from types import SimpleNamespace
from litellm.proxy._experimental.mcp_server import server
- from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
+ from litellm.proxy._experimental.mcp_server.mcp_context import (
+ active_mcp_request_ctx_var,
+ mcp_active_toolset_tools_ttl_ms,
+ )
previous_session = server.active_mcp_session_var.get()
previous_request = active_mcp_request_ctx_var.get()
+ ttl_token = mcp_active_toolset_tools_ttl_ms.set(1200)
request = SimpleNamespace(session=object(), protocol_version="2025-06-18", method="tools/call")
auth = (None, None, None, None, None, None, None)
async def cancelled_operation():
- async with server._legacy_operation_context(request, trace=False):
+ async with server._legacy_operation_context(request, trace=False) as context:
assert server.active_mcp_session_var.get() is request.session
assert active_mcp_request_ctx_var.get() is request
+ assert context.toolset_tools_ttl_ms == 1200
raise asyncio.CancelledError
- with patch(
- "litellm.proxy._experimental.mcp_server.server.get_or_extract_auth_context", AsyncMock(return_value=auth)
- ):
- with pytest.raises(asyncio.CancelledError):
- await cancelled_operation()
+ try:
+ with patch(
+ "litellm.proxy._experimental.mcp_server.server.get_or_extract_auth_context", AsyncMock(return_value=auth)
+ ):
+ with pytest.raises(asyncio.CancelledError):
+ await cancelled_operation()
+ finally:
+ mcp_active_toolset_tools_ttl_ms.reset(ttl_token)
assert server.active_mcp_session_var.get() is previous_session
assert active_mcp_request_ctx_var.get() is previous_request
@@ -705,6 +713,68 @@ async def test_tools_call_warmup_does_not_consume_mcp_server_rpm() -> None:
assert [tool.name for tool in listing.tools] == ["echo"]
+@pytest.mark.asyncio
+async def test_modern_protocol_metadata_survives_tool_listing_context_rebuild(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from mcp.types import ListToolsResult
+
+ from litellm.proxy import proxy_server
+ from litellm.proxy._experimental.mcp_server.mcp_server_manager import MCPServerManager
+ from litellm.proxy._experimental.mcp_server.tool_outcome import WireCompat
+
+ server: Final = MCPServer(
+ server_id="wire-compat-openapi",
+ name="petstore",
+ server_name="petstore",
+ transport=MCPTransport.http,
+ url="http://petstore.test",
+ spec_path="petstore.json",
+ tool_name_to_display_name={"getPetById": "Get Pet"},
+ )
+ output_schema: Final[dict[str, object]] = {
+ "type": "object",
+ "properties": {"name": {"type": "string"}},
+ }
+ manager: Final = MCPServerManager()
+ manager.config_mcp_servers = {server.server_id: server}
+ get_tools_page: Final = AsyncMock(
+ return_value=ListToolsResult(
+ tools=[
+ MCPTool(
+ name="petstore-getpetbyid",
+ description="Find pet by ID",
+ inputSchema={"type": "object"},
+ outputSchema=output_schema,
+ title="Find pet by ID",
+ )
+ ]
+ )
+ )
+ monkeypatch.setattr(proxy_server, "prisma_client", None)
+ monkeypatch.setattr(operations, "global_mcp_server_manager", manager)
+ monkeypatch.setattr(
+ operations,
+ "_get_allowed_mcp_servers",
+ AsyncMock(return_value=[server]),
+ )
+ monkeypatch.setattr(manager, "get_tools_page", get_tools_page)
+
+ listing: Final = await operations._get_tools_from_mcp_servers(
+ user_api_key_auth=None,
+ mcp_auth_header=None,
+ mcp_servers=[server.server_id],
+ protocol_version="2026-07-28",
+ enforce_rate_limits=False,
+ )
+
+ listed_tool: Final = listing.tools[0].model_dump(by_alias=True, exclude_none=True)
+ assert get_tools_page.await_args.kwargs["wire_compat"] is WireCompat.MODERN
+ assert listed_tool["name"] == "petstore-getpetbyid"
+ assert listed_tool["title"] == "Get Pet"
+ assert listed_tool["outputSchema"] == output_schema
+
+
def _scoped_rig(
monkeypatch: pytest.MonkeyPatch,
) -> tuple[MCPServer, MCPServer, AsyncMock, AsyncMock]:
diff --git a/tests/unit/proxy/_experimental/mcp_server/test_rest_endpoints.py b/tests/unit/proxy/_experimental/mcp_server/test_rest_endpoints.py
index 73e248ff52e..b1464f62164 100644
--- a/tests/unit/proxy/_experimental/mcp_server/test_rest_endpoints.py
+++ b/tests/unit/proxy/_experimental/mcp_server/test_rest_endpoints.py
@@ -4288,7 +4288,9 @@ class TestPreviewOpenAPITools:
)
class _StubRegistry:
- def register_tool(self, name, description, input_schema, handler): # noqa: ANN001
+ def register_tool(
+ self, name, description, input_schema, handler, output_schema=None, title=None
+ ): # noqa: ANN001
registered_summary_to_name[description] = name
monkeypatch.setattr(
diff --git a/tests/unit/responses/mcp/test_litellm_proxy_mcp_handler.py b/tests/unit/responses/mcp/test_litellm_proxy_mcp_handler.py
index 26553558298..e07e21402eb 100644
--- a/tests/unit/responses/mcp/test_litellm_proxy_mcp_handler.py
+++ b/tests/unit/responses/mcp/test_litellm_proxy_mcp_handler.py
@@ -345,6 +345,7 @@ async def test_execute_tool_calls_reverse_maps_display_name(monkeypatch):
server_id="other-server-id",
short_prefix=None,
mcp_info=None,
+ spec_path=None,
tool_name_to_display_name={"search": "search_docs"},
)
fake_server = types.SimpleNamespace(
@@ -353,6 +354,7 @@ async def test_execute_tool_calls_reverse_maps_display_name(monkeypatch):
server_id="test-server-id",
short_prefix=None,
mcp_info=None,
+ spec_path=None,
tool_name_to_display_name={"read_wiki_structure": "browse_repo_docs"},
)
from litellm.proxy._experimental.mcp_server import mcp_server_manager as _msm
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.integration.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.integration.test.tsx
index 65656a053ce..cb8a64f04a9 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.integration.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.integration.test.tsx
@@ -123,6 +123,14 @@ describe("CreateMCPServer", () => {
expect(screen.getByText("Add New MCP Server")).toBeInTheDocument();
});
+ it("shows the tools list TTL input only for OpenAPI transport", async () => {
+ render();
+
+ expect(screen.queryByLabelText("Tools list TTL (ms)")).not.toBeInTheDocument();
+ await selectOption("Transport Type", "OpenAPI Spec");
+ expect(screen.getByLabelText("Tools list TTL (ms)")).toBeInTheDocument();
+ });
+
// The modal DOES render for a non-admin; it retitles and routes the submit to the review endpoint.
// The assertion this replaced only checked that the admin title was absent, which passed for the
// wrong reason and left the whole non-admin submission path uncovered.
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.tsx
index 07618abb9a4..eac03faf0fa 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/CreateMCPServer.tsx
@@ -838,6 +838,30 @@ const CreateMCPServer: React.FC = ({
)}
+ {transportType === TRANSPORT.OPENAPI && (
+
+ Tools list TTL (ms)
+
+
+
+
+ }
+ name="tools_ttl_ms"
+ >
+ {(control) => (
+
+ )}
+
+ )}
+
{/* Authentication - show for HTTP, SSE, and OpenAPI */}
{transportType !== "stdio" && transportType !== "" && (
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.integration.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.integration.test.tsx
index 81462c6bf9b..0e923d5f61e 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.integration.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.integration.test.tsx
@@ -73,14 +73,17 @@ describe("MCPToolsetsTab create/edit toolset form", () => {
target: { value: "github-linear-tools" },
});
fireEvent.change(dialog.getByPlaceholderText("Optional description"), { target: { value: "tools for triage" } });
+ fireEvent.change(screen.getByLabelText("Tools list TTL (ms)"), { target: { value: "0" } });
await user.click(dialog.getByRole("button", { name: "Create Toolset" }));
+ const expectedCreate = {
+ toolset_name: "github-linear-tools",
+ description: "tools for triage",
+ tools_ttl_ms: 0,
+ tools: [],
+ };
await waitFor(() => {
- expect(networking.createMCPToolset).toHaveBeenCalledWith("sk-test", {
- toolset_name: "github-linear-tools",
- description: "tools for triage",
- tools: [],
- });
+ expect(networking.createMCPToolset).toHaveBeenCalledWith("sk-test", expectedCreate);
});
expect(networking.createMCPToolset).toHaveBeenCalledTimes(1);
});
@@ -146,6 +149,7 @@ describe("MCPToolsetsTab create/edit toolset form", () => {
toolset_id: "ts-1",
toolset_name: "existing",
description: "old description",
+ tools_ttl_ms: 2000,
tools: [{ server_id: "srv-1", tool_name: "search" }],
} as MCPToolset;
renderTab([toolset]);
@@ -155,6 +159,7 @@ describe("MCPToolsetsTab create/edit toolset form", () => {
expect(name).toBe(dialog.getByPlaceholderText("e.g. github-linear-tools"));
expect(dialog.getByText("Toolset Name")).toBeInTheDocument();
expect(dialog.getByPlaceholderText("Optional description")).toHaveValue("old description");
+ expect(dialog.getByLabelText("Tools list TTL (ms)")).toHaveValue(2000);
await user.clear(name);
fireEvent.change(name, { target: { value: "renamed" } });
@@ -171,6 +176,90 @@ describe("MCPToolsetsTab create/edit toolset form", () => {
});
});
+ it("sends null when the toolset tools list TTL is cleared", async () => {
+ const user = setup();
+ vi.mocked(networking.updateMCPToolset).mockResolvedValue(
+ {} as Awaited>,
+ );
+ renderTab([
+ {
+ toolset_id: "ts-1",
+ toolset_name: "existing",
+ tools_ttl_ms: 2000,
+ tools: [],
+ } as MCPToolset,
+ ]);
+
+ await openEditFor(user);
+ fireEvent.change(screen.getByLabelText("Tools list TTL (ms)"), { target: { value: "" } });
+ await user.click(screen.getByRole("button", { name: "Save Changes" }));
+
+ await waitFor(() => {
+ expect(networking.updateMCPToolset).toHaveBeenCalledWith(
+ "sk-test",
+ expect.objectContaining({ toolset_id: "ts-1", tools_ttl_ms: null }),
+ );
+ });
+ });
+
+ it("updates a changed toolset tools list TTL", async () => {
+ const user = setup();
+ vi.mocked(networking.updateMCPToolset).mockResolvedValue(
+ {} as Awaited>,
+ );
+ renderTab([
+ {
+ toolset_id: "ts-1",
+ toolset_name: "existing",
+ tools_ttl_ms: 2000,
+ tools: [],
+ } as MCPToolset,
+ ]);
+
+ await openEditFor(user);
+ fireEvent.change(screen.getByLabelText("Tools list TTL (ms)"), { target: { value: "3500" } });
+ await user.click(screen.getByRole("button", { name: "Save Changes" }));
+
+ await waitFor(() => {
+ expect(networking.updateMCPToolset).toHaveBeenCalledWith(
+ "sk-test",
+ expect.objectContaining({ toolset_id: "ts-1", tools_ttl_ms: 3500 }),
+ );
+ });
+ });
+
+ it("saves the full toolset TTL typed into the edit form", async () => {
+ const user = setup();
+ vi.mocked(networking.updateMCPToolset).mockResolvedValue(
+ {} as Awaited>,
+ );
+ renderTab([
+ {
+ toolset_id: "ts-1",
+ toolset_name: "existing",
+ tools_ttl_ms: 120000,
+ tools: [],
+ } as MCPToolset,
+ ]);
+
+ const dialog = await openEditFor(user);
+ const ttlInput = dialog.getByLabelText("Tools list TTL (ms)");
+ await user.clear(ttlInput);
+ await user.type(ttlInput, "45000");
+ expect(ttlInput).toHaveValue(45000);
+ await user.click(dialog.getByRole("button", { name: "Save Changes" }));
+
+ await waitFor(() => {
+ expect(networking.updateMCPToolset).toHaveBeenCalledWith("sk-test", {
+ toolset_id: "ts-1",
+ toolset_name: "existing",
+ description: "",
+ tools: [],
+ tools_ttl_ms: 45000,
+ });
+ });
+ });
+
it("seeds an absent description as an empty string rather than failing", async () => {
const user = setup();
vi.mocked(networking.updateMCPToolset).mockResolvedValue(
@@ -184,11 +273,11 @@ describe("MCPToolsetsTab create/edit toolset form", () => {
} as unknown as MCPToolset;
renderTab([toolset]);
- const dialog = await openEditFor(user);
- await dialog.findByDisplayValue("no-desc");
- expect(dialog.getByPlaceholderText("Optional description")).toHaveValue("");
+ await openEditFor(user);
+ await screen.findByDisplayValue("no-desc");
+ expect(screen.getByPlaceholderText("Optional description")).toHaveValue("");
- await user.click(dialog.getByRole("button", { name: "Save Changes" }));
+ await user.click(screen.getByRole("button", { name: "Save Changes" }));
const expectedUpdate = { toolset_id: "ts-2", toolset_name: "no-desc", description: "", tools: [] };
await waitFor(() => {
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.tsx
index ff0e8f7b6a9..2c4a928762e 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/MCPToolsetsTab.tsx
@@ -1,7 +1,7 @@
import React, { useState, useCallback } from "react";
import { z } from "zod";
import { SortingState } from "@tanstack/react-table";
-import { Inbox, Plus, X } from "lucide-react";
+import { Inbox, Info, Plus, X } from "lucide-react";
import { useMCPToolsets } from "@/app/(dashboard)/hooks/mcpServers/useMCPToolsets";
import { useMCPServers } from "@/app/(dashboard)/hooks/mcpServers/useMCPServers";
import { useQueryClient } from "@tanstack/react-query";
@@ -24,6 +24,7 @@ import { useZodForm } from "@/lib/forms/useZodForm";
import { toast } from "@/lib/toast";
import { displayToolName, getMCPToolsetTableColumns } from "./MCPToolsetTableColumns";
import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { SimpleTooltip } from "@/components/ui/tooltip";
interface MCPToolsetsTabProps {
accessToken: string | null;
@@ -33,6 +34,10 @@ interface MCPToolsetsTabProps {
const toolsetSchema = z.object({
toolset_name: z.string().min(1, "Please enter a toolset name"),
description: z.string(),
+ tools_ttl_ms: z.preprocess(
+ (value) => (value === "" || value === null || value === undefined ? undefined : value),
+ z.coerce.number().int().min(0).optional(),
+ ),
});
type ToolsetFormValues = z.infer;
@@ -148,7 +153,12 @@ function MCPToolList({ serverId, serverName, accessToken, selectedTools, onToggl
interface CreateToolsetModalProps {
open: boolean;
onClose: () => void;
- onSave: (name: string, description: string | undefined, tools: MCPToolsetTool[]) => Promise;
+ onSave: (
+ name: string,
+ description: string | undefined,
+ toolsTtlMs: number | undefined,
+ tools: MCPToolsetTool[],
+ ) => Promise;
accessToken: string | null;
initialToolset?: MCPToolset;
}
@@ -158,6 +168,7 @@ function CreateToolsetModal({ open, onClose, onSave, accessToken, initialToolset
defaultValues: {
toolset_name: initialToolset?.toolset_name || "",
description: initialToolset?.description || "",
+ tools_ttl_ms: initialToolset?.tools_ttl_ms ?? undefined,
},
});
const [selectedTools, setSelectedTools] = useState(initialToolset?.tools || []);
@@ -174,6 +185,7 @@ function CreateToolsetModal({ open, onClose, onSave, accessToken, initialToolset
form.reset({
toolset_name: initialToolset?.toolset_name || "",
description: initialToolset?.description || "",
+ tools_ttl_ms: initialToolset?.tools_ttl_ms ?? undefined,
});
setSelectedTools(initialToolset?.tools || []);
setServerSearch("");
@@ -192,7 +204,7 @@ function CreateToolsetModal({ open, onClose, onSave, accessToken, initialToolset
const handleSubmit = async (values: ToolsetFormValues) => {
setSaving(true);
try {
- await onSave(values.toolset_name, values.description, selectedTools);
+ await onSave(values.toolset_name, values.description, values.tools_ttl_ms, selectedTools);
onClose();
} finally {
setSaving(false);
@@ -218,6 +230,30 @@ function CreateToolsetModal({ open, onClose, onSave, accessToken, initialToolset
{(field) => }
+
+ Tools list TTL (ms)
+
+
+
+
+ }
+ className="w-48"
+ >
+ {(field) => (
+
+ )}
+
@@ -386,16 +422,39 @@ export function MCPToolsetsTab({ accessToken, userRole }: MCPToolsetsTabProps) {
const isAdmin = userRole === "Admin" || userRole === "proxy_admin";
- const handleCreate = async (name: string, description: string | undefined, tools: MCPToolsetTool[]) => {
+ const handleCreate = async (
+ name: string,
+ description: string | undefined,
+ toolsTtlMs: number | undefined,
+ tools: MCPToolsetTool[],
+ ) => {
if (!accessToken) return;
- await createMCPToolset(accessToken, { toolset_name: name, description, tools });
+ const toolsetInput = {
+ toolset_name: name,
+ description,
+ tools,
+ ...(toolsTtlMs !== undefined ? { tools_ttl_ms: toolsTtlMs } : {}),
+ };
+ await createMCPToolset(accessToken, toolsetInput);
toast.success("Toolset created");
queryClient.invalidateQueries({ queryKey: ["mcpToolsets"] });
};
- const handleUpdate = async (name: string, description: string | undefined, tools: MCPToolsetTool[]) => {
+ const handleUpdate = async (
+ name: string,
+ description: string | undefined,
+ toolsTtlMs: number | undefined,
+ tools: MCPToolsetTool[],
+ ) => {
if (!accessToken || !editToolset) return;
- await updateMCPToolset(accessToken, { toolset_id: editToolset.toolset_id, toolset_name: name, description, tools });
+ const toolsetUpdate = {
+ toolset_id: editToolset.toolset_id,
+ toolset_name: name,
+ description,
+ tools,
+ ...((toolsTtlMs ?? null) !== (editToolset.tools_ttl_ms ?? null) ? { tools_ttl_ms: toolsTtlMs ?? null } : {}),
+ };
+ await updateMCPToolset(accessToken, toolsetUpdate);
toast.success("Toolset updated");
queryClient.invalidateQueries({ queryKey: ["mcpToolsets"] });
setEditToolset(null);
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/createServerPayload.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/createServerPayload.test.ts
index 3ae846b0308..c0fcf92f0d4 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/createServerPayload.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/createServerPayload.test.ts
@@ -125,6 +125,17 @@ describe("buildCreateServerPayload transport and naming", () => {
expect(payload.transport).toBe("http");
});
+ it("includes a configured OpenAPI tools list TTL, including zero", () => {
+ const payload = payloadOf(
+ build({
+ transport: "openapi",
+ spec_path: "https://api.example.com/openapi.json",
+ tools_ttl_ms: 0,
+ }),
+ );
+ expect(payload.tools_ttl_ms).toBe(0);
+ });
+
it("leaves http and sse transports untouched", () => {
expect(payloadOf(build({ transport: "sse" })).transport).toBe("sse");
});
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.differential.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.differential.test.ts
index ee5cce2d0d2..3298d6507f5 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.differential.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.differential.test.ts
@@ -333,6 +333,28 @@ const EDIT_FORM_VALUES: EditServerFormValues = {
};
describe("buildEditServerPayload wire contract", () => {
+ it("omits an unchanged OpenAPI tools list TTL", () => {
+ const ui: EditServerUiState = {
+ ...baseUi,
+ mcpServer: { ...baseUi.mcpServer, spec_path: "https://example.com/openapi.json", tools_ttl_ms: 2000 },
+ };
+ const result = buildEditServerPayload({ ...EDIT_FORM_VALUES, tools_ttl_ms: 2000 }, ui);
+
+ expect(result).toMatchObject({ kind: "ok" });
+ if (result.kind !== "ok") throw new Error("Expected valid MCP server payload");
+ expect(result.payload).not.toHaveProperty("tools_ttl_ms");
+ });
+
+ it("clears an OpenAPI tools list TTL with an explicit null", () => {
+ const ui: EditServerUiState = {
+ ...baseUi,
+ mcpServer: { ...baseUi.mcpServer, spec_path: "https://example.com/openapi.json", tools_ttl_ms: 2000 },
+ };
+ const result = buildEditServerPayload({ ...EDIT_FORM_VALUES, tools_ttl_ms: null }, ui);
+
+ expect(result).toMatchObject({ kind: "ok", payload: { tools_ttl_ms: null } });
+ });
+
it("carries an edited alias and the server identifier onto the wire", () => {
const result = buildEditServerPayload({ ...EDIT_FORM_VALUES, alias: "renamed" }, baseUi);
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.ts b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.ts
index 081063854c0..7ac22aba16e 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/editServerPayload.ts
@@ -42,6 +42,7 @@ export interface EditServerFormValues {
readonly extra_headers?: readonly string[];
readonly disallowed_tools?: readonly string[];
readonly oauth_flow_type?: string;
+ readonly tools_ttl_ms?: number | string | null;
readonly [key: string]: unknown;
}
@@ -296,6 +297,7 @@ export const buildEditServerPayload = (values: EditServerFormValues, ui: EditSer
oauth_passthrough: oauthPassthroughRaw,
dcr_bridge: dcrBridgeRaw,
token_validation_json: rawTokenValidationJson,
+ tools_ttl_ms: rawToolsTtlMs,
...rawRestValues
} = values;
@@ -318,6 +320,10 @@ export const buildEditServerPayload = (values: EditServerFormValues, ui: EditSer
// position, which the payload's serialised key order depends on.
const restValues =
rawRestValues.transport === TRANSPORT.OPENAPI ? { ...rawRestValues, transport: "http" } : rawRestValues;
+ const toolsTtlPayload =
+ mcpServer.spec_path && rawToolsTtlMs !== mcpServer.tools_ttl_ms
+ ? { tools_ttl_ms: rawToolsTtlMs == null || rawToolsTtlMs === "" ? null : Number(rawToolsTtlMs) }
+ : {};
const tokenValidation = ((): TokenValidationResult => {
if (!rawTokenValidationJson || rawTokenValidationJson.trim() === "") return { kind: "ok", value: null };
@@ -365,6 +371,7 @@ export const buildEditServerPayload = (values: EditServerFormValues, ui: EditSer
const payload: EditServerPayload = {
...restValues,
+ ...toolsTtlPayload,
...stdio.fields,
// Remove UI-only fields
stdio_config: undefined,
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.test.tsx
index 35e212faf37..d9decf12d9f 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.test.tsx
@@ -179,6 +179,26 @@ describe("MCPServerEdit (stdio)", () => {
);
expect(screen.getByRole("tab", { name: "Server Configuration" })).toBeInTheDocument();
+ expect(screen.queryByLabelText("Tools list TTL (ms)")).not.toBeInTheDocument();
+ });
+
+ it("shows tools list TTL for an OpenAPI server", () => {
+ render(
+ ,
+ );
+
+ expect(screen.getByLabelText("Tools list TTL (ms)")).toBeInTheDocument();
});
it("should allow updating stdio transport configuration", async () => {
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx
index f35e3ab3d3a..9d755d274db 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx
@@ -994,6 +994,30 @@ const MCPServerEdit: React.FC = ({
)}
+ {isOpenAPITransport && (
+
+ Tools list TTL (ms)
+
+
+
+
+ }
+ name="tools_ttl_ms"
+ >
+ {(control) => (
+
+ )}
+
+ )}
+
{/* Authentication - for HTTP, SSE, and OpenAPI */}
{!isStdioTransport && (
<>
diff --git a/ui/litellm-dashboard/src/components/mcp_tools/types.tsx b/ui/litellm-dashboard/src/components/mcp_tools/types.tsx
index 22fd64f10d8..7dbfbe42917 100644
--- a/ui/litellm-dashboard/src/components/mcp_tools/types.tsx
+++ b/ui/litellm-dashboard/src/components/mcp_tools/types.tsx
@@ -434,6 +434,7 @@ export interface MCPServer {
*/
url?: string | null;
spec_path?: string | null;
+ tools_ttl_ms?: number | null;
transport?: string | null;
auth_type?: string | null;
oauth2_flow?: string | null;
@@ -548,6 +549,7 @@ export interface MCPToolset {
toolset_id: string;
toolset_name: string;
description?: string;
+ tools_ttl_ms?: number | null;
tools: MCPToolsetTool[];
created_at?: string;
created_by?: string;
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 0fc0d86b479..3a98080021f 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -34773,6 +34773,8 @@ export interface components {
tool_name_to_display_name?: {
[key: string]: string;
} | null;
+ /** Tools Ttl Ms */
+ tools_ttl_ms?: number | null;
/**
* Transport
* @enum {string}
@@ -38951,6 +38953,8 @@ export interface components {
tool_name_to_display_name?: {
[key: string]: string;
} | null;
+ /** Tools Ttl Ms */
+ tools_ttl_ms?: number | null;
/**
* Transport
* @default sse
@@ -38969,6 +38973,8 @@ export interface components {
* @default []
*/
tools: components["schemas"]["MCPToolsetTool"][];
+ /** Tools Ttl Ms */
+ tools_ttl_ms?: number | null;
/** Toolset Name */
toolset_name: string;
};
@@ -48481,6 +48487,8 @@ export interface components {
tool_name_to_display_name?: {
[key: string]: string;
} | null;
+ /** Tools Ttl Ms */
+ tools_ttl_ms?: number | null;
/**
* Transport
* @default sse
@@ -48496,6 +48504,8 @@ export interface components {
description?: string | null;
/** Tools */
tools?: components["schemas"]["MCPToolsetTool"][] | null;
+ /** Tools Ttl Ms */
+ tools_ttl_ms?: number | null;
/** Toolset Id */
toolset_id: string;
/** Toolset Name */