From bc7733891ca6d07f3962d06774de7d2729445874 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sat, 7 Mar 2026 07:58:23 +0000
Subject: [PATCH] Fix MCP UI/docs inconsistencies: add server-specific auth
 headers to Connect tab

- Add 'Pass per-server authentication' toggle to the Connect tab's
  FeatureCard component, showing x-mcp-{alias}-{header} pattern with
  examples (GitHub authorization, Zapier API key)
- Update Extra Headers tooltip to clarify that clients must include
  these headers in their requests for forwarding to work
- Update Static Headers tooltip to clarify these are set server-side
  and don't require client action

These changes align the UI Connect templates with the documentation's
'Forwarding Custom Headers to MCP Servers' section, which already
documents x-mcp-{server_alias}-{header_name} as the recommended
per-server auth pattern.

Co-authored-by: Ishaan Jaff <ishaan-jaff@users.noreply.github.com>
---
 .../mcp_tools/MCPPermissionManagement.tsx     |  4 +-
 .../src/components/mcp_tools/mcp_connect.tsx  | 99 +++++++++++++------
 2 files changed, 71 insertions(+), 32 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/mcp_tools/MCPPermissionManagement.tsx b/ui/litellm-dashboard/src/components/mcp_tools/MCPPermissionManagement.tsx
