[Fixes] Bug fixes to using LiteLLM MCP Gateway (#14392)

* fix: use _get_mcp_servers_in_path

* fix checks for using litellm_proxy as MCP tool provider

* fix: fix mcp_tools_with_litellm_proxy

* fix: fix aresponses_api_with_mcp

* aresponses_api_with_mcp

* test_mcp_allowed_tools_filtering

* fix: _filter_mcp_tools_by_allowed_tools

* fix: _filter_mcp_tools_by_allowed_tools

* test_streaming_responses_api_with_mcp_tools

* fixes: test tools transfrom MCP->OpenaI spec

* test_streaming_responses_api_with_mcp_tools

* fix: chat ui allow multi select with allowed tools

* fix: use correct MCP events with litellm proxy response API

* fix get_event_model_class

* fix litellm proxy MCP handler

* fix MCPEnhancedStreamingIterator

* chat ui show list tools result

* UI: show MCP events

* fix stream iterator

* fixes: litellm proxy mcp handler

* test responses + mcp

* fix: update responses api with mcp handling

* ruff check fix

* central: _process_mcp_tools_to_openai_format

* fix: refactor code

* test_mcp_allowed_tools_filtering

* test mcp with litellm proxy

* fix mcp call

* demo: video using MCP ui

* fixes for using stream iterator

* test_no_duplicate_mcp_tools_in_streaming_e2e

* docs fix

* fix code snippet

Author: ishaan-jaff

cookbook/litellm_proxy_server/mcp/mcp_with_litellm_proxy.py

@@ -0,0 +1,36 @@
+"""
+Use LiteLLM Proxy MCP Gateway to call MCP tools.
+
+When using LiteLLM Proxy, you can use the same MCP tools across all your LLM providers.
+"""
+import openai
+
+client = openai.OpenAI(
+    api_key="sk-1234", # paste your litellm proxy api key here
+    base_url="http://localhost:4000" # paste your litellm proxy base url here
+)
+print("Making API request to Responses API with MCP tools")
+
+response = client.responses.create(
+    model="gpt-5",
+    input=[
+        {
+            "role": "user",
+            "content": "give me TLDR of what BerriAI/litellm repo is about",
+            "type": "message"
+        }
+    ],
+    tools=[
+        {
+            "type": "mcp",
+            "server_label": "litellm",
+            "server_url": "litellm_proxy",
+            "require_approval": "never"
+        }
+    ],
+    stream=True,
+    tool_choice="required"
+)
+
+for chunk in response:
+    print("response chunk: ", chunk)

docs/my-website/docs/mcp.md

@@ -197,10 +197,17 @@ litellm_settings:
 
 ### Use on LiteLLM UI 
 
+Follow this walkthrough to use your MCP on LiteLLM UI
+
+<iframe width="840" height="500" src="https://www.loom.com/embed/57e0763267254bc79dbe6658d0b8758c" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+
 ### Use with Responses API
 
 Replace `http://localhost:4000` with your LiteLLM Proxy base URL.
 
+Demo Video Using Responses API with LiteLLM Proxy: [Demo video here](https://www.loom.com/share/34587e618c5c47c0b0d67b4e4d02718f?sid=2caf3d45-ead4-4490-bcc1-8d6dd6041c02)
+
+
 <Tabs>
 <TabItem value="curl" label="cURL">
 
@@ -234,12 +241,18 @@ curl --location 'http://localhost:4000/v1/responses' \
 <TabItem value="python" label="Python SDK">
 
 ```python title="Python SDK Example" showLineNumbers
+"""
+Use LiteLLM Proxy MCP Gateway to call MCP tools.
+
+When using LiteLLM Proxy, you can use the same MCP tools across all your LLM providers.
+"""
 import openai
 
 client = openai.OpenAI(
-    api_key="sk-1234",
-    base_url="http://localhost:4000"
+    api_key="sk-1234", # paste your litellm proxy api key here
+    base_url="http://localhost:4000" # paste your litellm proxy base url here
 )
+print("Making API request to Responses API with MCP tools")
 
 response = client.responses.create(
     model="gpt-5",
@@ -262,7 +275,8 @@ response = client.responses.create(
     tool_choice="required"
 )
 
-print(response)
+for chunk in response:
+    print("response chunk: ", chunk)
 ```
 
 </TabItem>

litellm/experimental_mcp_client/tools.py

@@ -17,22 +17,60 @@
 ########################################################
 def transform_mcp_tool_to_openai_tool(mcp_tool: MCPTool) -> ChatCompletionToolParam:
     """Convert an MCP tool to an OpenAI tool."""
+    normalized_parameters = _normalize_mcp_input_schema(mcp_tool.inputSchema)
+    
     return ChatCompletionToolParam(
         type="function",
         function=FunctionDefinition(
             name=mcp_tool.name,
             description=mcp_tool.description or "",
-            parameters=mcp_tool.inputSchema,
+            parameters=normalized_parameters,
             strict=False,
         ),
     )
 
 
+def _normalize_mcp_input_schema(input_schema: dict) -> dict:
+    """
+    Normalize MCP input schema to ensure it's valid for OpenAI function calling.
+    
+    OpenAI requires that function parameters have:
+    - type: 'object'
+    - properties: dict (can be empty)
+    - additionalProperties: false (recommended)
+    """
+    if not input_schema:
+        return {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False
+        }
+    
+    # Make a copy to avoid modifying the original
+    normalized_schema = dict(input_schema)
+    
+    # Ensure type is 'object'
+    if "type" not in normalized_schema:
+        normalized_schema["type"] = "object"
+    
+    # Ensure properties exists (can be empty)
+    if "properties" not in normalized_schema:
+        normalized_schema["properties"] = {}
+    
+    # Add additionalProperties if not present (recommended by OpenAI)
+    if "additionalProperties" not in normalized_schema:
+        normalized_schema["additionalProperties"] = False
+    
+    return normalized_schema
+
+
 def transform_mcp_tool_to_openai_responses_api_tool(mcp_tool: MCPTool) -> FunctionToolParam:
     """Convert an MCP tool to an OpenAI Responses API tool."""
+    normalized_parameters = _normalize_mcp_input_schema(mcp_tool.inputSchema)
+    
     return FunctionToolParam(
         name=mcp_tool.name,
-        parameters=mcp_tool.inputSchema,
+        parameters=normalized_parameters,
         strict=False,
         type="function",
         description=mcp_tool.description or "",

litellm/llms/openai/responses/transformation.py

@@ -272,6 +272,14 @@ def get_event_model_class(event_type: str) -> Any:
             ResponsesAPIStreamEvents.WEB_SEARCH_CALL_IN_PROGRESS: WebSearchCallInProgressEvent,
             ResponsesAPIStreamEvents.WEB_SEARCH_CALL_SEARCHING: WebSearchCallSearchingEvent,
             ResponsesAPIStreamEvents.WEB_SEARCH_CALL_COMPLETED: WebSearchCallCompletedEvent,
+            ResponsesAPIStreamEvents.MCP_LIST_TOOLS_IN_PROGRESS: MCPListToolsInProgressEvent,
+            ResponsesAPIStreamEvents.MCP_LIST_TOOLS_COMPLETED: MCPListToolsCompletedEvent,
+            ResponsesAPIStreamEvents.MCP_LIST_TOOLS_FAILED: MCPListToolsFailedEvent,
+            ResponsesAPIStreamEvents.MCP_CALL_IN_PROGRESS: MCPCallInProgressEvent,
+            ResponsesAPIStreamEvents.MCP_CALL_ARGUMENTS_DELTA: MCPCallArgumentsDeltaEvent,
+            ResponsesAPIStreamEvents.MCP_CALL_ARGUMENTS_DONE: MCPCallArgumentsDoneEvent,
+            ResponsesAPIStreamEvents.MCP_CALL_COMPLETED: MCPCallCompletedEvent,
+            ResponsesAPIStreamEvents.MCP_CALL_FAILED: MCPCallFailedEvent,
             ResponsesAPIStreamEvents.ERROR: ErrorEvent,
         }
 

litellm/proxy/_experimental/mcp_server/server.py

@@ -215,9 +215,9 @@ async def mcp_server_tool_call(
         """
         from fastapi import Request
 
+        from litellm.exceptions import BlockedPiiEntityError, GuardrailRaisedException
         from litellm.proxy.litellm_pre_call_utils import add_litellm_data_to_request
         from litellm.proxy.proxy_server import proxy_config
-        from litellm.exceptions import BlockedPiiEntityError, GuardrailRaisedException
 
         # Validate arguments
         user_api_key_auth, mcp_auth_header, _, mcp_server_auth_headers, mcp_protocol_version = get_auth_context()
@@ -279,33 +279,15 @@ async def mcp_server_tool_call(
     ############ Helper Functions ##########################
     ########################################################
 
-    async def _get_tools_from_mcp_servers(
-        user_api_key_auth: Optional[UserAPIKeyAuth],
-        mcp_auth_header: Optional[str],
+    async def _get_allowed_mcp_servers_from_mcp_server_names(
         mcp_servers: Optional[List[str]],
-        mcp_server_auth_headers: Optional[Dict[str, str]] = None,
-        mcp_protocol_version: Optional[str] = None,
-    ) -> List[MCPTool]:
+        allowed_mcp_servers: List[str],
+    ) -> List[str]:
         """
-        Helper method to fetch tools from MCP servers based on server filtering criteria.
-
-        Args:
-            user_api_key_auth: User authentication info for access control
-            mcp_auth_header: Optional auth header for MCP server (deprecated)
-            mcp_servers: Optional list of server names/aliases to filter by
-            mcp_server_auth_headers: Optional dict of server-specific auth headers {server_alias: auth_value}
-
-        Returns:
-            List[MCPTool]: Combined list of tools from filtered servers
+        Get the filtered MCP servers from the MCP server names
         """
-        if not MCP_AVAILABLE:
-            return []
-
-        # Get allowed MCP servers based on user permissions
-        allowed_mcp_servers = await global_mcp_server_manager.get_allowed_mcp_servers(user_api_key_auth)
-
-        filtered_server_ids = set()
-
+        from typing import Set
+        filtered_server_ids: Set[str] = set()
         # Filter servers based on mcp_servers parameter if provided
         if mcp_servers is not None:
             for server_or_group in mcp_servers:
@@ -336,6 +318,40 @@ async def _get_tools_from_mcp_servers(
 
         if filtered_server_ids:
             allowed_mcp_servers = list(filtered_server_ids)
+        
+        return allowed_mcp_servers
+
+    async def _get_tools_from_mcp_servers(
+        user_api_key_auth: Optional[UserAPIKeyAuth],
+        mcp_auth_header: Optional[str],
+        mcp_servers: Optional[List[str]],
+        mcp_server_auth_headers: Optional[Dict[str, str]] = None,
+        mcp_protocol_version: Optional[str] = None,
+    ) -> List[MCPTool]:
+        """
+        Helper method to fetch tools from MCP servers based on server filtering criteria.
+
+        Args:
+            user_api_key_auth: User authentication info for access control
+            mcp_auth_header: Optional auth header for MCP server (deprecated)
+            mcp_servers: Optional list of server names/aliases to filter by
+            mcp_server_auth_headers: Optional dict of server-specific auth headers {server_alias: auth_value}
+
+        Returns:
+            List[MCPTool]: Combined list of tools from filtered servers
+        """
+        if not MCP_AVAILABLE:
+            return []
+
+        # Get allowed MCP servers based on user permissions
+        allowed_mcp_servers = await global_mcp_server_manager.get_allowed_mcp_servers(user_api_key_auth)
+
+        if mcp_servers is not None:
+            allowed_mcp_servers = await _get_allowed_mcp_servers_from_mcp_server_names(
+                mcp_servers=mcp_servers,
+                allowed_mcp_servers=allowed_mcp_servers,
+            )
+
 
         # Get tools from each allowed server
         all_tools = []
@@ -556,20 +572,25 @@ async def _handle_local_mcp_tool(
         except Exception as e:
             return [TextContent(text=f"Error: {str(e)}", type="text")]
 
-    async def extract_mcp_auth_context(scope, path):
+    def _get_mcp_servers_in_path(path: str) -> Optional[List[str]]:
         """
-        Extracts mcp_servers from the path and processes the MCP request for auth context.
-        Returns: (user_api_key_auth, mcp_auth_header, mcp_servers, mcp_server_auth_headers)
+        Get the MCP servers from the path
         """
         import re
-
-        mcp_servers_from_path = None
+        mcp_servers_from_path: Optional[List[str]] = None
         mcp_path_match = re.match(r"^/mcp/([^/]+)(/.*)?$", path)
         if mcp_path_match:
             mcp_servers_str = mcp_path_match.group(1)
             if mcp_servers_str:
                 mcp_servers_from_path = [s.strip() for s in mcp_servers_str.split(",") if s.strip()]
+        return mcp_servers_from_path
 
+    async def extract_mcp_auth_context(scope, path):
+        """
+        Extracts mcp_servers from the path and processes the MCP request for auth context.
+        Returns: (user_api_key_auth, mcp_auth_header, mcp_servers, mcp_server_auth_headers)
+        """
+        mcp_servers_from_path = _get_mcp_servers_in_path(path)
         if mcp_servers_from_path is not None:
             (
                 user_api_key_auth,

litellm/proxy/management_endpoints/mcp_management_endpoints.py

@@ -17,16 +17,18 @@
 """
 
 import importlib
-from typing import Iterable, List, Optional
 from datetime import datetime
+from typing import Iterable, List, Optional
 
 from fastapi import APIRouter, Depends, Header, HTTPException, Response, status
 from fastapi.responses import JSONResponse
 
 import litellm
 from litellm._logging import verbose_logger, verbose_proxy_logger
 from litellm.constants import LITELLM_PROXY_ADMIN_NAME
-from litellm.proxy._experimental.mcp_server.utils import validate_and_normalize_mcp_server_payload
+from litellm.proxy._experimental.mcp_server.utils import (
+    validate_and_normalize_mcp_server_payload,
+)
 
 router = APIRouter(prefix="/v1/mcp", tags=["mcp"])
 MCP_AVAILABLE: bool = True
@@ -94,34 +96,17 @@ async def get_mcp_tools(
         """
         Get all MCP tools available for the current key, including those from access groups
         """
-        from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import (
-            MCPRequestHandler,
-        )
-        from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
-            global_mcp_server_manager,
+        from litellm.proxy._experimental.mcp_server.server import _list_mcp_tools
+        tools = await _list_mcp_tools(
+            user_api_key_auth=user_api_key_dict,
+            mcp_auth_header=None,
+            mcp_servers=None,
+            mcp_server_auth_headers=None,
+            mcp_protocol_version=None,
         )
+        dumped_tools = [dict(tool) for tool in tools]
 
-        # This now includes both direct and access group servers
-        server_ids = await MCPRequestHandler._get_allowed_mcp_servers_for_key(user_api_key_dict)
-
-        tools = []
-        errors = []
-        for server_id in server_ids:
-            try:
-                server_tools = await global_mcp_server_manager.get_tools_for_server(server_id)
-                tools.extend(server_tools)
-                verbose_proxy_logger.debug(f"Successfully fetched {len(server_tools)} tools from server {server_id}")
-            except Exception as e:
-                error_msg = f"Failed to get tools from server {server_id}: {str(e)}"
-                verbose_proxy_logger.warning(error_msg)
-                errors.append(error_msg)
-                # Continue with other servers instead of failing completely
-
-        verbose_proxy_logger.debug(f"Available tools: {tools}")
-        if errors:
-            verbose_proxy_logger.warning(f"Some servers failed to respond: {errors}")
-
-        return {"tools": tools}
+        return {"tools": dumped_tools}
 
     @router.get(
         "/access_groups",
@@ -134,8 +119,10 @@ async def get_mcp_access_groups(
         """
         Get all available MCP access groups from the database AND config
         """
+        from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
+            global_mcp_server_manager,
+        )
         from litellm.proxy.proxy_server import prisma_client
-        from litellm.proxy._experimental.mcp_server.mcp_server_manager import global_mcp_server_manager
 
         access_groups = set()
 

litellm/proxy/proxy_config.yaml

@@ -3,5 +3,16 @@ model_list:
     litellm_params:
       model: openai/*
       api_base: https://exampleopenaiendpoint-production-0ee2.up.railway.app/
+  - model_name: bedrock/*
+    litellm_params:
+      model: bedrock/*
+  - model_name: openai/*
+    litellm_params:
+      model: openai/*
+  - model_name: gemini/*
+    litellm_params:
+      model: gemini/*
+
+
 litellm_settings:
   callbacks: ["cloudzero"]