scriptoriumadmin/litellm
1
0
Fork 0
mirror of https://github.com/BerriAI/litellm.git synced 2026-09-15 23:31:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 165

Revert "added oauth mcp to docs"

Browse source 
This reverts commit 950b7cef44.
This commit is contained in:
mubashir1osmani 2025-10-02 15:13:33 -04:00
parent 93abafc9ed
commit 72000be905
1 changed files with 274 additions and 133 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

407
docs/my-website/docs/mcp.md
View file

@ -137,6 +137,7 @@ mcp_servers:
| `basic` | `Authorization: Basic <auth_value>` |
| `authorization` | `Authorization: <auth_value>` |
- **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:
</TabItem>
</Tabs>
## MCP Tool Filtering
Control which tools are available from your MCP servers. You can either allow only specific tools or block dangerous ones.
<Tabs>
<TabItem value="allowed" label="Only Allow Specific Tools">
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
</TabItem>
<TabItem value="blocked" label="Block Specific 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
</TabItem>
</Tabs>
### 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
<Tabs>
<TabItem value="config" label="config.yaml">
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"
```
</TabItem>
<TabItem value="clientside" label="Dynamically on Client Side">
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
</TabItem>
</Tabs>
### Client Usage
When connecting from MCP clients, include the custom headers that match the `extra_headers` configuration:
<Tabs>
<TabItem value="fastmcp" label="Python FastMCP">
```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())
```
</TabItem>
<TabItem value="cursor" label="Cursor IDE">
```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"
}
}
}
}
```
</TabItem>
<TabItem value="http" label="HTTP Client">
```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"
}'
```
</TabItem>
</Tabs>
### 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 '<your-litellm-proxy-base-url>/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