Skillintermediate

MCP Permission Management

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

Claude Code Knowledge Pack7/10/2026

Overview

MCP Permission Management

Control which MCP servers and tools can be accessed by specific keys, teams, or organizations in LiteLLM. When a client attempts to list or call tools, LiteLLM enforces access controls based on configured permissions.

Overview

LiteLLM provides fine-grained permission management for MCP servers, allowing you to:

Restrict MCP access by entity: Control which keys, teams, or organizations can access specific MCP servers
Tool-level filtering: Automatically filter available tools based on entity permissions
Centralized control: Manage all MCP permissions from the LiteLLM Admin UI or API
One-click public MCPs: Mark specific servers as available to every LiteLLM API key when you don't need per-key restrictions

This ensures that only authorized entities can discover and use MCP tools, providing an additional security layer for your MCP infrastructure.

:::info Related Documentation

MCP Overview - Learn about MCP in LiteLLM
MCP Cost Tracking - Track costs for MCP tool calls
MCP Guardrails - Apply security guardrails to MCP calls
Using MCP - How to use MCP with LiteLLM :::

How It Works

LiteLLM supports managing permissions for MCP Servers by Keys, Teams, Organizations (entities) on LiteLLM. When a MCP client attempts to list tools, LiteLLM will only return the tools the entity has permissions to access.

When Creating a Key, Team, or Organization, you can select the allowed MCP Servers that the entity has access to.

Allow/Disallow MCP Tools

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.

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.

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

Public MCP Servers (allow_all_keys)

Some MCP servers are meant to be shared broadly—think internal knowledge bases, calendar integrations, or other low-risk utilities where every team should be able to connect without requesting access. Instead of adding those servers to every key, team, or organization, enable the new allow_all_keys toggle.

Open MCP Servers → Add / Edit in the Admin UI.
Expand Permission Management / Access Control.
Toggle Allow All LiteLLM Keys on.

The toggle makes the server “public” without touching existing access groups.

Set allow_all_keys: true to mark the server as public:

mcp_servers:
  deepwiki:
    url: https://mcp.deepwiki.com/mcp
    allow_all_keys: true

When to use it

You have shared MCP utilities where fine-grained ACLs would only add busywork.
You want a “default enabled” experience for internal users, while still being able to layer tool-level restrictions.
You’re onboarding new teams and want the safest MCPs available out of the box.

Once enabled, LiteLLM automatically includes the server for every key during tool discovery/calls—no extra virtual-key or team configuration is required.

Allow/Disallow MCP Tool Parameters

Control which parameters are allowed for specific MCP tools using the allowed_params configuration. This provides fine-grained control over tool usage by restricting the parameters that can be passed to each tool.

Configuration

allowed_params is a dictionary that maps tool names to lists of allowed parameter names. When configured, only the specified parameters will be accepted for that tool - any other parameters will be rejected with a 403 error.

mcp_servers:
  deepwiki_mcp:
    url: https://mcp.deepwiki.com/mcp
    transport: "http"
    auth_type: "none"
    allowed_params:
      # Tool name: list of allowed parameters
      read_wiki_contents: ["status"]
  
  my_api_mcp:
    url: "https://my-api-server.com"
    auth_type: "api_key"
    auth_value: "my-key"
    allowed_params:
      # Using unprefixed tool name
      getpetbyid: ["status"]
      # Using prefixed tool name (both formats work)
      my_api_mcp-findpetsbystatus: ["status", "limit"]
      # Another tool with multiple allowed params
      create_issue: ["title", "body", "labels"]

How It Works

Tool-specific filtering: Each tool can have its own list of allowed parameters
Flexible naming: Tool names can be specified with or without the server prefix (e.g., both "getpetbyid" and "my_api_mcp-getpetbyid" work)
Whitelist approach: Only parameters in the allowed list are permitted
Unlisted tools: If allowed_params is not set, all parameters are allowed
Error handling: Requests with disallowed parameters receive a 403 error with details about which parameters are allowed

Example Request Behavior

