diff --git a/docs/my-website/docs/mcp.md b/docs/my-website/docs/mcp.md index 7eee979cc67..f99d731d3cf 100644 --- a/docs/my-website/docs/mcp.md +++ b/docs/my-website/docs/mcp.md @@ -137,7 +137,6 @@ 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: @@ -149,16 +148,6 @@ 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" @@ -173,13 +162,6 @@ 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 ``` @@ -209,65 +191,6 @@ 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 @@ -848,203 +771,6 @@ 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. @@ -1054,6 +780,13 @@ 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 @@ -1433,6 +1166,132 @@ 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