Skillintermediate

MCP Overview

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Image from '@theme/IdealImage';

Claude Code Knowledge Pack7/10/2026

Overview

MCP Overview

LiteLLM Proxy provides an MCP Gateway that allows you to use a fixed endpoint for all MCP tools and control MCP access by Key, Team.

<p style={{textAlign: 'left', color: '#666'}}> LiteLLM MCP Architecture: Use MCP tools with all LiteLLM supported models </p>

Overview

Feature	Description
MCP Operations	• List Tools<br/>• Call Tools <br/>• Prompts <br/>• Resources
Supported MCP Transports	• Streamable HTTP<br/>• SSE<br/>• Standard Input/Output (stdio)
LiteLLM Permission Management	• By Key<br/>• By Team<br/>• By Organization

:::caution MCP protocol update Starting in LiteLLM v1.80.18, the LiteLLM MCP protocol version is 2025-11-25.<br/> LiteLLM namespaces multiple MCP servers by prefixing each tool name with its MCP server name, so newly created servers now must use names that comply with SEP-986—noncompliant names cannot be added anymore. Existing servers that still violate SEP-986 only emit warnings today, but future MCP-side rollouts may block those names entirely, so we recommend updating any legacy server names proactively before MCP enforcement makes them unusable. :::

Adding your MCP

Prerequisites

To store MCP servers in the database, you need to enable database storage:

Environment Variable:

OR in config.yaml:

general_settings:
  store_model_in_db: true

Fine-grained Database Storage Control

By default, when store_model_in_db is true, all object types (models, MCPs, guardrails, vector stores, etc.) are stored in the database. If you want to store only specific object types, use the supported_db_objects setting.

Example: Store only MCP servers in the database

general_settings:
  store_model_in_db: true
  supported_db_objects: ["mcp"]  # Only store MCP servers in DB

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-xxxxxxx

See all available object types: Config Settings - supported_db_objects

If supported_db_objects is not set, all object types are loaded from the database (default behavior).

For diagnosing connectivity problems after setup, see the MCP Troubleshooting Guide.

On the LiteLLM UI, Navigate to "MCP Servers" and click "Add New MCP Server".

On this form, you should enter your MCP Server URL and the transport you want to use.

LiteLLM supports the following MCP transports:

Streamable HTTP
SSE (Server-Sent Events)
Standard Input/Output (stdio)

Add HTTP MCP Server

This video walks through adding and using an HTTP MCP server on LiteLLM UI and using it in Cursor IDE.

Add SSE MCP Server

This video walks through adding and using an SSE MCP server on LiteLLM UI and using it in Cursor IDE.

Add STDIO MCP Server

For stdio MCP servers, select "Standard Input/Output (stdio)" as the transport type and provide the stdio configuration in JSON format:

OAuth Configuration & Overrides

LiteLLM attempts OAuth 2.0 Authorization Server Discovery by default. When you create an MCP server in the UI and set Authentication: OAuth, LiteLLM will locate the provider metadata, dynamically register a client, and perform PKCE-based authorization without you providing any additional details.

Customize the OAuth flow when needed:

Provide explicit client credentials – If the MCP provider does not offer dynamic client registration or you prefer to manage the client yourself, fill in client_id, client_secret, and the desired scopes.
Override discovery URLs – In some environments, LiteLLM might not be able to reach the provider's metadata endpoints. Use the optional authorization_url, token_url, and registration_url fields to point LiteLLM directly to the correct endpoints.

<br/>

AWS SigV4 Authentication

For MCP servers hosted on AWS Bedrock AgentCore, select AWS SigV4 as the authentication type. LiteLLM will sign every outgoing MCP request with your AWS credentials using Signature Version 4.

Fill in your AWS region, service name (defaults to bedrock-agentcore), and optionally your AWS access key and secret. If credentials are omitted, LiteLLM falls back to the boto3 credential chain (IAM roles, environment variables, etc.).

See full SigV4 setup guide

<br/>

Static Headers

Sometimes your MCP server needs specific headers on every request. Maybe it's an API key, maybe it's a custom header the server expects. Instead of configuring auth, you can just set them directly.

These headers get sent with every request to the server. That's it.

When to use this:

Your server needs custom headers that don't fit the standard auth patterns
You want full control over exactly what headers are sent
You're debugging and need to quickly add headers without changing auth configuration

Add your MCP servers directly in your config.yaml file:

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-xxxxxxx

litellm_settings:
  # MCP Aliases - Map aliases to server names for easier tool access
  mcp_aliases:
    "github": "github_mcp_server"
    "zapier": "zapier_mcp_server"
    "deepwiki": "deepwiki_mcp_server"

mcp_servers:
  # HTTP Streamable Server
  deepwiki_mcp:
    url: "https://mcp.deepwiki.com/mcp"
  # SSE Server
  zapier_mcp:
    url: "https://actions.zapier.com/mcp/sk-akxxxxx/sse"
  
  # Standard Input/Output (stdio) Server - CircleCI Example
  circleci_mcp:
    transport: "stdio"
    command: "npx"
    args: ["-y", "@circleci/mcp-server-circleci"]
    env:
      CIRCLECI_TOKEN: "your-circleci-token"
      CIRCLECI_BASE_URL: "https://circleci.com"
  
  # Full configuration with all optional fields
  my_http_server:
    url: "https://my-mcp-server.com/mcp"
    transport: "http"
    description: "My custom MCP server"
    auth_type: "api_key"
    auth_value: "abc123"

Configuration Options:

