From 72000be905bdfe90dcbfa5c2f8cebdb7f9d9bbf6 Mon Sep 17 00:00:00 2001 From: mubashir1osmani Date: Thu, 2 Oct 2025 15:13:33 -0400 Subject: [PATCH] Revert "added oauth mcp to docs" This reverts commit 950b7cef44f14b2db1429f6fbd32548a7c95d325. --- docs/my-website/docs/mcp.md | 407 ++++++++++++++++++++++++------------ 1 file changed, 274 insertions(+), 133 deletions(-) diff --git a/docs/my-website/docs/mcp.md b/docs/my-website/docs/mcp.md index f99d731d3cf..7eee979cc67 100644 --- a/docs/my-website/docs/mcp.md +++ b/docs/my-website/docs/mcp.md @@ -137,6 +137,7 @@ mcp_servers: | `basic` | `Authorization: Basic ` | | `authorization` | `Authorization: ` | +- **Extra Headers**: Optional list of additional header names that should be forwarded from client to the MCP server - **Spec Version**: Optional MCP specification version (defaults to `2025-06-18`) Examples for each auth type: @@ -148,6 +149,16 @@ mcp_servers: auth_type: "api_key" auth_value: "abc123" # headers={"X-API-Key": "abc123"} + # NEW – OAuth 2.0 Client Credentials (v1.77.5) + oauth2_example: + url: "https://my-mcp-server.com/mcp" + auth_type: "oauth2" # 👈 KEY CHANGE + authorization_url: "https://my-mcp-server.com/oauth/authorize" # optional for client-credentials + token_url: "https://my-mcp-server.com/oauth/token" # required + client_id: os.environ/OAUTH_CLIENT_ID + client_secret: os.environ/OAUTH_CLIENT_SECRET + scopes: ["tool.read", "tool.write"] # optional + bearer_example: url: "https://my-mcp-server.com/mcp" auth_type: "bearer_token" @@ -162,6 +173,13 @@ mcp_servers: url: "https://my-mcp-server.com/mcp" auth_type: "authorization" auth_value: "Token example123" # headers={"Authorization": "Token example123"} + + # Example with extra headers forwarding + github_mcp: + url: "https://api.githubcopilot.com/mcp" + auth_type: "bearer_token" + auth_value: "ghp_example_token" + extra_headers: ["custom_key", "x-custom-header"] # These headers will be forwarded from client ``` @@ -191,6 +209,65 @@ litellm_settings: +## MCP Tool Filtering + +Control which tools are available from your MCP servers. You can either allow only specific tools or block dangerous ones. + + + + +Use `allowed_tools` to specify exactly which tools users can access. All other tools will be blocked. + +```yaml title="config.yaml" showLineNumbers +mcp_servers: + github_mcp: + url: "https://api.githubcopilot.com/mcp" + auth_type: oauth2 + authorization_url: https://github.com/login/oauth/authorize + token_url: https://github.com/login/oauth/access_token + client_id: os.environ/GITHUB_OAUTH_CLIENT_ID + client_secret: os.environ/GITHUB_OAUTH_CLIENT_SECRET + scopes: ["public_repo", "user:email"] + allowed_tools: ["list_tools"] + # only list_tools will be available +``` + +**Use this when:** +- You want strict control over which tools are available +- You're in a high-security environment +- You're testing a new MCP server with limited tools + + + + +Use `disallowed_tools` to block specific tools. All other tools will be available. + +```yaml title="config.yaml" showLineNumbers +mcp_servers: + github_mcp: + url: "https://api.githubcopilot.com/mcp" + auth_type: oauth2 + authorization_url: https://github.com/login/oauth/authorize + token_url: https://github.com/login/oauth/access_token + client_id: os.environ/GITHUB_OAUTH_CLIENT_ID + client_secret: os.environ/GITHUB_OAUTH_CLIENT_SECRET + scopes: ["public_repo", "user:email"] + disallowed_tools: ["repo_delete"] + # only repo_delete will be blocked +``` + +**Use this when:** +- Most tools are safe, but you want to block a few dangerous ones +- You want to prevent expensive API calls +- You're gradually adding restrictions to an existing server + + + + +### Important Notes + +- If you specify both `allowed_tools` and `disallowed_tools`, the allowed list takes priority +- Tool names are case-sensitive ## Using your MCP @@ -771,6 +848,203 @@ When creating API keys, you can assign them to specific access groups for permis /> +## Forwarding Custom Headers to MCP Servers + +LiteLLM supports forwarding additional custom headers from MCP clients to backend MCP servers using the `extra_headers` configuration parameter. This allows you to pass custom authentication tokens, API keys, or other headers that your MCP server requires. + +### Configuration + + + + +Configure `extra_headers` in your MCP server configuration to specify which header names should be forwarded: + +```yaml title="config.yaml with extra_headers" showLineNumbers +mcp_servers: + github_mcp: + url: "https://api.githubcopilot.com/mcp" + auth_type: "bearer_token" + auth_value: "ghp_default_token" + extra_headers: ["custom_key", "x-custom-header", "Authorization"] + description: "GitHub MCP server with custom header forwarding" +``` + + + +Use this when giving users access to a [group of MCP servers](#grouping-mcps-access-groups). + +**Format:** `x-mcp-{server_alias}-{header_name}: value` + +This allows you to use different authentication for different MCP servers. + + +**Examples:** +- `x-mcp-github-authorization: Bearer ghp_xxxxxxxxx` - GitHub MCP server with Bearer token +- `x-mcp-zapier-x-api-key: sk-xxxxxxxxx` - Zapier MCP server with API key +- `x-mcp-deepwiki-authorization: Basic base64_encoded_creds` - DeepWiki MCP server with Basic auth + +```python title="Python Client with Server-Specific Auth" showLineNumbers +from fastmcp import Client +import asyncio + +# Standard MCP configuration with multiple servers +config = { + "mcpServers": { + "mcp_group": { + "url": "http://localhost:4000/mcp", + "headers": { + "x-mcp-servers": "dev_group", # assume this gives access to github, zapier and deepwiki + "x-litellm-api-key": "Bearer sk-1234", + "x-mcp-github-authorization": "Bearer gho_token", + "x-mcp-zapier-x-api-key": "sk-xxxxxxxxx", + "x-mcp-deepwiki-authorization": "Basic base64_encoded_creds", + "custom_key": "value" + } + } + } +} + +# Create a client that connects to all servers +client = Client(config) + + +async def main(): + async with client: + tools = await client.list_tools() + print(f"Available tools: {tools}") + + # call mcp + await client.call_tool( + name="github_mcp-search_issues", + arguments={'query': 'created:>2024-01-01', 'sort': 'created', 'order': 'desc', 'perPage': 30} + ) + +if __name__ == "__main__": + asyncio.run(main()) + +``` + + + +**Benefits:** +- **Server-specific authentication**: Each MCP server can use different auth methods +- **Better security**: No need to share the same auth token across all servers +- **Flexible header names**: Support for different auth header types (authorization, x-api-key, etc.) +- **Clean separation**: Each server's auth is clearly identified + + + + + + + +### Client Usage + +When connecting from MCP clients, include the custom headers that match the `extra_headers` configuration: + + + + +```python title="FastMCP Client with Custom Headers" showLineNumbers +from fastmcp import Client +import asyncio + +# MCP client configuration with custom headers +config = { + "mcpServers": { + "github": { + "url": "http://localhost:4000/github_mcp/mcp", + "headers": { + "x-litellm-api-key": "Bearer sk-1234", + "Authorization": "Bearer gho_token", + "custom_key": "custom_value", + "x-custom-header": "additional_data" + } + } + } +} + +# Create a client that connects to the server +client = Client(config) + +async def main(): + async with client: + # List available tools + tools = await client.list_tools() + print(f"Available tools: {tools}") + + # Call a tool if available + if tools: + result = await client.call_tool(tools[0].name, {}) + print(f"Tool result: {result}") + +# Run the client +asyncio.run(main()) +``` + + + + + +```json title="Cursor MCP Configuration with Custom Headers" showLineNumbers +{ + "mcpServers": { + "GitHub": { + "url": "http://localhost:4000/github_mcp/mcp", + "headers": { + "x-litellm-api-key": "Bearer $LITELLM_API_KEY", + "Authorization": "Bearer $GITHUB_TOKEN", + "custom_key": "custom_value", + "x-custom-header": "additional_data" + } + } + } +} +``` + + + + + +```bash title="cURL with Custom Headers" showLineNumbers +curl --location 'http://localhost:4000/github_mcp/mcp' \ +--header 'Content-Type: application/json' \ +--header 'x-litellm-api-key: Bearer sk-1234' \ +--header 'Authorization: Bearer gho_token' \ +--header 'custom_key: custom_value' \ +--header 'x-custom-header: additional_data' \ +--data '{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/list" +}' +``` + + + + +### How It Works + +1. **Configuration**: Define `extra_headers` in your MCP server config with the header names you want to forward +2. **Client Headers**: Include the corresponding headers in your MCP client requests +3. **Header Forwarding**: LiteLLM automatically forwards matching headers to the backend MCP server +4. **Authentication**: The backend MCP server receives both the configured auth headers and the custom headers + +### Use Cases + +- **Custom Authentication**: Forward custom API keys or tokens required by specific MCP servers +- **Request Context**: Pass user identification, session data, or request tracking headers +- **Third-party Integration**: Include headers required by external services that your MCP server integrates with +- **Multi-tenant Systems**: Forward tenant-specific headers for proper request routing + +### Security Considerations + +- Only headers listed in `extra_headers` are forwarded to maintain security +- Sensitive headers should be passed through environment variables when possible +- Consider using server-specific auth headers for better security isolation + +--- + ## 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. @@ -780,13 +1054,6 @@ Use this if you want to pass a client side authentication token to LiteLLM to th You can specify MCP auth tokens using server-specific headers in the format `x-mcp-{server_alias}-{header_name}`. This allows you to use different authentication for different MCP servers. -**Format:** `x-mcp-{server_alias}-{header_name}: value` - -**Examples:** -- `x-mcp-github-authorization: Bearer ghp_xxxxxxxxx` - GitHub MCP server with Bearer token -- `x-mcp-zapier-x-api-key: sk-xxxxxxxxx` - Zapier MCP server with API key -- `x-mcp-deepwiki-authorization: Basic base64_encoded_creds` - DeepWiki MCP server with Basic auth - **Benefits:** - **Server-specific authentication**: Each MCP server can use different auth methods - **Better security**: No need to share the same auth token across all servers @@ -1166,132 +1433,6 @@ curl --location '/v1/responses' \ }' ``` -## OAuth2 Integration with MCP - -Use liteLLM to connect MCP servers using OAuth2 (Github, Zapier etc.) - -### Quick Start - - -```yaml title="config.yaml - OAuth2 MCP Configuration" showLineNumbers -model_list: - - model_name: gpt-4o - litellm_params: - model: openai/gpt-4o - api_key: sk-xxxxxxx - -mcp_servers: - github_mcp: - url: "https://api.githubcopilot.com/mcp" - auth_type: "oauth2" - client_id: "your_github_client_id" - client_secret: "your_github_client_secret" - scopes: ["public_repo", "user:email", "read:org"] - authorization_url: "https://github.com/login/oauth/authorize" - token_url: "https://github.com/login/oauth/access_token" - - zapier_mcp: - url: "https://actions.zapier.com/mcp/your-key/sse" - auth_type: "oauth2" - client_id: "zapier_client_id" - client_secret: "zapier_client_secret" - authorization_url: "https://zapier.com/oauth/authorize" - token_url: "https://zapier.com/oauth/access_token" - scopes: ["read", "write"] - - # custom mcp - custom_mcp: - url: "https://custom-mcp-url.com/mcp" - auth_type: "oauth2" - client_id: "custom_client_id" - client_secret: "custom_client_secret" - authorization_url: "https://custom-service.com/oauth/authorize" - token_url: "https://custom-service.com/oauth/token" - scopes: ["api:read", "api:write"] - redirect_uri: "https://your-app.com/callback" -``` - -### OAuth2 Endpoints - -LiteLLM automatically provides OAuth2 server discovery endpoints: - -| Endpoint | Description | -|----------|-------------| -| `/.well-known/oauth-authorization-server` | OAuth2 server metadata | -| `/authorize` | Authorization endpoint for OAuth2 flow | -| `/token` | Token exchange endpoint | -| `/callback` | OAuth2 callback handler | - -```bash title="Access OAuth2 Server Metadata" showLineNumbers -curl https://your-litellm-proxy/.well-known/oauth-authorization-server -``` - -### Using OAuth2 Tokens with MCP - -Use server-specific headers for multiple OAuth2 providers: - -```bash title="Multiple OAuth2 Servers" showLineNumbers -curl --location 'https://your-litellm-proxy/v1/responses' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer oauth_access_token' \ # or use litellm_master_key here ---data '{ - "model": "gpt-4o", - "tools": [ - { - "type": "mcp", - "server_label": "litellm", - "server_url": "litellm_proxy", - "require_approval": "never", - "headers": { - "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY", - "x-mcp-github-authorization": "Bearer github_oauth_token_123", - "x-mcp-zapier-authorization": "Bearer zapier_oauth_token_456" - } - } - ], - "input": "Create a GitHub issue and send Zapier notification", - "tool_choice": "required" -}' -``` - -```bash title="Access all configured MCP servers" showLineNumbers -curl --location 'https://your-litellm-proxy/v1/responses' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer oauth-token' \ # or litellm_master_key ---data '{ - "model": "gpt-4o", - "tools": [ - { - "type": "mcp", - "server_label": "litellm", - "server_url": "litellm_proxy", - "require_approval": "never" - } - ], - "input": "List GitHub repositories", - "tool_choice": "required" -}' -``` - -#### Dynamic Token Refresh - -LiteLLM can automatically handle token refresh for supported providers: - -```yaml title="OAuth2 with Token Refresh" showLineNumbers -mcp_servers: - github_mcp: - url: "https://api.githubcopilot.com/mcp" - auth_type: "oauth2" - client_id: "your_client_id" - client_secret: "your_client_secret" - scopes: ["public_repo", "user:email"] - authorization_url: "https://github.com/login/oauth/authorize" - token_url: "https://github.com/login/oauth/access_token" - refresh_token_url: "https://github.com/login/oauth/access_token" # For refresh - auto_refresh: true # Enable automatic token refresh -``` - - ## MCP Cost Tracking