[Feat] MCP - Allow connecting to MCP with authentication headers + Allow clients to specify MCP headers (#11890)

[ishaan-jaff]

MCP - Allow connecting to MCP with authentication headers + Allow clients to specify MCP headers

Adds the following:

1. Support for clients to specify x-mcp-auth as a header to authenticate to the MCP Server
2. Support for connecting to MCP servers using the specified auth tokens

Using your MCP with client side credentials

Use this if you want to pass a client side authentication token to LiteLLM to then pass to your MCP to auth to your MCP.

You can specify your MCP auth token using the header x-mcp-auth. LiteLLM will forward this token to your MCP server for authentication.

Connect via OpenAI Responses API with MCP Auth

Use the OpenAI Responses API and include the x-mcp-auth header for your MCP server authentication:

curl --location 'https://api.openai.com/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $OPENAI_API_KEY" \
--data '{
    "model": "gpt-4o",
    "tools": [
        {
            "type": "mcp",
            "server_label": "litellm",
            "server_url": "<your-litellm-proxy-base-url>/mcp",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY",
                "x-mcp-auth": "YOUR_MCP_AUTH_TOKEN"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

Connect via LiteLLM Proxy Responses API with MCP Auth

Use this when calling LiteLLM Proxy for LLM API requests to /v1/responses endpoint with MCP authentication:

curl --location '<your-litellm-proxy-base-url>/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $LITELLM_API_KEY" \
--data '{
    "model": "gpt-4o",
    "tools": [
        {
            "type": "mcp",
            "server_label": "litellm",
            "server_url": "<your-litellm-proxy-base-url>/mcp",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY",
                "x-mcp-auth": "YOUR_MCP_AUTH_TOKEN"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

Connect via Cursor IDE with MCP Auth

Use tools directly from Cursor IDE with LiteLLM MCP and include your MCP authentication token:

Setup Instructions:

1. Open Cursor Settings: Use ⇧+⌘+J (Mac) or Ctrl+Shift+J (Windows/Linux)
2. Navigate to MCP Tools: Go to the "MCP Tools" tab and click "New MCP Server"
3. Add Configuration: Copy and paste the JSON configuration below, then save with Cmd+S or Ctrl+S

{
  "mcpServers": {
    "LiteLLM": {
      "url": "<your-litellm-proxy-base-url>/mcp",
      "headers": {
        "x-litellm-api-key": "Bearer $LITELLM_API_KEY",
        "x-mcp-auth": "$MCP_AUTH_TOKEN"
      }
    }
  }
}

Connect via Streamable HTTP Transport with MCP Auth

Connect to LiteLLM MCP using HTTP transport with MCP authentication:

Server URL:

<your-litellm-proxy-base-url>/mcp

Headers:

x-litellm-api-key: Bearer YOUR_LITELLM_API_KEY
x-mcp-auth: YOUR_MCP_AUTH_TOKEN

This URL can be used with any MCP client that supports HTTP transport. The x-mcp-auth header will be forwarded to your MCP server for authentication.

Connect via Python FastMCP Client with MCP Auth

Use the Python FastMCP client to connect to your LiteLLM MCP server with MCP authentication:

import asyncio
import json

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# Create the transport with your LiteLLM MCP server URL and auth headers
server_url = "<your-litellm-proxy-base-url>/mcp"
transport = StreamableHttpTransport(
    server_url,
    headers={
        "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY",
        "x-mcp-auth": "YOUR_MCP_AUTH_TOKEN"
    }
)

# Initialize the client with the transport
client = Client(transport=transport)


async def main():
    # Connection is established here
    print("Connecting to LiteLLM MCP server with authentication...")
    async with client:
        print(f"Client connected: {client.is_connected()}")

        # Make MCP calls within the context
        print("Fetching available tools...")
        tools = await client.list_tools()

        print(f"Available tools: {json.dumps([t.name for t in tools], indent=2)}")
        
        # Example: Call a tool (replace 'tool_name' with an actual tool name)
        if tools:
            tool_name = tools[0].name
            print(f"Calling tool: {tool_name}")
            
            # Call the tool with appropriate arguments
            result = await client.call_tool(tool_name, arguments={})
            print(f"Tool result: {result}")


# Run the example
if __name__ == "__main__":
    asyncio.run(main())

Relevant issues

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/litellm/ directory, Adding at least 1 test is a hard requirement - see details
• I have added a screenshot of my new test passing locally
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem

Type

🆕 New Feature
✅ Test

Changes

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
litellm	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 20, 2025 1:08am

[wagnerjt]

Not sure if you want to update the docs to leverage this client somewhere around the line 500 mark

[ishaan-jaff]

can you elaborate, wdym ?

[wagnerjt]

These examples

litellm/docs/my-website/docs/mcp.md

Line 484 in 677ef3c

from litellm import experimental_mcp_client