multicorn-shield 1.3.5 → 1.4.0

package/CHANGELOG.md

@@ -9,6 +9,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Bump `version` in `package.json` before publishing to npm.
 
+## [1.4.0] - 2026-05-08
+
+### Added
+
+- Hosted proxy wizard now prompts for upstream MCP server authentication (header name and value) when the target server requires credentials
+- Helpful examples shown during hosted proxy setup: common MCP server URLs (GitHub, Supabase, Atlassian, Stripe) with links to where to find tokens
+- Upstream auth headers are stored encrypted and forwarded by the proxy to the target MCP server on every request
+
+### Changed
+
+- Target MCP server URL prompt now shows common examples instead of a generic placeholder
+- "govern" replaced with "control" in all user-facing copy
+- "upstream auth" replaced with "server credentials" in all user-facing copy
+
+### Fixed
+
+- Hosted proxy connections to MCP servers requiring authentication (e.g. GitHub, Supabase) now work end-to-end - previously the proxy forwarded requests without credentials
+
+## [1.3.6] - 2026-05-08
+
+### Fixed
+
+- Hosted proxy URLs now embed the API key as a query parameter fallback for MCP clients that don't send static Authorization headers (fixes Cursor, Claude Desktop, and other clients that ignore the headers config during discovery)
+
 ## [1.3.5] - 2026-05-08
 
 ### Fixed

package/dist/multicorn-proxy.js

@@ -1500,8 +1500,8 @@ async function promptProxyConfig(ask, agentName) {
   while (targetUrl.length === 0) {
     process.stderr.write(
       "\n" + style.bold("Target MCP server URL:") + "\n" + style.dim(
-        "The URL of the MCP server you want Shield to protect. Example: https://your-server.example.com/mcp"
-      ) + "\n"
+        "This is the URL of the MCP server you want Shield to control. Common examples:"
+      ) + "\n" + style.dim("  GitHub:     https://api.githubcopilot.com/mcp/") + "\n" + style.dim("  Supabase:   https://mcp.supabase.com/sse") + "\n" + style.dim("  Atlassian:  https://mcp.atlassian.com/v1/sse") + "\n" + style.dim("  Stripe:     https://mcp.stripe.com/v1/sse") + "\n" + style.dim("Check your MCP server's documentation for the correct URL.") + "\n"
     );
     const input = await ask("URL: ");
     if (input.trim().length === 0) {
@@ -1521,10 +1521,44 @@ async function promptProxyConfig(ask, agentName) {
     targetUrl = input.trim();
   }
   const shortName = normalizeAgentName(agentName) || "shield-mcp";
-  return { targetUrl, shortName };
+  process.stderr.write(
+    "\n" + style.bold("Does this MCP server require authentication?") + "\n" + style.dim(
+      "Most MCP servers need a token or API key. Check the server's docs for how to get one:"
+    ) + "\n" + style.dim("  GitHub:     Settings > Developer Settings > Personal Access Tokens") + "\n" + style.dim(
+      "  Supabase:   Project Settings > API > anon or scoped key (service role bypasses RLS; avoid for most MCP)"
+    ) + "\n" + style.dim("  Atlassian:  id.atlassian.com > API Tokens") + "\n" + style.dim("  Stripe:     Dashboard > Developers > API Keys") + "\n"
+  );
+  const authReply = await ask("(y/N): ");
+  const authNorm = authReply.trim().toLowerCase();
+  const wantsAuth = authNorm === "y" || authNorm === "yes";
+  let upstreamHeaders;
+  if (wantsAuth) {
+    process.stderr.write(
+      "\n" + style.bold("Enter the Authorization header value.") + "\n" + style.dim("  For Bearer tokens: Bearer ghp_xxxxxxxxxxxx") + "\n" + style.dim("  For API keys:      Bearer sk-xxxxxxxxxxxx") + "\n"
+    );
+    const headerVal = await ask("Value: ");
+    const trimmed = headerVal.trim();
+    if (trimmed.length > 0) {
+      upstreamHeaders = { Authorization: trimmed };
+    }
+  }
+  return {
+    targetUrl,
+    shortName,
+    ...upstreamHeaders !== void 0 ? { upstreamHeaders } : {}
+  };
 }
-async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverName, platform) {
+async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverName, platform, upstreamHeaders) {
   let response;
+  const body = {
+    server_name: serverName,
+    target_url: targetUrl,
+    platform,
+    agent_name: agentName
+  };
+  if (upstreamHeaders !== void 0 && Object.keys(upstreamHeaders).length > 0) {
+    body["upstream_headers"] = upstreamHeaders;
+  }
   try {
     response = await fetch(`${baseUrl}/api/v1/proxy/config`, {
       method: "POST",
@@ -1532,12 +1566,7 @@ async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverNa
         "Content-Type": "application/json",
         "X-Multicorn-Key": apiKey
       },
-      body: JSON.stringify({
-        server_name: serverName,
-        target_url: targetUrl,
-        platform,
-        agent_name: agentName
-      }),
+      body: JSON.stringify(body),
       signal: AbortSignal.timeout(1e4)
     });
   } catch (error) {
@@ -1564,6 +1593,41 @@ async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverNa
   const data = envelope["data"];
   return typeof data?.["proxy_url"] === "string" ? data["proxy_url"] : "";
 }