index 89aa756cb27..660ca67e6b0 100644
--- a/ui/litellm-dashboard/src/components/mcp_tools/MCPPermissionManagement.tsx
+++ b/ui/litellm-dashboard/src/components/mcp_tools/MCPPermissionManagement.tsx
@@ -139,7 +139,7 @@ const MCPPermissionManagement: React.FC<MCPPermissionManagementProps> = ({
             label={
               <span className="text-sm font-medium text-gray-700 flex items-center">
                 Extra Headers
-                <Tooltip title="Forward custom headers from incoming requests to this MCP server (e.g., Authorization, X-Custom-Header, User-Agent)">
+                <Tooltip title="Header names to forward from client requests to this MCP server. Clients must include these headers in their requests (e.g., Authorization, X-Custom-Header). Only headers listed here will be forwarded.">
                   <InfoCircleOutlined className="ml-2 text-blue-400 hover:text-blue-600 cursor-help" />
                 </Tooltip>
                 {mcpServer?.extra_headers && mcpServer.extra_headers.length > 0 && (
@@ -169,7 +169,7 @@ const MCPPermissionManagement: React.FC<MCPPermissionManagementProps> = ({
             label={
               <span className="text-sm font-medium text-gray-700 flex items-center">
                 Static Headers
-                <Tooltip title="Send these key-value headers with every request to this MCP server.">
+                <Tooltip title="Fixed key-value headers sent with every request to this MCP server. These are set server-side and do not require the client to pass them.">
                   <InfoCircleOutlined className="ml-2 text-blue-400 hover:text-blue-600 cursor-help" />
                 </Tooltip>
               </span>
diff --git a/ui/litellm-dashboard/src/components/mcp_tools/mcp_connect.tsx b/ui/litellm-dashboard/src/components/mcp_tools/mcp_connect.tsx
index 1c82859e062..57e7cfa53dd 100644
--- a/ui/litellm-dashboard/src/components/mcp_tools/mcp_connect.tsx
+++ b/ui/litellm-dashboard/src/components/mcp_tools/mcp_connect.tsx
@@ -35,6 +35,7 @@ const FeatureCard: React.FC<FeatureCardProps> = ({
   accessGroups = ["dev-group"],
 }) => {
   const [useServerHeader, setUseServerHeader] = useState(false);
+  const [useServerAuth, setUseServerAuth] = useState(false);
 
   const getHeadersConfig = () => {
     const headers: Record<string, any> = {
@@ -42,10 +43,13 @@ const FeatureCard: React.FC<FeatureCardProps> = ({
     };
     if (useServerHeader && serverName) {
       const formattedServerName = serverName.replace(/\s+/g, "_");
-      // Include both server name and access groups in the same header (comma-separated string)
       const serverAndGroups = [formattedServerName, ...accessGroups].join(",");
       headers["x-mcp-servers"] = serverAndGroups;
     }
+    if (useServerAuth && serverName) {
+      const alias = serverName.replace(/\s+/g, "_").toLowerCase();
+      headers[`x-mcp-${alias}-authorization`] = "Bearer YOUR_SERVER_AUTH_TOKEN";
+    }
     return headers;
   };
 
@@ -61,35 +65,70 @@ const FeatureCard: React.FC<FeatureCardProps> = ({
         </div>
       </div>
       {serverName && (title === "Implementation Example" || title === "Configuration") && (
-        <Form.Item className="mb-4">
-          <div className="flex items-center gap-2 mb-2">
-            <Switch size="small" checked={useServerHeader} onChange={setUseServerHeader} />
-            <Text className="text-sm">
-              Limit tools to specific MCP servers or MCP groups by passing the <code>x-mcp-servers</code> header
-            </Text>
-          </div>
-          {useServerHeader && (
-            <Alert
-              className="mt-2"
-              type="info"
-              showIcon
-              message="Two Options"
-              description={
-                <div>
-                  <p>
-                    <strong>Option 1:</strong> Get a specific server: <code>"{serverName.replace(/\s+/g, "_")}"</code>
-                  </p>
-                  <p>
-                    <strong>Option 2:</strong> Get a group of MCPs: <code>"dev-group"</code>
-                  </p>
-                  <p className="mt-2 text-sm text-gray-600">
-                    You can also mix both: <code>"Server1,dev-group"</code>
-                  </p>
-                </div>
-              }
-            />
-          )}
-        </Form.Item>
+        <>
+          <Form.Item className="mb-4">
+            <div className="flex items-center gap-2 mb-2">
+              <Switch size="small" checked={useServerHeader} onChange={setUseServerHeader} />
+              <Text className="text-sm">
+                Limit tools to specific MCP servers or MCP groups by passing the <code>x-mcp-servers</code> header
+              </Text>
+            </div>
+            {useServerHeader && (
+              <Alert
+                className="mt-2"
+                type="info"
+                showIcon
+                message="Two Options"
+                description={
+                  <div>
+                    <p>
+                      <strong>Option 1:</strong> Get a specific server: <code>"{serverName.replace(/\s+/g, "_")}"</code>
+                    </p>
+                    <p>
+                      <strong>Option 2:</strong> Get a group of MCPs: <code>"dev-group"</code>
+                    </p>
+                    <p className="mt-2 text-sm text-gray-600">
+                      You can also mix both: <code>"Server1,dev-group"</code>
+                    </p>
+                  </div>
+                }
+              />
+            )}
+          </Form.Item>
+          <Form.Item className="mb-4">
+            <div className="flex items-center gap-2 mb-2">
+              <Switch size="small" checked={useServerAuth} onChange={setUseServerAuth} />
+              <Text className="text-sm">
+                Pass per-server authentication using <code>x-mcp-&#123;alias&#125;-&#123;header&#125;</code> headers
+              </Text>
+            </div>
+            {useServerAuth && (
+              <Alert
+                className="mt-2"
+                type="info"
+                showIcon
+                message="Server-Specific Auth Headers"
+                description={
+                  <div>
+                    <p>
+                      Format: <code>x-mcp-&#123;server_alias&#125;-&#123;header_name&#125;: value</code>
+                    </p>
+                    <p className="mt-1">
+                      <strong>Examples:</strong>
+                    </p>
+                    <ul className="mt-1 ml-4 list-disc">
+                      <li><code>x-mcp-github-authorization: Bearer ghp_xxx</code></li>
+                      <li><code>x-mcp-zapier-x-api-key: sk-xxx</code></li>
+                    </ul>
+                    <p className="mt-2 text-sm text-gray-600">
+                      Each MCP server can use different auth. The alias is the server&apos;s alias in lowercase.
+                    </p>
+                  </div>
+                }
+              />
+            )}
+          </Form.Item>
+        </>
       )}
       {React.Children.map(children, (child) => {
         if (