Check for existing issues

• I have searched the existing issues and checked that my issue is not a duplicate.

What happened?

What happened?

For MCP servers generated from an OpenAPI spec (spec_path / OpenAPI MCP), extra_headers does not forward request headers to the upstream API.

This makes it impossible to register an OpenAPI-backed MCP where the upstream API requires a caller-provided custom header such as X-TOKEN.

Example config:

mcp_servers:
  data_api:
    url: http://upstream-api.local
    spec_path: http://upstream-api.local/openapi.json
    auth_type: none
    extra_headers:
      - X-TOKEN

Then call the MCP endpoint with the required header:

curl -s -X POST http://localhost:4000/data_api/mcp \
  -H "x-litellm-api-key: Bearer $LITELLM_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-TOKEN: $UPSTREAM_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 1,
    "params": {
      "name": "<some-openapi-generated-tool>",
      "arguments": {}
    }
  }'

Expected: LiteLLM should forward X-TOKEN to the upstream OpenAPI endpoint.

Actual: the upstream receives no X-TOKEN header. APIs that require the header return a missing-header / unauthorized error.

Why this happens

The managed MCP path appears to support extra_headers passthrough. In server.py, _prepare_mcp_server_headers() copies configured server.extra_headers from raw_headers:

if server.extra_headers and raw_headers:
    if extra_headers is None:
        extra_headers = {}

    normalized_raw_headers = {
        str(k).lower(): v for k, v in raw_headers.items() if isinstance(k, str)
    }

    for header in server.extra_headers:
        header_value = normalized_raw_headers.get(header.lower())
        if header_value is not None:
            extra_headers[header] = header_value

But OpenAPI MCP tools do not use this managed MCP-client path. They are registered as local tool handlers during startup in mcp_server_manager.py.

During OpenAPI tool registration, LiteLLM explicitly notes that request-time extra_headers are not available:

# Note: `extra_headers` on MCPServer is a List[str] of header names to forward
# from the client request (not available in this OpenAPI tool generation step).
# `static_headers` is a dict of concrete headers to always send.
headers = (
    merge_mcp_headers(
        extra_headers=headers,
        static_headers=server.static_headers,
    )
    or {}
)

The generated OpenAPI tool then only has access to the closed-over headers dict plus a hard-coded Authorization ContextVar override:

effective_headers = dict(headers)
override_auth = _request_auth_header.get()
if override_auth:
    effective_headers["Authorization"] = override_auth

And the local/OpenAPI tool dispatch path in server.py only populates that ContextVar from mcp_auth_header (x-mcp-auth), formatting it as an auth header:

auth_header_value = None
if mcp_auth_header:
    if server_auth_type == MCPAuth.api_key:
        auth_header_value = f"ApiKey {mcp_auth_header}"
    elif server_auth_type == MCPAuth.basic:
        auth_header_value = f"Basic {mcp_auth_header}"
    else:
        auth_header_value = f"Bearer {mcp_auth_header}"
_request_auth_header.set(auth_header_value)

So there is currently no code path that carries arbitrary request headers like X-TOKEN into OpenAPI-generated tool execution.

Expected behavior

For OpenAPI-backed MCP servers, extra_headers should behave the same way it does for managed MCP servers: any configured header names should be copied from the incoming LiteLLM request and forwarded to the upstream OpenAPI endpoint.

For example:

extra_headers:
  - X-TOKEN

should cause incoming X-TOKEN: ... to be forwarded to the upstream request made by the generated OpenAPI tool.

Actual behavior

X-TOKEN is not forwarded.

Only these alternatives currently work:

• static_headers, if the token is fixed for all callers
• authentication_token, if the upstream accepts one of LiteLLM's supported auth formats
• x-mcp-auth, but only as a hard-coded Authorization override, not arbitrary headers

None of those solve per-request passthrough for APIs that require X-TOKEN, X-API-Key, or other custom caller-provided headers.

Related issues

This is related to, but not a duplicate of:

• #18169 - static_headers ignored for OpenAPI-based MCP servers. This covers static config-time headers, while this issue is about request-time extra_headers passthrough.
• #16508 - OAuth2 headers not passed to OpenAPI-based MCP tools. Same general root cause, but this issue covers arbitrary configured headers such as X-TOKEN.

Suggested fix

OpenAPI-generated MCP tools need a request-time header context similar to the existing _request_auth_header, but generalized for arbitrary configured headers.

One possible approach:

1. In the OpenAPI/local tool dispatch branch in server.py, build a dict from raw_headers using mcp_server.extra_headers.
2. Store that dict in a ContextVar before calling _handle_local_mcp_tool.
3. In openapi_to_mcp_generator.py, merge that ContextVar dict into effective_headers before making the upstream HTTP request.

Pseudo-shape:

effective_headers = dict(headers)

request_extra_headers = _request_extra_headers.get()
if request_extra_headers:
    effective_headers.update(request_extra_headers)

override_auth = _request_auth_header.get()
if override_auth:
    effective_headers["Authorization"] = override_auth

This would preserve existing behavior while making extra_headers work consistently across managed MCP servers and OpenAPI-backed MCP servers.

Workaround

Use static_headers if the upstream token is shared/static:

static_headers:
  X-TOKEN: "..."

But this does not work for caller-specific tokens and is not equivalent to extra_headers.

What part of LiteLLM is this about?

Proxy / MCP / OpenAPI MCP

What LiteLLM version are you on?

v1.83.10-stable

Relevant log output

Upstream API response depends on the API, but generally looks like:
{"detail":[{"loc":["headers","x-token"],"msg":"X-TOKEN header missing"}]}

Steps to Reproduce

1. Create an OpenAPI-backed MCP server with spec_path and extra_headers: ["X-TOKEN"].
2. Use an upstream OpenAPI endpoint that requires the X-TOKEN request header.
3. Call the generated MCP tool with X-TOKEN set on the request to LiteLLM.
4. Observe that the upstream API reports the header as missing.

Relevant log output

What part of LiteLLM is this about?

Proxy

What LiteLLM version are you on ?

v1.83.3-stable

Twitter / LinkedIn details

No response