[Chore] update mcp documentation for header forwarding

[Sameerlite]

Relevant issues

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Type

🆕 New Feature
🐛 Bug Fix
🧹 Refactoring
📖 Documentation
🚄 Infrastructure
✅ Test

Changes

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Error		Mar 4, 2026 7:38am

[greptile-apps]

Greptile Summary

This PR updates MCP documentation and the dashboard UI to standardize on server_url: "litellm_proxy" when calling the proxy's /v1/responses endpoint, and adds a new documentation section explaining custom header forwarding to MCP servers via the x-mcp-{server_alias}-{header_name} pattern.

• mcp.md: Adds a new "Calling the Proxy's /v1/responses Endpoint" section with clear guidance on using litellm_proxy and two options for passing custom headers to MCP servers.
• mcp_control.md: Updates server_url from full proxy URLs to litellm_proxy in two LiteLLM Proxy code examples. However, one of the changes is in the "URL-based Namespacing" section and the updated description references an x-mcp-servers header that is absent from the code example.
• mcp_connect.tsx: Changes the LiteLLM Proxy tab's server_url from ${proxyBaseUrl}/mcp to litellm_proxy, aligning the dashboard with the documented pattern.

Confidence Score: 3/5

• Documentation-only changes with one code example inconsistency that could confuse users
• The PR is mostly safe (docs + minor UI change), but the mcp_control.md edit under "URL-based Namespacing" introduces a misleading example: the code no longer demonstrates URL namespacing, and the description references a header not present in the snippet. This could lead users to misconfigure their MCP setup.
• docs/my-website/docs/mcp_control.md — the LiteLLM Proxy tab under "Method 1: URL-based Namespacing" needs correction

Important Files Changed

Filename	Overview
docs/my-website/docs/mcp_control.md	Updated server_url to "litellm_proxy" in LiteLLM Proxy tabs, but the change under "URL-based Namespacing" removes the very URL namespacing being demonstrated, and adds an inaccurate description referencing a header not present in the code.
docs/my-website/docs/mcp.md	Adds new documentation section for calling the proxy's /v1/responses endpoint and sending custom headers to MCP servers. Content is clear and correctly demonstrates the litellm_proxy pattern and x-mcp-{server}-{header} header format.
ui/litellm-dashboard/src/components/mcp_tools/mcp_connect.tsx	Changed LiteLLM Proxy tab server_url from dynamic "${proxyBaseUrl}/mcp" to static "litellm_proxy". This is correct for the Responses API flow where the proxy intercepts the value internally.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Client sends request to<br>/v1/responses endpoint] --> B{server_url value?}
    B -->|"litellm_proxy"| C[LiteLLM Proxy intercepts<br>and routes internally]
    B -->|"full URL e.g. proxy.com/mcp"| D[Direct MCP connection<br>bypasses proxy routing]
    C --> E{Custom headers?}
    E -->|"x-mcp-{alias}-{header}"<br>in request headers| F[Proxy forwards header<br>to matching MCP server]
    E -->|"headers" in tool config| G[Headers merged and<br>forwarded to MCP server]
    E -->|None| H[Default routing<br>to all allowed servers]
    F --> I[MCP Server]
    G --> I
    H --> I

Loading

_{Last reviewed commit: 36999b2}

[greptile-apps]

URL namespacing example no longer demonstrates URL namespacing

This code example is in the "Method 1: URL-based Namespacing" section, but server_url was changed from "<your-litellm-proxy-base-url>/dev_group/mcp" (which demonstrated URL namespacing) to "litellm_proxy" (which is the generic proxy shorthand). The example no longer illustrates URL-based namespacing at all.

Additionally, the description on line 338 says "This example uses the x-mcp-servers header to access all servers in the 'dev_group' access group" — but the code snippet does not include the x-mcp-servers header anywhere. The description doesn't match the code.

Consider either:

1. Keeping the original URL namespacing example (server_url: "<your-litellm-proxy-base-url>/dev_group/mcp") since this section is specifically about URL-based namespacing, or
2. If litellm_proxy is intended here, add the x-mcp-servers: "dev_group" header to the headers object in the code example so the description is accurate.