+function shouldEmbedKeyInHostedProxyUrl(platform) {
+  return HOSTED_PROXY_PLATFORMS_WITH_URL_KEY.has(platform);
+}
+function hostedProxyUrlWithKeyParam(proxyUrl, apiKey) {
+  if (apiKey.length === 0) {
+    process.stderr.write(
+      style.yellow("\u26A0") + " Could not add key to proxy URL: API key is empty; using URL without key query parameter.\n"
+    );
+    return proxyUrl;
+  }
+  try {
+    const u = new URL(proxyUrl);
+    u.searchParams.set("key", apiKey);
+    return u.toString();
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      style.yellow("\u26A0") + " Could not parse proxy URL to append key query parameter; using URL unchanged. " + style.dim(detail) + "\n"
+    );
+    return proxyUrl;
+  }
+}
+function formatHostedProxyUrlForStderr(platform, proxyUrl, apiKey) {
+  if (!shouldEmbedKeyInHostedProxyUrl(platform) || apiKey.length === 0) {
+    return proxyUrl;
+  }
+  try {
+    const u = new URL(proxyUrl);
+    const redactedLabel = apiKey.length <= 4 ? "****" : `mcs_...${apiKey.slice(-4)}`;
+    u.searchParams.set("key", redactedLabel);
+    return u.toString();
+  } catch {
+    return proxyUrl;
+  }
+}
 function writeMcpAddedLine(shortName, filePath) {
   process.stderr.write(
     style.green("\u2713") + ' MCP server "' + shortName + '" added to ' + style.cyan(filePath) + "\n"
@@ -1713,8 +1777,9 @@ function printHostedProxyPostWriteHints(platform, shortName) {
 }
 async function applyHostedProxyMcpConfig(platform, proxyUrl, shortName, apiKey, workspacePath) {
   const authHeader = `Bearer ${apiKey}`;
+  const proxyUrlWithKeyWhenNeeded = shouldEmbedKeyInHostedProxyUrl(platform) ? hostedProxyUrlWithKeyParam(proxyUrl, apiKey) : proxyUrl;
   if (platform === "gemini-cli") {
-    await mergeGeminiHostedMcpServersIntoSettings(shortName, proxyUrl, apiKey);
+    await mergeGeminiHostedMcpServersIntoSettings(shortName, proxyUrlWithKeyWhenNeeded, apiKey);
     process.stderr.write(
       style.dim(
         "For project-specific config, copy the mcpServers entry into .gemini/settings.json in your project root. Restart Gemini CLI if it is already running."
@@ -1739,20 +1804,24 @@ async function applyHostedProxyMcpConfig(platform, proxyUrl, shortName, apiKey,
     let result = "parse-error";
     if (platform === "cursor") {
       result = await mergeMcpServersObjectStyle(getCursorMcpJsonPath(), shortName, {
-        url: proxyUrl,
+        url: proxyUrlWithKeyWhenNeeded,
         headers: { Authorization: authHeader }
       });
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getCursorMcpJsonPath());
       }
     } else if (platform === "claude-desktop") {
-      result = await mergeClaudeDesktopHostedMcpRemote(shortName, proxyUrl, apiKey);
+      result = await mergeClaudeDesktopHostedMcpRemote(
+        shortName,
+        proxyUrlWithKeyWhenNeeded,
+        apiKey
+      );
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getClaudeDesktopConfigPath());
       }
     } else if (platform === "windsurf") {
       result = await mergeMcpServersObjectStyle(getWindsurfMcpConfigPath(), shortName, {
-        serverUrl: proxyUrl,
+        serverUrl: proxyUrlWithKeyWhenNeeded,
         headers: { Authorization: authHeader }
       });
       if (result === "parse-error") {
@@ -1760,25 +1829,30 @@ async function applyHostedProxyMcpConfig(platform, proxyUrl, shortName, apiKey,
       }
     } else if (platform === "cline") {
       result = await mergeMcpServersObjectStyle(getClineMcpSettingsPath(), shortName, {
-        url: proxyUrl,
+        url: proxyUrlWithKeyWhenNeeded,
         headers: { Authorization: authHeader }
       });
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getClineMcpSettingsPath());
       }
     } else if (platform === "kilo-code") {
-      result = await mergeKiloCodeProjectMcp(workspacePath, shortName, proxyUrl, apiKey);
+      result = await mergeKiloCodeProjectMcp(
+        workspacePath,
+        shortName,
+        proxyUrlWithKeyWhenNeeded,
+        apiKey
+      );
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(join(workspacePath, ".kilocode", "mcp.json"));
       }
     } else if (platform === "continue-dev") {
-      result = await mergeContinueHostedMcp(shortName, proxyUrl, apiKey);
+      result = await mergeContinueHostedMcp(shortName, proxyUrlWithKeyWhenNeeded, apiKey);
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getContinueConfigJsonPath());
       }
     } else {
       result = await mergeMcpServersObjectStyle(getCursorMcpJsonPath(), shortName, {
-        url: proxyUrl,
+        url: proxyUrlWithKeyWhenNeeded,
         headers: { Authorization: authHeader }
       });
       if (result === "parse-error") {
@@ -1823,6 +1897,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
   ]);
   const usesInlineKey = hostedInlinePlatforms.has(platform);
   const authHeader = usesInlineKey ? `Bearer ${apiKey}` : "Bearer YOUR_SHIELD_API_KEY";
