chore(internal): support x-stainless-mcp-client-envs header in MCP servers

Author: stainless-app[bot]

packages/mcp-server/src/code-tool.ts

@@ -144,22 +144,25 @@ const remoteStainlessHandler = async ({
 
   const codeModeEndpoint = readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
 
+  const localClientEnvs = {
+    IMAGEKIT_PRIVATE_KEY: requireValue(
+      readEnv('IMAGEKIT_PRIVATE_KEY') ?? client.privateKey,
+      'set IMAGEKIT_PRIVATE_KEY environment variable or provide privateKey client option',
+    ),
+    OPTIONAL_IMAGEKIT_IGNORES_THIS: readEnv('OPTIONAL_IMAGEKIT_IGNORES_THIS') ?? client.password ?? undefined,
+    IMAGEKIT_WEBHOOK_SECRET: readEnv('IMAGEKIT_WEBHOOK_SECRET') ?? client.webhookSecret ?? undefined,
+    IMAGE_KIT_BASE_URL: readEnv('IMAGE_KIT_BASE_URL') ?? client.baseURL ?? undefined,
+  };
+  // Merge any upstream client envs from the request header, with upstream values taking precedence.
+  const mergedClientEnvs = { ...localClientEnvs, ...reqContext.upstreamClientEnvs };
+
   // Setting a Stainless API key authenticates requests to the code tool endpoint.
   const res = await fetch(codeModeEndpoint, {
     method: 'POST',
     headers: {
       ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
       'Content-Type': 'application/json',
-      'x-stainless-mcp-client-envs': JSON.stringify({
-        IMAGEKIT_PRIVATE_KEY: requireValue(
-          readEnv('IMAGEKIT_PRIVATE_KEY') ?? client.privateKey,
-          'set IMAGEKIT_PRIVATE_KEY environment variable or provide privateKey client option',
-        ),
-        OPTIONAL_IMAGEKIT_IGNORES_THIS:
-          readEnv('OPTIONAL_IMAGEKIT_IGNORES_THIS') ?? client.password ?? undefined,
-        IMAGEKIT_WEBHOOK_SECRET: readEnv('IMAGEKIT_WEBHOOK_SECRET') ?? client.webhookSecret ?? undefined,
-        IMAGE_KIT_BASE_URL: readEnv('IMAGE_KIT_BASE_URL') ?? client.baseURL ?? undefined,
-      }),
+      'x-stainless-mcp-client-envs': JSON.stringify(mergedClientEnvs),
     },
     body: JSON.stringify({
       project_name: 'imagekit',
@@ -270,6 +273,9 @@ const localDenoHandler = async ({
     printOutput: true,
     spawnOptions: {
       cwd: path.dirname(workerPath),
+      // Merge any upstream client envs into the Deno subprocess environment,
+      // with the upstream env vars taking precedence.
+      env: { ...process.env, ...reqContext.upstreamClientEnvs },
     },
   });
 
@@ -279,15 +285,19 @@ const localDenoHandler = async ({
         reject(new Error(`Worker exited with code ${exitCode}`));
       });
 
-      const opts: ClientOptions = {
-        baseURL: client.baseURL,
-        privateKey: client.privateKey,
-        password: client.password,
-        webhookSecret: client.webhookSecret,
-        defaultHeaders: {
-          'X-Stainless-MCP': 'true',
-        },
-      };
+      // Strip null/undefined values so that the worker SDK client can fall back to
+      // reading from environment variables (including any upstreamClientEnvs).
+      const opts: ClientOptions = Object.fromEntries(
+        Object.entries({
+          baseURL: client.baseURL,
+          privateKey: client.privateKey,
+          password: client.password,
+          webhookSecret: client.webhookSecret,
+          defaultHeaders: {
+            'X-Stainless-MCP': 'true',
+          },
+        }).filter(([_, v]) => v != null),
+      ) as ClientOptions;
 
       const req = worker.request(
         'http://localhost',

packages/mcp-server/src/http.ts

@@ -27,6 +27,19 @@ const newServer = async ({
 
   const authOptions = parseClientAuthHeaders(req, false);
 
+  let upstreamClientEnvs: Record<string, string> | undefined;
+  const clientEnvsHeader = req.headers['x-stainless-mcp-client-envs'];
+  if (typeof clientEnvsHeader === 'string') {
+    try {
+      const parsed = JSON.parse(clientEnvsHeader);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        upstreamClientEnvs = parsed;
+      }
+    } catch {
+      // Ignore malformed header
+    }
+  }
+
   await initMcpServer({
     server: server,
     mcpOptions: mcpOptions,
@@ -35,6 +48,7 @@ const newServer = async ({
       ...authOptions,
     },
     stainlessApiKey: stainlessApiKey,
+    upstreamClientEnvs,
   });
 
   return server;
@@ -72,7 +86,7 @@ const del = async (req: express.Request, res: express.Response) => {
 };
 
 const redactHeaders = (headers: Record<string, any>) => {
-  const hiddenHeaders = /auth|cookie|key|token/i;
+  const hiddenHeaders = /auth|cookie|key|token|x-stainless-mcp-client-envs/i;
   const filtered = { ...headers };
   Object.keys(filtered).forEach((key) => {
     if (hiddenHeaders.test(key)) {

packages/mcp-server/src/server.ts

@@ -37,6 +37,7 @@ export async function initMcpServer(params: {
   clientOptions?: ClientOptions;
   mcpOptions?: McpOptions;
   stainlessApiKey?: string | undefined;
+  upstreamClientEnvs?: Record<string, string> | undefined;
 }) {
   const server = params.server instanceof McpServer ? params.server.server : params.server;
 
@@ -118,6 +119,7 @@ export async function initMcpServer(params: {
       reqContext: {
         client,
         stainlessApiKey: params.stainlessApiKey ?? params.mcpOptions?.stainlessApiKey,
+        upstreamClientEnvs: params.upstreamClientEnvs,
       },
       args,
     });

packages/mcp-server/src/types.ts

@@ -45,6 +45,7 @@ export type ToolCallResult = {
 export type McpRequestContext = {
   client: ImageKit;
   stainlessApiKey?: string | undefined;
+  upstreamClientEnvs?: Record<string, string> | undefined;
 };
 
 export type HandlerFunction = ({