With the configuration above, here's how requests would be handled:

✅ Allowed Request:

{
  "tool": "read_wiki_contents",
  "arguments": {
    "status": "active"
  }
}

❌ Rejected Request:

{
  "tool": "read_wiki_contents",
  "arguments": {
    "status": "active",
    "limit": 10  // This parameter is not allowed
  }
}

Error Response:

{
  "error": "Parameters ['limit'] are not allowed for tool read_wiki_contents. Allowed parameters: ['status']. Contact proxy admin to allow these parameters."
}

Use Cases

Security: Prevent users from accessing sensitive parameters or dangerous operations
Cost control: Restrict expensive parameters (e.g., limiting result counts)
Compliance: Enforce parameter usage policies for regulatory requirements
Staged rollouts: Gradually enable parameters as tools are tested
Multi-tenant isolation: Different parameter access for different user groups

Combining with Tool Filtering

allowed_params works alongside allowed_tools and disallowed_tools for complete control:

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"]
    # Only allow specific tools
    allowed_tools: ["create_issue", "list_issues", "search_issues"]
    # Block dangerous operations
    disallowed_tools: ["delete_repo"]
    # Restrict parameters per tool
    allowed_params:
      create_issue: ["title", "body", "labels"]
      list_issues: ["state", "sort", "perPage"]
      search_issues: ["query", "sort", "order", "perPage"]

This configuration ensures that:

Only the three listed tools are available
The delete_repo tool is explicitly blocked
Each tool can only use its specified parameters

MCP Server Access Control

LiteLLM Proxy provides two methods for controlling access to specific MCP servers:

URL-based Namespacing - Use URL paths to directly access specific servers or access groups
Header-based Namespacing - Use the x-mcp-servers header to specify which servers to access

Method 1: URL-based Namespacing

LiteLLM Proxy supports URL-based namespacing for MCP servers using the format /<servers or access groups>/mcp. This allows you to:

Direct URL Access: Point MCP clients directly to specific servers or access groups via URL
Simplified Configuration: Use URLs instead of headers for server selection
Access Group Support: Use access group names in URLs for grouped server access

URL Format

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

Examples:

/github_mcp/mcp - Access tools from the "github_mcp" MCP server
/zapier/mcp - Access tools from the "zapier" MCP server
/dev_group/mcp - Access tools from all servers in the "dev_group" access group
/github_mcp,zapier/mcp - Access tools from multiple specific servers

Usage Examples

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>/github_mcp/mcp",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

This example uses URL namespacing to access only the "github" MCP server.

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": "litellm_proxy",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

This example uses the x-mcp-servers header to access all servers in the "dev_group" access group. Use server_url: "litellm_proxy" when calling the proxy's /v1/responses endpoint—do not use the full proxy URL.

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

This configuration uses URL namespacing to access tools from both "github" and "zapier" MCP servers.

Benefits of URL Namespacing

Direct Access: No need for additional headers to specify servers
Clean URLs: Self-documenting URLs that clearly indicate which servers are accessible
Access Group Support: Use access group names for grouped server access
Multiple Servers: Specify multiple servers in a single URL with comma separation
Simplified Configuration: Easier setup for MCP clients that prefer URL-based configuration

Method 2: Header-based Namespacing

You can choose to access specific MCP servers and only list their tools using the x-mcp-servers header. This header allows you to:

Limit tool access to one or more specific MCP servers
Control which tools are available in different environments or use cases

The header accepts a comma-separated list of server aliases: "alias_1,Server2,Server3"

Notes:

If the header is not provided, tools from all available MCP servers will be accessible
This method works with the standard LiteLLM MCP endpoint

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-servers": "alias_1"
            }
        }
    ],
    "input": "Run available tools",
    "tool_choice": "required"
}'

In this example, the request will only have access to tools from the "alias_1" MCP server.

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": "litellm_proxy",
            "require_approval": "never",
            "headers": {
                "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY",
                "x-mcp-servers": "alias_1,Server2"
            }
        }
    ],
    "input":