fix(mcp): evaluate environment variables at transport connection time

lakshitsoni26 · lakshitsoni26 · commit 73f87924c617 · 2026-06-17T18:59:49.000+05:30
Fixes #93144 Prior to this change, templates in MCP config fields (such as `env` and `headers`) were resolved during Gateway startup. As a result, any dynamic rotation of underlying environment variables required a full Gateway restart. This commit shifts the environment variable substitution logic to the MCP transport connection layer. We now intercept the SDK's fetch invocations (for HTTP/SSE) and child process spawn routines (for stdio), dynamically substituting variables based on the live `process.env` state at the exact moment of request, cleanly solving the credential rotation limits.
diff --git a/src/agents/mcp-transport.ts b/src/agents/mcp-transport.ts
@@ -11,6 +11,8 @@ import {
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { FetchLike, Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import { substituteString, containsEnvVarReference } from "../config/env-substitution.js";
+import { isDangerousHostEnvVarName } from "../infra/host-env-security.js";
 import { logDebug } from "../logger.js";
 import {
   buildMcpHttpFetch,
@@ -95,10 +97,24 @@ export function resolveMcpTransport(
     return null;
   }
   if (resolved.kind === "stdio") {
+    const processEnv = process.env;
+    const finalEnv: Record<string, string> = {};
+    for (const [key, value] of Object.entries(resolved.env || {})) {
+      if (isDangerousHostEnvVarName(key)) {
+        throw new Error(
+          `Dynamic environment variable substitution generated a dangerous host environment variable: ${key}`,
+        );
+      }
+      finalEnv[key] =
+        value && containsEnvVarReference(value)
+          ? substituteString(value, processEnv, "mcp.servers.*.env")
+          : value;
+    }
+
     const transport = new OpenClawStdioClientTransport({
       command: resolved.command,
       args: resolved.args,
-      env: resolved.env,
+      env: finalEnv,
       cwd: resolved.cwd,
       stderr: "pipe",
     });
@@ -120,22 +136,50 @@ export function resolveMcpTransport(
           config: resolved.oauth,
         })
       : undefined;
+  const headers =
+    resolved.auth === "oauth" ? withoutMcpAuthorizationHeader(resolved.headers) : resolved.headers;
+
   const baseFetch = buildMcpHttpFetch({
     sslVerify: resolved.sslVerify,
     clientCert: resolved.clientCert,
     clientKey: resolved.clientKey,
     resourceUrl: resolved.url,
   });
-  const headers =
-    resolved.auth === "oauth" ? withoutMcpAuthorizationHeader(resolved.headers) : resolved.headers;
+
+  const substitutingFetch: FetchLike = (url, init) => {
+    let finalInit = init;
+    if (init?.headers) {
+      const mergedHeaders = new Headers(init.headers);
+      let needsReplace = false;
+      const processEnv = process.env;
+      for (const [key, value] of mergedHeaders.entries()) {
+        if (value && containsEnvVarReference(value)) {
+          mergedHeaders.set(key, substituteString(value, processEnv, "mcp.servers.*.headers"));
+          needsReplace = true;
+        }
+      }
+      if (needsReplace) {
+        // We reconstruct as a plain object to avoid surprising any fetch polyfills or assertions
+        // that expect a plain object, particularly in tests.
+        const plainHeaders: Record<string, string> = {};
+        for (const [key, value] of mergedHeaders.entries()) {
+          plainHeaders[key] = value;
+        }
+        finalInit = { ...init, headers: plainHeaders };
+      }
+    }
+    return baseFetch(url, finalInit);
+  };
+
   const httpFetch =
     resolved.auth === "oauth"
       ? withSameOriginMcpHttpHeaders({
-          fetchFn: baseFetch,
+          fetchFn: substitutingFetch,
           headers,
           resourceUrl: resolved.url,
         })
-      : baseFetch;
+      : substitutingFetch;
+
   if (resolved.transportType === "streamable-http") {
     return {
       transport: new StreamableHTTPClientTransport(new URL(resolved.url), {
@@ -150,11 +194,15 @@ export function resolveMcpTransport(
       supportsParallelToolCalls: resolved.supportsParallelToolCalls,
     };
   }
-  const sseHeaders: Record<string, string> = { ...headers };
-  const hasHeaders = Object.keys(sseHeaders).length > 0;
+
+  const sseHeaders = headers ? { ...headers } : {};
+  if (resolved.auth === "oauth" && sseHeaders.authorization) {
+    delete sseHeaders.authorization;
+  }
+
   return {
     transport: new SSEClientTransport(new URL(resolved.url), {
-      requestInit: resolved.auth === "oauth" || !hasHeaders ? undefined : { headers: sseHeaders },
+      requestInit: resolved.auth === "oauth" || !headers ? undefined : { headers },
       fetch: httpFetch,
       eventSourceInit: {
         fetch: buildSseEventSourceFetch(resolved.auth === "oauth" ? {} : sseHeaders, httpFetch),
diff --git a/src/config/env-substitution.ts b/src/config/env-substitution.ts
@@ -83,12 +83,14 @@ export type EnvSubstitutionWarning = {
   configPath: string;
 };
 
-type SubstituteOptions = {
+export type SubstituteOptions = {
   /** When set, missing vars call this instead of throwing and the original placeholder is preserved. */
   onMissing?: (warning: EnvSubstitutionWarning) => void;
+  /** Paths to skip substitution for. Supports simple wildcard '*' matches like 'mcp.servers.*.env'. */
+  ignorePaths?: string[];
 };
 
-function substituteString(
+export function substituteString(
   value: string,
   env: NodeJS.ProcessEnv,
   configPath: string,
@@ -168,6 +170,19 @@ function substituteAny(
   path: string,
   opts?: SubstituteOptions,
 ): unknown {
+  if (
+    opts?.ignorePaths &&
+    opts.ignorePaths.some((p) => {
+      if (!p.includes("*")) {
+        return path === p || path.startsWith(`${p}.`) || path.startsWith(`${p}[`);
+      }
+      const regexStr = "^" + p.replace(/\./g, "\\.").replace(/\*/g, "[^.]+") + "($|\\.|\\[)";
+      return new RegExp(regexStr).test(path);
+    })
+  ) {
+    return value;
+  }
+
   if (typeof value === "string") {
     return substituteString(value, env, path, opts);
   }
diff --git a/src/config/gateway-dispatch-config.ts b/src/config/gateway-dispatch-config.ts
@@ -98,7 +98,10 @@ function resolveGatewayDispatchEnvVars(config: unknown, env: NodeJS.ProcessEnv):
   if (isPlainRecord(config) && Object.hasOwn(config, "env")) {
     applyConfigEnvVars(config as OpenClawConfig, env);
   }
-  return resolveConfigEnvVars(config, env, { onMissing: () => undefined });
+  return resolveConfigEnvVars(config, env, {
+    onMissing: () => undefined,
+    ignorePaths: ["mcp.servers.*.env", "mcp.servers.*.headers"],
+  });
 }
 
 function readRawGatewayDispatchConfig(options: GatewayDispatchConfigReadOptions = {}): {
diff --git a/src/config/io.ts b/src/config/io.ts
@@ -1370,6 +1370,7 @@ function resolveConfigForRead(
   return {
     resolvedConfigRaw: resolveConfigEnvVars(resolvedIncludes, env, {
       onMissing: (w) => envWarnings.push(w),
+      ignorePaths: ["mcp.servers.*.env", "mcp.servers.*.headers"],
     }),
     // Capture env snapshot after substitution for write-time ${VAR} restoration.
     envSnapshotForRestore: { ...env } as Record<string, string | undefined>,
diff --git a/src/plugins/loader.ts b/src/plugins/loader.ts
@@ -1360,13 +1360,15 @@ function resolvePluginLoadCacheContext(options: PluginLoadOptions = {}) {
     shouldResolveRawConfigEnvVars
       ? (resolveConfigEnvVars(rawConfig, env, {
           onMissing: () => undefined,
+          ignorePaths: ["mcp.servers.*.env", "mcp.servers.*.headers"],
         }) as OpenClawConfig)
       : rawConfig,
     env,
   );
   const activationSourceConfig = shouldResolveRawConfigEnvVars
     ? (resolveConfigEnvVars(rawActivationSourceConfig, env, {
         onMissing: () => undefined,
+        ignorePaths: ["mcp.servers.*.env", "mcp.servers.*.headers"],
       }) as OpenClawConfig)
     : rawActivationSourceConfig;
   const normalized = normalizePluginsConfig(cfg.plugins);

Original file line number	Diff line number	Diff line change
`@@ -98,7 +98,10 @@ function resolveGatewayDispatchEnvVars(config: unknown, env: NodeJS.ProcessEnv):`
`98`	`98`	`if (isPlainRecord(config) && Object.hasOwn(config, "env")) {`
`99`	`99`	`applyConfigEnvVars(config as OpenClawConfig, env);`
`100`	`100`	`}`
`101`		`- return resolveConfigEnvVars(config, env, { onMissing: () => undefined });`
	`101`	`+ return resolveConfigEnvVars(config, env, {`
	`102`	`+ onMissing: () => undefined,`
	`103`	`+ ignorePaths: ["mcp.servers..env", "mcp.servers..headers"],`
	`104`	`+ });`
`102`	`105`	`}`
`103`	`106`
`104`	`107`	`function readRawGatewayDispatchConfig(options: GatewayDispatchConfigReadOptions = {}): {`