+  const urlInSnippet = usesInlineKey && shouldEmbedKeyInHostedProxyUrl(platform) ? hostedProxyUrlWithKeyParam(routingToken, apiKey) : routingToken;
   let snippetText;
   if (platform === "github-copilot") {
     snippetText = JSON.stringify(
@@ -1831,7 +1906,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
           servers: {
             [shortName]: {
               type: "http",
-              url: routingToken,
+              url: urlInSnippet,
               headers: {
                 Authorization: authHeader
               }
@@ -1843,13 +1918,13 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
       2
     );
   } else if (platform === "goose") {
-    snippetText = gooseHostedProxyYaml(shortName, routingToken, authHeader);
+    snippetText = gooseHostedProxyYaml(shortName, urlInSnippet, authHeader);
   } else if (platform === "gemini-cli") {
     snippetText = JSON.stringify(
       {
         mcpServers: {
           [shortName]: {
-            httpUrl: routingToken,
+            httpUrl: urlInSnippet,
             headers: {
               Authorization: authHeader
             }
@@ -1865,7 +1940,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
         mcpServers: {
           [shortName]: {
             command: "npx",
-            args: ["-y", "mcp-remote", routingToken, "--header", `Authorization: ${authHeader}`]
+            args: ["-y", "mcp-remote", urlInSnippet, "--header", `Authorization: ${authHeader}`]
           }
         }
       },
@@ -1879,7 +1954,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
           {
             name: shortName,
             type: "streamable-http",
-            url: routingToken,
+            url: urlInSnippet,
             headers: {
               Authorization: authHeader
             }
@@ -1895,7 +1970,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
       {
         mcpServers: {
           [shortName]: {
-            [urlKey]: routingToken,
+            [urlKey]: urlInSnippet,
             headers: {
               Authorization: authHeader
             }
@@ -2399,7 +2474,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
           }
         }
       } else {
-        const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+        const { targetUrl, shortName, upstreamHeaders } = await promptProxyConfig(ask, agentName);
         let proxyUrl = "";
         let created = false;
         while (!created) {
@@ -2411,7 +2486,8 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
               agentName,
               targetUrl,
               shortName,
-              selectedPlatform
+              selectedPlatform,
+              upstreamHeaders
             );
             spinner.stop(true, "Proxy config created!");
             created = true;
@@ -2426,7 +2502,9 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
         if (created && proxyUrl.length > 0) {
           process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
-          process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+          process.stderr.write(
+            "  " + style.cyan(formatHostedProxyUrlForStderr(selectedPlatform, proxyUrl, apiKey)) + "\n"
+          );
           await applyHostedProxyMcpConfig(
             selectedPlatform,
             proxyUrl,
@@ -2490,7 +2568,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
           }
         }
       } else {
-        const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+        const { targetUrl, shortName, upstreamHeaders } = await promptProxyConfig(ask, agentName);
         let proxyUrl = "";
         let created = false;
         while (!created) {
@@ -2502,7 +2580,8 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
               agentName,
               targetUrl,
               shortName,
-              selectedPlatform
+              selectedPlatform,
+              upstreamHeaders
             );
             spinner.stop(true, "Proxy config created!");
             created = true;
@@ -2517,7 +2596,9 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
         if (created && proxyUrl.length > 0) {
           process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
-          process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+          process.stderr.write(
+            "  " + style.cyan(formatHostedProxyUrlForStderr(selectedPlatform, proxyUrl, apiKey)) + "\n"
+          );
           await applyHostedProxyMcpConfig(
             selectedPlatform,
             proxyUrl,
@@ -2575,7 +2656,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
           }
         }
       } else {
-        const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+        const { targetUrl, shortName, upstreamHeaders } = await promptProxyConfig(ask, agentName);
         let proxyUrl = "";
         let created = false;
         while (!created) {
@@ -2587,7 +2668,8 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
               agentName,
               targetUrl,
               shortName,
-              selectedPlatform
+              selectedPlatform,
+              upstreamHeaders
             );
             spinner.stop(true, "Proxy config created!");
             created = true;
@@ -2602,7 +2684,9 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
         if (created && proxyUrl.length > 0) {
           process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
-          process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+          process.stderr.write(
+            "  " + style.cyan(formatHostedProxyUrlForStderr(selectedPlatform, proxyUrl, apiKey)) + "\n"
+          );
           await applyHostedProxyMcpConfig(
             selectedPlatform,
             proxyUrl,
@@ -2623,7 +2707,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
       }
     } else {
-      const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+      const { targetUrl, shortName, upstreamHeaders } = await promptProxyConfig(ask, agentName);
       let proxyUrl = "";
       let created = false;
       while (!created) {
@@ -2635,7 +2719,8 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
             agentName,
             targetUrl,
             shortName,
-            selectedPlatform
+            selectedPlatform,
+            upstreamHeaders
           );
           spinner.stop(true, "Proxy config created!");
           created = true;
@@ -2650,7 +2735,9 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
       }
       if (created && proxyUrl.length > 0) {
         process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
-        process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+        process.stderr.write(
+          "  " + style.cyan(formatHostedProxyUrlForStderr(selectedPlatform, proxyUrl, apiKey)) + "\n"
+        );
         await applyHostedProxyMcpConfig(
           selectedPlatform,
           proxyUrl,
@@ -2831,7 +2918,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
   }
   return lastConfig;
 }
-var SECRET_JSON_FILE_OPTIONS, style, BANNER, NativePluginPrerequisiteMissingError, CONFIG_DIR, CONFIG_PATH, OPENCLAW_CONFIG_PATH, ANSI_PATTERN, OPENCLAW_MIN_VERSION, INIT_WIZARD_PLATFORM_REGISTRY, INIT_WIZARD_MENU_SECTIONS, INIT_WIZARD_SELECTION_MAX, PLATFORM_BY_SELECTION, DEFAULT_SHIELD_API_BASE_URL;
+var SECRET_JSON_FILE_OPTIONS, style, BANNER, NativePluginPrerequisiteMissingError, CONFIG_DIR, CONFIG_PATH, OPENCLAW_CONFIG_PATH, ANSI_PATTERN, OPENCLAW_MIN_VERSION, INIT_WIZARD_PLATFORM_REGISTRY, INIT_WIZARD_MENU_SECTIONS, INIT_WIZARD_SELECTION_MAX, PLATFORM_BY_SELECTION, HOSTED_PROXY_PLATFORMS_WITH_URL_KEY, DEFAULT_SHIELD_API_BASE_URL;
 var init_config = __esm({
   "src/proxy/config.ts"() {
     init_consent();
@@ -2922,6 +3009,14 @@ var init_config = __esm({
     PLATFORM_BY_SELECTION = Object.fromEntries(
       INIT_WIZARD_PLATFORM_REGISTRY.map((e, i) => [i + 1, e.slug])
     );
+    HOSTED_PROXY_PLATFORMS_WITH_URL_KEY = /* @__PURE__ */ new Set([
+      "cursor",
+      "claude-desktop",
+      "github-copilot",
+      "kilo-code",
+      "continue-dev",
+      "goose"
+    ]);
     DEFAULT_SHIELD_API_BASE_URL = "https://api.multicorn.ai";
   }
 });

package/dist/multicorn-shield.js

@@ -1571,8 +1571,8 @@ async function promptProxyConfig(ask, agentName) {
   while (targetUrl.length === 0) {
     process.stderr.write(
       "\n" + style.bold("Target MCP server URL:") + "\n" + style.dim(
-        "The URL of the MCP server you want Shield to protect. Example: https://your-server.example.com/mcp"
-      ) + "\n"
+        "This is the URL of the MCP server you want Shield to control. Common examples:"
+      ) + "\n" + style.dim("  GitHub:     https://api.githubcopilot.com/mcp/") + "\n" + style.dim("  Supabase:   https://mcp.supabase.com/sse") + "\n" + style.dim("  Atlassian:  https://mcp.atlassian.com/v1/sse") + "\n" + style.dim("  Stripe:     https://mcp.stripe.com/v1/sse") + "\n" + style.dim("Check your MCP server's documentation for the correct URL.") + "\n"
     );
     const input = await ask("URL: ");
     if (input.trim().length === 0) {
@@ -1592,10 +1592,44 @@ async function promptProxyConfig(ask, agentName) {
     targetUrl = input.trim();
   }
   const shortName = normalizeAgentName(agentName) || "shield-mcp";
-  return { targetUrl, shortName };
+  process.stderr.write(
+    "\n" + style.bold("Does this MCP server require authentication?") + "\n" + style.dim(
+      "Most MCP servers need a token or API key. Check the server's docs for how to get one:"
+    ) + "\n" + style.dim("  GitHub:     Settings > Developer Settings > Personal Access Tokens") + "\n" + style.dim(
+      "  Supabase:   Project Settings > API > anon or scoped key (service role bypasses RLS; avoid for most MCP)"
+    ) + "\n" + style.dim("  Atlassian:  id.atlassian.com > API Tokens") + "\n" + style.dim("  Stripe:     Dashboard > Developers > API Keys") + "\n"
+  );
+  const authReply = await ask("(y/N): ");
+  const authNorm = authReply.trim().toLowerCase();
+  const wantsAuth = authNorm === "y" || authNorm === "yes";
+  let upstreamHeaders;
+  if (wantsAuth) {
+    process.stderr.write(
+      "\n" + style.bold("Enter the Authorization header value.") + "\n" + style.dim("  For Bearer tokens: Bearer ghp_xxxxxxxxxxxx") + "\n" + style.dim("  For API keys:      Bearer sk-xxxxxxxxxxxx") + "\n"
+    );
+    const headerVal = await ask("Value: ");
+    const trimmed = headerVal.trim();
+    if (trimmed.length > 0) {
+      upstreamHeaders = { Authorization: trimmed };
+    }
+  }
+  return {
+    targetUrl,
+    shortName,
+    ...upstreamHeaders !== void 0 ? { upstreamHeaders } : {}
+  };
 }
-async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverName, platform) {
+async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverName, platform, upstreamHeaders) {
   let response;
+  const body = {
+    server_name: serverName,
+    target_url: targetUrl,
+    platform,
+    agent_name: agentName
+  };
+  if (upstreamHeaders !== void 0 && Object.keys(upstreamHeaders).length > 0) {
+    body["upstream_headers"] = upstreamHeaders;
+  }
   try {
     response = await fetch(`${baseUrl}/api/v1/proxy/config`, {
       method: "POST",
@@ -1603,12 +1637,7 @@ async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverNa
         "Content-Type": "application/json",
         "X-Multicorn-Key": apiKey
       },
-      body: JSON.stringify({
-        server_name: serverName,
-        target_url: targetUrl,
-        platform,
-        agent_name: agentName
-      }),
+      body: JSON.stringify(body),
       signal: AbortSignal.timeout(1e4)
     });
   } catch (error) {
@@ -1635,6 +1664,49 @@ async function createProxyConfig(baseUrl, apiKey, agentName, targetUrl, serverNa
   const data = envelope["data"];
   return typeof data?.["proxy_url"] === "string" ? data["proxy_url"] : "";
 }
+var HOSTED_PROXY_PLATFORMS_WITH_URL_KEY = /* @__PURE__ */ new Set([
+  "cursor",
+  "claude-desktop",
+  "github-copilot",
+  "kilo-code",
+  "continue-dev",
+  "goose"
+]);
+function shouldEmbedKeyInHostedProxyUrl(platform) {
+  return HOSTED_PROXY_PLATFORMS_WITH_URL_KEY.has(platform);
+}
+function hostedProxyUrlWithKeyParam(proxyUrl, apiKey) {
+  if (apiKey.length === 0) {
+    process.stderr.write(
+      style.yellow("\u26A0") + " Could not add key to proxy URL: API key is empty; using URL without key query parameter.\n"
+    );
+    return proxyUrl;
+  }
+  try {
+    const u = new URL(proxyUrl);
+    u.searchParams.set("key", apiKey);
+    return u.toString();
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      style.yellow("\u26A0") + " Could not parse proxy URL to append key query parameter; using URL unchanged. " + style.dim(detail) + "\n"
+    );
+    return proxyUrl;
+  }
+}
+function formatHostedProxyUrlForStderr(platform, proxyUrl, apiKey) {
+  if (!shouldEmbedKeyInHostedProxyUrl(platform) || apiKey.length === 0) {
+    return proxyUrl;
+  }
+  try {
+    const u = new URL(proxyUrl);
+    const redactedLabel = apiKey.length <= 4 ? "****" : `mcs_...${apiKey.slice(-4)}`;
+    u.searchParams.set("key", redactedLabel);
+    return u.toString();
+  } catch {
+    return proxyUrl;
+  }
+}
 function writeMcpAddedLine(shortName, filePath) {
   process.stderr.write(
     style.green("\u2713") + ' MCP server "' + shortName + '" added to ' + style.cyan(filePath) + "\n"
@@ -1784,8 +1856,9 @@ function printHostedProxyPostWriteHints(platform, shortName) {
 }
 async function applyHostedProxyMcpConfig(platform, proxyUrl, shortName, apiKey, workspacePath) {
   const authHeader = `Bearer ${apiKey}`;
+  const proxyUrlWithKeyWhenNeeded = shouldEmbedKeyInHostedProxyUrl(platform) ? hostedProxyUrlWithKeyParam(proxyUrl, apiKey) : proxyUrl;
   if (platform === "gemini-cli") {
-    await mergeGeminiHostedMcpServersIntoSettings(shortName, proxyUrl, apiKey);
+    await mergeGeminiHostedMcpServersIntoSettings(shortName, proxyUrlWithKeyWhenNeeded, apiKey);
     process.stderr.write(
       style.dim(
         "For project-specific config, copy the mcpServers entry into .gemini/settings.json in your project root. Restart Gemini CLI if it is already running."
@@ -1810,20 +1883,24 @@ async function applyHostedProxyMcpConfig(platform, proxyUrl, shortName, apiKey,
     let result = "parse-error";
     if (platform === "cursor") {
       result = await mergeMcpServersObjectStyle(getCursorMcpJsonPath(), shortName, {
-        url: proxyUrl,
+        url: proxyUrlWithKeyWhenNeeded,
         headers: { Authorization: authHeader }
       });
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getCursorMcpJsonPath());
       }
     } else if (platform === "claude-desktop") {
-      result = await mergeClaudeDesktopHostedMcpRemote(shortName, proxyUrl, apiKey);
+      result = await mergeClaudeDesktopHostedMcpRemote(
+        shortName,
+        proxyUrlWithKeyWhenNeeded,
+        apiKey
+      );
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getClaudeDesktopConfigPath());
       }
     } else if (platform === "windsurf") {
       result = await mergeMcpServersObjectStyle(getWindsurfMcpConfigPath(), shortName, {
-        serverUrl: proxyUrl,
+        serverUrl: proxyUrlWithKeyWhenNeeded,
         headers: { Authorization: authHeader }
       });
       if (result === "parse-error") {
@@ -1831,25 +1908,30 @@ async function applyHostedProxyMcpConfig(platform, proxyUrl, shortName, apiKey,
       }
     } else if (platform === "cline") {
       result = await mergeMcpServersObjectStyle(getClineMcpSettingsPath(), shortName, {
-        url: proxyUrl,
+        url: proxyUrlWithKeyWhenNeeded,
         headers: { Authorization: authHeader }
       });
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getClineMcpSettingsPath());
       }
     } else if (platform === "kilo-code") {
-      result = await mergeKiloCodeProjectMcp(workspacePath, shortName, proxyUrl, apiKey);
+      result = await mergeKiloCodeProjectMcp(
+        workspacePath,
+        shortName,
+        proxyUrlWithKeyWhenNeeded,
+        apiKey
+      );
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(join(workspacePath, ".kilocode", "mcp.json"));
       }
     } else if (platform === "continue-dev") {
-      result = await mergeContinueHostedMcp(shortName, proxyUrl, apiKey);
+      result = await mergeContinueHostedMcp(shortName, proxyUrlWithKeyWhenNeeded, apiKey);
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getContinueConfigJsonPath());
       }
     } else {
       result = await mergeMcpServersObjectStyle(getCursorMcpJsonPath(), shortName, {
-        url: proxyUrl,
+        url: proxyUrlWithKeyWhenNeeded,
         headers: { Authorization: authHeader }
       });
       if (result === "parse-error") {
@@ -1894,6 +1976,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
   ]);
   const usesInlineKey = hostedInlinePlatforms.has(platform);
   const authHeader = usesInlineKey ? `Bearer ${apiKey}` : "Bearer YOUR_SHIELD_API_KEY";
+  const urlInSnippet = usesInlineKey && shouldEmbedKeyInHostedProxyUrl(platform) ? hostedProxyUrlWithKeyParam(routingToken, apiKey) : routingToken;
   let snippetText;
   if (platform === "github-copilot") {
     snippetText = JSON.stringify(
@@ -1902,7 +1985,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
           servers: {
             [shortName]: {
               type: "http",
-              url: routingToken,
+              url: urlInSnippet,
               headers: {
                 Authorization: authHeader
               }
@@ -1914,13 +1997,13 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
       2
     );
   } else if (platform === "goose") {
-    snippetText = gooseHostedProxyYaml(shortName, routingToken, authHeader);
+    snippetText = gooseHostedProxyYaml(shortName, urlInSnippet, authHeader);
   } else if (platform === "gemini-cli") {
     snippetText = JSON.stringify(
       {
         mcpServers: {
           [shortName]: {
-            httpUrl: routingToken,
+            httpUrl: urlInSnippet,
             headers: {
               Authorization: authHeader
             }
@@ -1936,7 +2019,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
         mcpServers: {
           [shortName]: {
             command: "npx",
-            args: ["-y", "mcp-remote", routingToken, "--header", `Authorization: ${authHeader}`]
+            args: ["-y", "mcp-remote", urlInSnippet, "--header", `Authorization: ${authHeader}`]
           }
         }
       },
@@ -1950,7 +2033,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
           {
             name: shortName,
             type: "streamable-http",
-            url: routingToken,
+            url: urlInSnippet,
             headers: {
               Authorization: authHeader
             }
@@ -1966,7 +2049,7 @@ function printPlatformSnippet(platform, routingToken, shortName, apiKey) {
       {
         mcpServers: {
           [shortName]: {
-            [urlKey]: routingToken,
+            [urlKey]: urlInSnippet,
             headers: {
               Authorization: authHeader
             }
@@ -2471,7 +2554,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
           }
         }
       } else {
-        const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+        const { targetUrl, shortName, upstreamHeaders } = await promptProxyConfig(ask, agentName);
         let proxyUrl = "";
         let created = false;
         while (!created) {
@@ -2483,7 +2566,8 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
               agentName,
               targetUrl,
               shortName,
-              selectedPlatform
+              selectedPlatform,
+              upstreamHeaders
             );
             spinner.stop(true, "Proxy config created!");
             created = true;
@@ -2498,7 +2582,9 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
         if (created && proxyUrl.length > 0) {
           process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
-          process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+          process.stderr.write(
+            "  " + style.cyan(formatHostedProxyUrlForStderr(selectedPlatform, proxyUrl, apiKey)) + "\n"
+          );
           await applyHostedProxyMcpConfig(
             selectedPlatform,
             proxyUrl,
@@ -2562,7 +2648,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
           }
         }
       } else {
-        const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+        const { targetUrl, shortName, upstreamHeaders } = await promptProxyConfig(ask, agentName);
         let proxyUrl = "";
         let created = false;
         while (!created) {
@@ -2574,7 +2660,8 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
               agentName,
               targetUrl,
               shortName,
-              selectedPlatform
+              selectedPlatform,
+              upstreamHeaders
             );
             spinner.stop(true, "Proxy config created!");
             created = true;
@@ -2589,7 +2676,9 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
         if (created && proxyUrl.length > 0) {
           process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
-          process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+          process.stderr.write(
+            "  " + style.cyan(formatHostedProxyUrlForStderr(selectedPlatform, proxyUrl, apiKey)) + "\n"
+          );
           await applyHostedProxyMcpConfig(
             selectedPlatform,
             proxyUrl,
@@ -2647,7 +2736,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
           }
         }
       } else {
-        const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+        const { targetUrl, shortName, upstreamHeaders } = await promptProxyConfig(ask, agentName);
         let proxyUrl = "";
         let created = false;
         while (!created) {
@@ -2659,7 +2748,8 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
               agentName,
               targetUrl,
               shortName,
-              selectedPlatform
+              selectedPlatform,
+              upstreamHeaders
             );
             spinner.stop(true, "Proxy config created!");
             created = true;
@@ -2674,7 +2764,9 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
         if (created && proxyUrl.length > 0) {
           process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
-          process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+          process.stderr.write(
+            "  " + style.cyan(formatHostedProxyUrlForStderr(selectedPlatform, proxyUrl, apiKey)) + "\n"
+          );
           await applyHostedProxyMcpConfig(
             selectedPlatform,
             proxyUrl,
@@ -2695,7 +2787,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
       }
     } else {
-      const { targetUrl, shortName } = await promptProxyConfig(ask, agentName);
+      const { targetUrl, shortName, upstreamHeaders } = await promptProxyConfig(ask, agentName);
       let proxyUrl = "";
       let created = false;
       while (!created) {
@@ -2707,7 +2799,8 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
             agentName,
             targetUrl,
             shortName,
-            selectedPlatform
+            selectedPlatform,
+            upstreamHeaders
           );
           spinner.stop(true, "Proxy config created!");
           created = true;
@@ -2722,7 +2815,9 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
       }
       if (created && proxyUrl.length > 0) {
         process.stderr.write("\n" + style.bold("Your Shield proxy URL:") + "\n");
-        process.stderr.write("  " + style.cyan(proxyUrl) + "\n");
+        process.stderr.write(
+          "  " + style.cyan(formatHostedProxyUrlForStderr(selectedPlatform, proxyUrl, apiKey)) + "\n"
+        );
         await applyHostedProxyMcpConfig(
           selectedPlatform,
           proxyUrl,

package/dist/shield-extension.js

@@ -22417,7 +22417,7 @@ async function writeExtensionBackup(claudeDesktopConfigPath, mcpServers) {
 
 // package.json
 var package_default = {
-  version: "1.3.5"};
+  version: "1.4.0"};
 
 // src/package-meta.ts
 var PACKAGE_VERSION = package_default.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multicorn-shield",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "The control layer for AI agents: permissions, consent, spending limits, and audit logging.",
   "license": "MIT",
   "author": "Multicorn AI Pty Ltd",