Server Name: Use any descriptive name for your MCP server (e.g., zapier_mcp, deepwiki_mcp, circleci_mcp)
Alias: This name will be prefilled with the server name with "_" replacing spaces, else edit it to be the prefix in tool names
URL: The endpoint URL for your MCP server (required for HTTP/SSE transports)
Transport: Optional transport type (defaults to sse)
- sse - SSE (Server-Sent Events) transport
- http - Streamable HTTP transport
- stdio - Standard Input/Output transport
Command: The command to execute for stdio transport (required for stdio)
allow_all_keys: Set to true to make the server available to every LiteLLM API key, even if the key/team doesn't list the server in its MCP permissions.
Args: Array of arguments to pass to the command (optional for stdio)
Env: Environment variables to set for the stdio process (optional for stdio)
Description: Optional description for the server

Auth Type: Optional authentication type. Supported values:

Value	Header sent
`api_key`	`X-API-Key: <auth_value>`
`bearer_token`	`Authorization: Bearer <auth_value>`
`basic`	`Authorization: Basic <auth_value>`
`authorization`	`Authorization: <auth_value>`
`aws_sigv4`	Per-request AWS SigV4 signature (details)

Extra Headers: Optional list of additional header names that should be forwarded from client to the MCP server
Static Headers: Optional map of header key/value pairs to include every request to the MCP server.
Spec Version: Optional MCP specification version (defaults to 2025-06-18)

Examples for each auth type:

mcp_servers:
  api_key_example:
    url: "https://my-mcp-server.com/mcp"
    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 override
    token_url: "https://my-mcp-server.com/oauth/token"             # optional override
    registration_url: "https://my-mcp-server.com/oauth/register"   # optional override
    client_id: os.environ/OAUTH_CLIENT_ID
    client_secret: os.environ/OAUTH_CLIENT_SECRET
    scopes: ["tool.read", "tool.write"] # optional override

  bearer_example:
    url: "https://my-mcp-server.com/mcp"
    auth_type: "bearer_token"
    auth_value: "abc123"        # headers={"Authorization": "Bearer abc123"}

  basic_example:
    url: "https://my-mcp-server.com/mcp"
    auth_type: "basic"
    auth_value: "dXNlcjpwYXNz"  # headers={"Authorization": "Basic dXNlcjpwYXNz"}

  custom_auth_example:
    url: "https://my-mcp-server.com/mcp"
    auth_type: "authorization"
    auth_value: "Token example123"  # headers={"Authorization": "Token example123"}

  # AWS SigV4 for Bedrock AgentCore MCP servers
  agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_role_name: os.environ/AWS_ROLE_ARN          # optional — IAM role to assume
    aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID  # optional — falls back to IAM role
    aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
    aws_region_name: us-east-1
    aws_service_name: bedrock-agentcore

  # 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

  # Example with static headers
  my_mcp_server:
    url: "https://my-mcp-server.com/mcp"
    static_headers: # These headers will be requested to the MCP server
      X-API-Key: "abc123"
      X-Custom-Header: "some-value"

MCP Walkthroughs

Strands (STDIO) – watch tutorial

Add it from the UI

{
  "mcpServers": {
    "strands-agents": {
      "command": "uvx",
      "args": ["strands-agents-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": ["search_docs", "fetch_doc"]
    }
  }
}

config.yml

mcp_servers:
  strands_mcp:
    transport: "stdio"
    command: "uvx"
    args: ["strands-agents-mcp-server"]
    env:
      FASTMCP_LOG_LEVEL: "INFO"

MCP Aliases

You can define aliases for your MCP servers in the litellm_settings section. This allows you to:

Map friendly names to server names: Use shorter, more memorable aliases
Override server aliases: If a server doesn't have an alias defined, the system will use the first matching alias from mcp_aliases
Ensure uniqueness: Only the first alias for each server is used, preventing conflicts

Example:

litellm_settings:
  mcp_aliases:
    "github": "github_mcp_server"      # Maps "github" alias to "github_mcp_server"
    "zapier": "zapier_mcp_server"      # Maps "zapier" alias to "zapier_mcp_server"
    "docs": "deepwiki_mcp_server"      # Maps "docs" alias to "deepwiki_mcp_server"
    "github_alt": "github_mcp_server"  # This will be ignored since "github" already maps to this server

Benefits:

Simplified tool access: Use github_create_issue instead of github_mcp_server_create_issue
Consistent naming: Standardize alias patterns across your organization
Easy migration: Change server names without breaking existing tool references

Converting OpenAPI Specs to MCP Servers

LiteLLM can convert OpenAPI specifications into MCP servers, exposing any REST API as MCP tools without writing custom server code.

See the MCP from OpenAPI Specs guide for full setup, usage examples, and how to override tool names and descriptions.

MCP OAuth

LiteLLM supports OAuth 2.0 for MCP servers -- both interactive (PKCE) flows for user-facing clients and machine-to-machine (M2M) client_credentials for backend services.

See the MCP OAuth guide for setup instructions, sequence diagrams, and a test server.

<details> <summary>Detailed OAuth reference (click to expand)</summary>

LiteLLM v 1.77.6 added support for OAuth 2.0 Client Credentials for MCP servers.

You can configure this either in config.yaml or directly from the LiteLLM UI (MCP Servers → Authentication → OAuth).

mcp_servers:
  github_mcp:
    url: "https://api.githubcopilot.com/mcp"
    auth_type: oauth2
    client_id: os.environ/GITHUB_OAUTH_CLIENT_ID
    client_secret: os.environ/GITHUB_OAUTH_CLIENT_SECRET

See Claude Code Tutorial

How It Works

sequenceDiagram
    participant Browser as User-Agent (Browser)
    participant Client as Client
    participant LiteLLM as LiteLLM Proxy
    participant MCP as MCP Server (Resource Server)
    participant Auth as Authorization Server

    Note over Client,LiteLLM: Step 1 – Resource discov