From cfd3f730692dcebcab5597407ef7927e057c39da Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Tue, 24 Feb 2026 14:41:53 +0000
Subject: [PATCH 1/7] chore(internal): upgrade @modelcontextprotocol/sdk and
 hono

---
 packages/mcp-server/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
index 04a2225..bf8bb24 100644
--- a/packages/mcp-server/package.json
+++ b/packages/mcp-server/package.json
@@ -32,7 +32,7 @@
   "dependencies": {
     "scan-documents": "file:../../dist/",
     "@cloudflare/cabidela": "^0.2.4",
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@valtown/deno-http-worker": "^0.0.21",
     "cookie-parser": "^1.4.6",
     "cors": "^2.8.5",

From 1133800e1e21c15a3beb23b14dc3e917b6248146 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Wed, 25 Feb 2026 14:30:04 +0000
Subject: [PATCH 2/7] chore(internal): make MCP code execution location
 configurable via a flag

---
 packages/mcp-server/Dockerfile              |  14 +-
 packages/mcp-server/src/code-tool-paths.cts |   3 +
 packages/mcp-server/src/code-tool-types.ts  |   1 +
 packages/mcp-server/src/code-tool-worker.ts | 288 ++++++++++++++++++
 packages/mcp-server/src/code-tool.ts        | 312 +++++++++++++++++---
 packages/mcp-server/src/options.ts          |  12 +
 packages/mcp-server/src/server.ts           |   1 +
 packages/mcp-server/tests/options.test.ts   |  20 +-
 8 files changed, 584 insertions(+), 67 deletions(-)
 create mode 100644 packages/mcp-server/src/code-tool-paths.cts
 create mode 100644 packages/mcp-server/src/code-tool-worker.ts

diff --git a/packages/mcp-server/Dockerfile b/packages/mcp-server/Dockerfile
index 7c43a3b..9dccac0 100644
--- a/packages/mcp-server/Dockerfile
+++ b/packages/mcp-server/Dockerfile
@@ -37,9 +37,21 @@ COPY . .
 RUN yarn install --frozen-lockfile && \
     yarn build
 
-# Production stage
+FROM denoland/deno:bin-2.6.10 AS deno_installer
+FROM gcr.io/distroless/cc@sha256:66d87e170bc2c5e2b8cf853501141c3c55b4e502b8677595c57534df54a68cc5 AS cc
+
 FROM node:24-alpine
 
+# Install deno
+COPY --from=deno_installer /deno /usr/local/bin/deno
+
+# Add in shared libraries needed by Deno
+COPY --from=cc --chown=root:root --chmod=755 /lib/*-linux-gnu/* /usr/local/lib/
+COPY --from=cc --chown=root:root --chmod=755 /lib/ld-linux-* /lib/
+
+RUN mkdir /lib64 && ln -s /usr/local/lib/ld-linux-* /lib64/
+ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib
+
 # Add non-root user
 RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
 
diff --git a/packages/mcp-server/src/code-tool-paths.cts b/packages/mcp-server/src/code-tool-paths.cts
new file mode 100644
index 0000000..15ce7f5
--- /dev/null
+++ b/packages/mcp-server/src/code-tool-paths.cts
@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export const workerPath = require.resolve('./code-tool-worker.mjs');
diff --git a/packages/mcp-server/src/code-tool-types.ts b/packages/mcp-server/src/code-tool-types.ts
index bbbde4d..7607711 100644
--- a/packages/mcp-server/src/code-tool-types.ts
+++ b/packages/mcp-server/src/code-tool-types.ts
@@ -8,6 +8,7 @@ export type WorkerInput = {
   client_opts: ClientOptions;
   intent?: string | undefined;
 };
+
 export type WorkerOutput = {
   is_error: boolean;
   result: unknown | null;
diff --git a/packages/mcp-server/src/code-tool-worker.ts b/packages/mcp-server/src/code-tool-worker.ts
new file mode 100644
index 0000000..8a4dc1b
--- /dev/null
+++ b/packages/mcp-server/src/code-tool-worker.ts
@@ -0,0 +1,288 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import path from 'node:path';
+import util from 'node:util';
+import Fuse from 'fuse.js';
+import ts from 'typescript';
+import { WorkerOutput } from './code-tool-types';
+import { ScanDocuments, ClientOptions } from 'scan-documents';
+
+function getRunFunctionSource(code: string): {
+  type: 'declaration' | 'expression';
+  client: string | undefined;
+  code: string;
+} | null {
+  const sourceFile = ts.createSourceFile('code.ts', code, ts.ScriptTarget.Latest, true);
+  const printer = ts.createPrinter();
+
+  for (const statement of sourceFile.statements) {
+    // Check for top-level function declarations
+    if (ts.isFunctionDeclaration(statement)) {
+      if (statement.name?.text === 'run') {
+        return {
+          type: 'declaration',
+          client: statement.parameters[0]?.name.getText(),
+          code: printer.printNode(ts.EmitHint.Unspecified, statement.body!, sourceFile),
+        };
+      }
+    }
+
+    // Check for variable declarations: const run = () => {} or const run = function() {}
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (
+          ts.isIdentifier(declaration.name) &&
+          declaration.name.text === 'run' &&
+          // Check if it's initialized with a function
+          declaration.initializer &&
+          (ts.isFunctionExpression(declaration.initializer) || ts.isArrowFunction(declaration.initializer))
+        ) {
+          return {
+            type: 'expression',
+            client: declaration.initializer.parameters[0]?.name.getText(),
+            code: printer.printNode(ts.EmitHint.Unspecified, declaration.initializer, sourceFile),
+          };
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+function getTSDiagnostics(code: string): string[] {
+  const functionSource = getRunFunctionSource(code)!;
+  const codeWithImport = [
+    'import { ScanDocuments } from "scan-documents";',
+    functionSource.type === 'declaration' ?
+      `async function run(${functionSource.client}: ScanDocuments)`
+    : `const run: (${functionSource.client}: ScanDocuments) => Promise<unknown> =`,
+    functionSource.code,
+  ].join('\n');
+  const sourcePath = path.resolve('code.ts');
+  const ast = ts.createSourceFile(sourcePath, codeWithImport, ts.ScriptTarget.Latest, true);
+  const options = ts.getDefaultCompilerOptions();
+  options.target = ts.ScriptTarget.Latest;
+  options.module = ts.ModuleKind.NodeNext;
+  options.moduleResolution = ts.ModuleResolutionKind.NodeNext;
+  const host = ts.createCompilerHost(options, true);
+  const newHost: typeof host = {
+    ...host,
+    getSourceFile: (...args) => {
+      if (path.resolve(args[0]) === sourcePath) {
+        return ast;
+      }
+      return host.getSourceFile(...args);
+    },
+    readFile: (...args) => {
+      if (path.resolve(args[0]) === sourcePath) {
+        return codeWithImport;
+      }
+      return host.readFile(...args);
+    },
+    fileExists: (...args) => {
+      if (path.resolve(args[0]) === sourcePath) {
+        return true;
+      }
+      return host.fileExists(...args);
+    },
+  };
+  const program = ts.createProgram({
+    options,
+    rootNames: [sourcePath],
+    host: newHost,
+  });
+  const diagnostics = ts.getPreEmitDiagnostics(program, ast);
+  return diagnostics.map((d) => {
+    const message = ts.flattenDiagnosticMessageText(d.messageText, '\n');
+    if (!d.file || !d.start) return `- ${message}`;
+    const { line: lineNumber } = ts.getLineAndCharacterOfPosition(d.file, d.start);
+    const line = codeWithImport.split('\n').at(lineNumber)?.trim();
+    return line ? `- ${message}\n    ${line}` : `- ${message}`;
+  });
+}
+
+const fuse = new Fuse(
+  [
+    'client.files.delete',
+    'client.files.download',
+    'client.files.list',
+    'client.files.retrieve',
+    'client.files.upload',
+    'client.tasks.list',
+    'client.tasks.retrieve',
+    'client.events.list',
+    'client.imageOperations.applyEffect',
+    'client.imageOperations.convert',
+    'client.imageOperations.detectDocuments',
+    'client.imageOperations.extractText',
+    'client.imageOperations.scan',
+    'client.imageOperations.warp',
+    'client.pdfOperations.extractPages',
+    'client.pdfOperations.merge',
+    'client.pdfOperations.render',
+    'client.pdfOperations.split',
+  ],
+  { threshold: 1, shouldSort: true },
+);
+
+function getMethodSuggestions(fullyQualifiedMethodName: string): string[] {
+  return fuse
+    .search(fullyQualifiedMethodName)
+    .map(({ item }) => item)
+    .slice(0, 5);
+}
+
+const proxyToObj = new WeakMap<any, any>();
+const objToProxy = new WeakMap<any, any>();
+
+type ClientProxyConfig = {
+  path: string[];
+  isBelievedBad?: boolean;
+};
+
+function makeSdkProxy<T extends object>(obj: T, { path, isBelievedBad = false }: ClientProxyConfig): T {
+  let proxy: T = objToProxy.get(obj);
+
+  if (!proxy) {
+    proxy = new Proxy(obj, {
+      get(target, prop, receiver) {
+        const propPath = [...path, String(prop)];
+        const value = Reflect.get(target, prop, receiver);
+
+        if (isBelievedBad || (!(prop in target) && value === undefined)) {
+          // If we're accessing a path that doesn't exist, it will probably eventually error.
+          // Let's proxy it and mark it bad so that we can control the error message.
+          // We proxy an empty class so that an invocation or construction attempt is possible.
+          return makeSdkProxy(class {}, { path: propPath, isBelievedBad: true });
+        }
+
+        if (value !== null && (typeof value === 'object' || typeof value === 'function')) {
+          return makeSdkProxy(value, { path: propPath, isBelievedBad });
+        }
+
+        return value;
+      },
+
+      apply(target, thisArg, args) {
+        if (isBelievedBad || typeof target !== 'function') {
+          const fullyQualifiedMethodName = path.join('.');
+          const suggestions = getMethodSuggestions(fullyQualifiedMethodName);
+          throw new Error(
+            `${fullyQualifiedMethodName} is not a function. Did you mean: ${suggestions.join(', ')}`,
+          );
+        }
+
+        return Reflect.apply(target, proxyToObj.get(thisArg) ?? thisArg, args);
+      },
+
+      construct(target, args, newTarget) {
+        if (isBelievedBad || typeof target !== 'function') {
+          const fullyQualifiedMethodName = path.join('.');
+          const suggestions = getMethodSuggestions(fullyQualifiedMethodName);
+          throw new Error(
+            `${fullyQualifiedMethodName} is not a constructor. Did you mean: ${suggestions.join(', ')}`,
+          );
+        }
+
+        return Reflect.construct(target, args, newTarget);
+      },
+    });
+
+    objToProxy.set(obj, proxy);
+    proxyToObj.set(proxy, obj);
+  }
+
+  return proxy;
+}
+
+function parseError(code: string, error: unknown): string | undefined {
+  if (!(error instanceof Error)) return;
+  const message = error.name ? `${error.name}: ${error.message}` : error.message;
+  try {
+    // Deno uses V8; the first "<anonymous>:LINE:COLUMN" is the top of stack.
+    const lineNumber = error.stack?.match(/<anonymous>:([0-9]+):[0-9]+/)?.[1];
+    // -1 for the zero-based indexing
+    const line =
+      lineNumber &&
+      code
+        .split('\n')
+        .at(parseInt(lineNumber, 10) - 1)
+        ?.trim();
+    return line ? `${message}\n  at line ${lineNumber}\n    ${line}` : message;
+  } catch {
+    return message;
+  }
+}
+
+const fetch = async (req: Request): Promise<Response> => {
+  const { opts, code } = (await req.json()) as { opts: ClientOptions; code: string };
+
+  const runFunctionSource = code ? getRunFunctionSource(code) : null;
+  if (!runFunctionSource) {
+    const message =
+      code ?
+        'The code is missing a top-level `run` function.'
+      : 'The code argument is missing. Provide one containing a top-level `run` function.';
+    return Response.json(
+      {
+        is_error: true,
+        result: `${message} Write code within this template:\n\n\`\`\`\nasync function run(client) {\n  // Fill this out\n}\n\`\`\``,
+        log_lines: [],
+        err_lines: [],
+      } satisfies WorkerOutput,
+      { status: 400, statusText: 'Code execution error' },
+    );
+  }
+
+  const diagnostics = getTSDiagnostics(code);
+  if (diagnostics.length > 0) {
+    return Response.json(
+      {
+        is_error: true,
+        result: `The code contains TypeScript diagnostics:\n${diagnostics.join('\n')}`,
+        log_lines: [],
+        err_lines: [],
+      } satisfies WorkerOutput,
+      { status: 400, statusText: 'Code execution error' },
+    );
+  }
+
+  const client = new ScanDocuments({
+    ...opts,
+  });
+
+  const log_lines: string[] = [];
+  const err_lines: string[] = [];
+  const console = {
+    log: (...args: unknown[]) => {
+      log_lines.push(util.format(...args));
+    },
+    error: (...args: unknown[]) => {
+      err_lines.push(util.format(...args));
+    },
+  };
+  try {
+    let run_ = async (client: any) => {};
+    eval(`${code}\nrun_ = run;`);
+    const result = await run_(makeSdkProxy(client, { path: ['client'] }));
+    return Response.json({
+      is_error: false,
+      result,
+      log_lines,
+      err_lines,
+    } satisfies WorkerOutput);
+  } catch (e) {
+    return Response.json(
+      {
+        is_error: true,
+        result: parseError(code, e),
+        log_lines,
+        err_lines,
+      } satisfies WorkerOutput,
+      { status: 400, statusText: 'Code execution error' },
+    );
+  }
+};
+
+export default { fetch };
diff --git a/packages/mcp-server/src/code-tool.ts b/packages/mcp-server/src/code-tool.ts
index 3c5c3d9..6b0cf99 100644
--- a/packages/mcp-server/src/code-tool.ts
+++ b/packages/mcp-server/src/code-tool.ts
@@ -1,6 +1,12 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { newDenoHTTPWorker } from '@valtown/deno-http-worker';
+import { workerPath } from './code-tool-paths.cjs';
 import {
+  ContentBlock,
   McpRequestContext,
   McpTool,
   Metadata,
@@ -12,6 +18,8 @@ import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { readEnv, requireValue } from './util';
 import { WorkerInput, WorkerOutput } from './code-tool-types';
 import { SdkMethod } from './methods';
+import { McpCodeExecutionMode } from './options';
+import { ClientOptions } from 'scan-documents';
 
 const prompt = `Runs JavaScript code to interact with the Scan Documents API.
 
@@ -38,9 +46,19 @@ Variables will not persist between calls, so make sure to return or log any data
  * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then
  * a generic endpoint that can be used to invoke any endpoint with the provided arguments.
  *
- * @param endpoints - The endpoints to include in the list.
+ * @param blockedMethods - The methods to block for code execution. Blocking is done by simple string
+ * matching, so it is not secure against obfuscation. For stronger security, block in the downstream API
+ * with limited API keys.
+ * @param codeExecutionMode - Whether to execute code in a local Deno environment or in a remote
+ * sandbox environment hosted by Stainless.
  */
-export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | undefined }): McpTool {
+export function codeTool({
+  blockedMethods,
+  codeExecutionMode,
+}: {
+  blockedMethods: SdkMethod[] | undefined;
+  codeExecutionMode: McpCodeExecutionMode;
+}): McpTool {
   const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] };
   const tool: Tool = {
     name: 'execute',
@@ -60,6 +78,7 @@ export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | und
       required: ['code'],
     },
   };
+
   const handler = async ({
     reqContext,
     args,
@@ -68,9 +87,6 @@ export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | und
     args: any;
   }): Promise<ToolCallResult> => {
     const code = args.code as string;
-    const intent = args.intent as string | undefined;
-    const client = reqContext.client;
-
     // Do very basic blocking of code that includes forbidden method names.
     //
     // WARNING: This is not secure against obfuscation and other evasion methods. If
@@ -87,51 +103,253 @@ export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | und
       }
     }
 
-    const codeModeEndpoint =
-      readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
-
-    // 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',
-        client_envs: JSON.stringify({
-          SCAN_DOCUMENTS_API_KEY: requireValue(
-            readEnv('SCAN_DOCUMENTS_API_KEY') ?? client.apiKey,
-            'set SCAN_DOCUMENTS_API_KEY environment variable or provide apiKey client option',
-          ),
-          SCAN_DOCUMENTS_BASE_URL: readEnv('SCAN_DOCUMENTS_BASE_URL') ?? client.baseURL ?? undefined,
-        }),
-      },
-      body: JSON.stringify({
-        project_name: 'scan-documents',
-        code,
-        intent,
-        client_opts: {},
-      } satisfies WorkerInput),
-    });
+    if (codeExecutionMode === 'local') {
+      return await localDenoHandler({ reqContext, args });
+    } else {
+      return await remoteStainlessHandler({ reqContext, args });
+    }
+  };
+
+  return { metadata, tool, handler };
+}
+
+const remoteStainlessHandler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: any;
+}): Promise<ToolCallResult> => {
+  const code = args.code as string;
+  const intent = args.intent as string | undefined;
+  const client = reqContext.client;
 
-    if (!res.ok) {
-      throw new Error(
-        `${res.status}: ${
-          res.statusText
-        } error when trying to contact Code Tool server. Details: ${await res.text()}`,
+  const codeModeEndpoint = readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
+
+  // 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',
+      client_envs: JSON.stringify({
+        SCAN_DOCUMENTS_API_KEY: requireValue(
+          readEnv('SCAN_DOCUMENTS_API_KEY') ?? client.apiKey,
+          'set SCAN_DOCUMENTS_API_KEY environment variable or provide apiKey client option',
+        ),
+        SCAN_DOCUMENTS_BASE_URL: readEnv('SCAN_DOCUMENTS_BASE_URL') ?? client.baseURL ?? undefined,
+      }),
+    },
+    body: JSON.stringify({
+      project_name: 'scan-documents',
+      code,
+      intent,
+      client_opts: {},
+    } satisfies WorkerInput),
+  });
+
+  if (!res.ok) {
+    throw new Error(
+      `${res.status}: ${
+        res.statusText
+      } error when trying to contact Code Tool server. Details: ${await res.text()}`,
+    );
+  }
+
+  const { is_error, result, log_lines, err_lines } = (await res.json()) as WorkerOutput;
+  const hasLogs = log_lines.length > 0 || err_lines.length > 0;
+  const output = {
+    result,
+    ...(log_lines.length > 0 && { log_lines }),
+    ...(err_lines.length > 0 && { err_lines }),
+  };
+  if (is_error) {
+    return asErrorResult(typeof result === 'string' && !hasLogs ? result : JSON.stringify(output, null, 2));
+  }
+  return asTextContentResult(output);
+};
+
+const localDenoHandler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: unknown;
+}): Promise<ToolCallResult> => {
+  const client = reqContext.client;
+  const baseURLHostname = new URL(client.baseURL).hostname;
+  const { code } = args as { code: string };
+
+  let denoPath: string;
+
+  const packageRoot = path.resolve(path.dirname(workerPath), '..');
+  const packageNodeModulesPath = path.resolve(packageRoot, 'node_modules');
+
+  // Check if deno is in PATH
+  const { execSync } = await import('node:child_process');
+  try {
+    execSync('command -v deno', { stdio: 'ignore' });
+    denoPath = 'deno';
+  } catch {
+    try {
+      // Use deno binary in node_modules if it's found
+      const denoNodeModulesPath = path.resolve(packageNodeModulesPath, 'deno', 'bin.cjs');
+      await fs.promises.access(denoNodeModulesPath, fs.constants.X_OK);
+      denoPath = denoNodeModulesPath;
+    } catch {
+      return asErrorResult(
+        'Deno is required for code execution but was not found. ' +
+          'Install it from https://deno.land or run: npm install deno',
       );
     }
+  }
+
+  const allowReadPaths = [
+    'code-tool-worker.mjs',
+    `${workerPath.replace(/([\/\\]node_modules)[\/\\].+$/, '$1')}/`,
+    packageRoot,
+  ];
 
-    const { is_error, result, log_lines, err_lines } = (await res.json()) as WorkerOutput;
-    const hasLogs = log_lines.length > 0 || err_lines.length > 0;
-    const output = {
-      result,
-      ...(log_lines.length > 0 && { log_lines }),
-      ...(err_lines.length > 0 && { err_lines }),
-    };
-    if (is_error) {
-      return asErrorResult(typeof result === 'string' && !hasLogs ? result : JSON.stringify(output, null, 2));
+  // Follow symlinks in node_modules to allow read access to workspace-linked packages
+  try {
+    const sdkPkgName = 'scan-documents';
+    const sdkDir = path.resolve(packageNodeModulesPath, sdkPkgName);
+    const realSdkDir = fs.realpathSync(sdkDir);
+    if (realSdkDir !== sdkDir) {
+      allowReadPaths.push(realSdkDir);
     }
-    return asTextContentResult(output);
-  };
+  } catch {
+    // Ignore if symlink resolution fails
+  }
 
-  return { metadata, tool, handler };
-}
+  const allowRead = allowReadPaths.join(',');
+
+  const worker = await newDenoHTTPWorker(url.pathToFileURL(workerPath), {
+    denoExecutable: denoPath,
+    runFlags: [
+      `--node-modules-dir=manual`,
+      `--allow-read=${allowRead}`,
+      `--allow-net=${baseURLHostname}`,
+      // Allow environment variables because instantiating the client will try to read from them,
+      // even though they are not set.
+      '--allow-env',
+    ],
+    printOutput: true,
+    spawnOptions: {
+      cwd: path.dirname(workerPath),
+    },
+  });
+
+  try {
+    const resp = await new Promise<Response>((resolve, reject) => {
+      worker.addEventListener('exit', (exitCode) => {
+        reject(new Error(`Worker exited with code ${exitCode}`));
+      });
+
+      const opts: ClientOptions = {
+        baseURL: client.baseURL,
+        apiKey: client.apiKey,
+        defaultHeaders: {
+          'X-Stainless-MCP': 'true',
+        },
+      };
+
+      const req = worker.request(
+        'http://localhost',
+        {
+          headers: {
+            'content-type': 'application/json',
+          },
+          method: 'POST',
+        },
+        (resp) => {
+          const body: Uint8Array[] = [];
+          resp.on('error', (err) => {
+            reject(err);
+          });
+          resp.on('data', (chunk) => {
+            body.push(chunk);
+          });
+          resp.on('end', () => {
+            resolve(
+              new Response(Buffer.concat(body).toString(), {
+                status: resp.statusCode ?? 200,
+                headers: resp.headers as any,
+              }),
+            );
+          });
+        },
+      );
+
+      const body = JSON.stringify({
+        opts,
+        code,
+      });
+
+      req.write(body, (err) => {
+        if (err != null) {
+          reject(err);
+        }
+      });
+
+      req.end();
+    });
+
+    if (resp.status === 200) {
+      const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput;
+      const returnOutput: ContentBlock | null =
+        result == null ? null : (
+          {
+            type: 'text',
+            text: typeof result === 'string' ? result : JSON.stringify(result),
+          }
+        );
+      const logOutput: ContentBlock | null =
+        log_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: log_lines.join('\n'),
+          };
+      const errOutput: ContentBlock | null =
+        err_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: 'Error output:\n' + err_lines.join('\n'),
+          };
+      return {
+        content: [returnOutput, logOutput, errOutput].filter((block) => block !== null),
+      };
+    } else {
+      const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput;
+      const messageOutput: ContentBlock | null =
+        result == null ? null : (
+          {
+            type: 'text',
+            text: typeof result === 'string' ? result : JSON.stringify(result),
+          }
+        );
+      const logOutput: ContentBlock | null =
+        log_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: log_lines.join('\n'),
+          };
+      const errOutput: ContentBlock | null =
+        err_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: 'Error output:\n' + err_lines.join('\n'),
+          };
+      return {
+        content: [messageOutput, logOutput, errOutput].filter((block) => block !== null),
+        isError: true,
+      };
+    }
+  } finally {
+    worker.terminate();
+  }
+};
diff --git a/packages/mcp-server/src/options.ts b/packages/mcp-server/src/options.ts
index 32a8871..9e9d15c 100644
--- a/packages/mcp-server/src/options.ts
+++ b/packages/mcp-server/src/options.ts
@@ -19,8 +19,11 @@ export type McpOptions = {
   codeAllowHttpGets?: boolean | undefined;
   codeAllowedMethods?: string[] | undefined;
   codeBlockedMethods?: string[] | undefined;
+  codeExecutionMode: McpCodeExecutionMode;
 };
 
+export type McpCodeExecutionMode = 'stainless-sandbox' | 'local';
+
 export function parseCLIOptions(): CLIOptions {
   const opts = yargs(hideBin(process.argv))
     .option('code-allow-http-gets', {
@@ -40,6 +43,13 @@ export function parseCLIOptions(): CLIOptions {
       description:
         'Methods to explicitly block for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.',
     })
+    .option('code-execution-mode', {
+      type: 'string',
+      choices: ['stainless-sandbox', 'local'],
+      default: 'stainless-sandbox',
+      description:
+        "Where to run code execution in code tool; 'stainless-sandbox' will execute code in Stainless-hosted sandboxes whereas 'local' will execute code locally on the MCP server machine.",
+    })
     .option('debug', { type: 'boolean', description: 'Enable debug logging' })
     .option('no-tools', {
       type: 'string',
@@ -93,6 +103,7 @@ export function parseCLIOptions(): CLIOptions {
     codeAllowHttpGets: argv.codeAllowHttpGets,
     codeAllowedMethods: argv.codeAllowedMethods,
     codeBlockedMethods: argv.codeBlockedMethods,
+    codeExecutionMode: argv.codeExecutionMode as McpCodeExecutionMode,
     transport,
     port: argv.port,
     socket: argv.socket,
@@ -124,6 +135,7 @@ export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): M
     : defaultOptions.includeDocsTools;
 
   return {
+    codeExecutionMode: defaultOptions.codeExecutionMode,
     ...(docsTools !== undefined && { includeDocsTools: docsTools }),
   };
 }
diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts
index 7eb4b3d..4f95d54 100644
--- a/packages/mcp-server/src/server.ts
+++ b/packages/mcp-server/src/server.ts
@@ -159,6 +159,7 @@ export function selectTools(options?: McpOptions): McpTool[] {
   const includedTools = [
     codeTool({
       blockedMethods: blockedMethodsForCodeTool(options),
+      codeExecutionMode: options?.codeExecutionMode ?? 'stainless-sandbox',
     }),
   ];
   if (options?.includeDocsTools ?? true) {
diff --git a/packages/mcp-server/tests/options.test.ts b/packages/mcp-server/tests/options.test.ts
index 7a2d511..1730629 100644
--- a/packages/mcp-server/tests/options.test.ts
+++ b/packages/mcp-server/tests/options.test.ts
@@ -1,4 +1,4 @@
-import { parseCLIOptions, parseQueryOptions } from '../src/options';
+import { parseCLIOptions } from '../src/options';
 
 // Mock process.argv
 const mockArgv = (args: string[]) => {
@@ -30,21 +30,3 @@ describe('parseCLIOptions', () => {
     cleanup();
   });
 });
-
-describe('parseQueryOptions', () => {
-  const defaultOptions = {};
-
-  it('default parsing should be empty', () => {
-    const query = '';
-    const result = parseQueryOptions(defaultOptions, query);
-
-    expect(result).toEqual({});
-  });
-
-  it('should handle invalid query string gracefully', () => {
-    const query = 'invalid=value&tools=invalid-operation';
-
-    // Should throw due to Zod validation for invalid tools
-    expect(() => parseQueryOptions(defaultOptions, query)).toThrow();
-  });
-});

From 4b55b1fae74f0ea3106258ccf85863a9172582c2 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Thu, 26 Feb 2026 11:12:17 +0000
Subject: [PATCH 3/7] chore(internal): fix MCP Dockerfiles so they can be built
 without buildkit

---
 packages/mcp-server/Dockerfile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/mcp-server/Dockerfile b/packages/mcp-server/Dockerfile
index 9dccac0..5a308fc 100644
--- a/packages/mcp-server/Dockerfile
+++ b/packages/mcp-server/Dockerfile
@@ -46,8 +46,8 @@ FROM node:24-alpine
 COPY --from=deno_installer /deno /usr/local/bin/deno
 
 # Add in shared libraries needed by Deno
-COPY --from=cc --chown=root:root --chmod=755 /lib/*-linux-gnu/* /usr/local/lib/
-COPY --from=cc --chown=root:root --chmod=755 /lib/ld-linux-* /lib/
+COPY --from=cc /lib/*-linux-gnu/* /usr/local/lib/
+COPY --from=cc /lib/ld-linux-* /lib/
 
 RUN mkdir /lib64 && ln -s /usr/local/lib/ld-linux-* /lib64/
 ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib

From e1a34c1c73ba4bf2cd8aed8e96e857c194fedc9a Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Thu, 26 Feb 2026 11:14:53 +0000
Subject: [PATCH 4/7] chore(internal): fix MCP Dockerfiles so they can be built
 without buildkit

---
 packages/mcp-server/Dockerfile | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/packages/mcp-server/Dockerfile b/packages/mcp-server/Dockerfile
index 5a308fc..17b153c 100644
--- a/packages/mcp-server/Dockerfile
+++ b/packages/mcp-server/Dockerfile
@@ -37,19 +37,11 @@ COPY . .
 RUN yarn install --frozen-lockfile && \
     yarn build
 
-FROM denoland/deno:bin-2.6.10 AS deno_installer
-FROM gcr.io/distroless/cc@sha256:66d87e170bc2c5e2b8cf853501141c3c55b4e502b8677595c57534df54a68cc5 AS cc
+FROM denoland/deno:alpine-2.7.1
 
-FROM node:24-alpine
+# Install node and npm
+RUN apk add --no-cache nodejs npm
 
-# Install deno
-COPY --from=deno_installer /deno /usr/local/bin/deno
-
-# Add in shared libraries needed by Deno
-COPY --from=cc /lib/*-linux-gnu/* /usr/local/lib/
-COPY --from=cc /lib/ld-linux-* /lib/
-
-RUN mkdir /lib64 && ln -s /usr/local/lib/ld-linux-* /lib64/
 ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib
 
 # Add non-root user
@@ -69,6 +61,7 @@ COPY --from=builder /build/dist ./node_modules/scan-documents
 
 # Change ownership to nodejs user
 RUN chown -R nodejs:nodejs /app
+RUN chown -R nodejs:nodejs /deno-dir
 
 # Switch to non-root user
 USER nodejs

From 3c528b41d05fc52d1259d88192f6a9db5ed9717c Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Fri, 27 Feb 2026 14:34:08 +0000
Subject: [PATCH 5/7] chore(internal): move stringifyQuery implementation to
 internal function

---
 src/client.ts                | 22 +++++-----------------
 src/internal/utils.ts        |  1 +
 src/internal/utils/query.ts  | 23 +++++++++++++++++++++++
 tests/stringifyQuery.test.ts |  6 ++----
 4 files changed, 31 insertions(+), 21 deletions(-)
 create mode 100644 src/internal/utils/query.ts

diff --git a/src/client.ts b/src/client.ts
index e41b493..4c7ee33 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -11,6 +11,7 @@ import type { APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
+import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
 import * as Uploads from './core/uploads';
@@ -248,21 +249,8 @@ export class ScanDocuments {
   /**
    * Basic re-implementation of `qs.stringify` for primitive types.
    */
-  protected stringifyQuery(query: Record<string, unknown>): string {
-    return Object.entries(query)
-      .filter(([_, value]) => typeof value !== 'undefined')
-      .map(([key, value]) => {
-        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-          return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
-        }
-        if (value === null) {
-          return `${encodeURIComponent(key)}=`;
-        }
-        throw new Errors.ScanDocumentsError(
-          `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
-        );
-      })
-      .join('&');
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
   }
 
   private getUserAgent(): string {
@@ -299,7 +287,7 @@ export class ScanDocuments {
     }
 
     if (typeof query === 'object' && query && !Array.isArray(query)) {
-      url.search = this.stringifyQuery(query as Record<string, unknown>);
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
@@ -738,7 +726,7 @@ export class ScanDocuments {
     ) {
       return {
         bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
-        body: this.stringifyQuery(body as Record<string, unknown>),
+        body: this.stringifyQuery(body),
       };
     } else {
       return this.#encoder({ body, headers });
diff --git a/src/internal/utils.ts b/src/internal/utils.ts
index 3cbfacc..c591353 100644
--- a/src/internal/utils.ts
+++ b/src/internal/utils.ts
@@ -6,3 +6,4 @@ export * from './utils/env';
 export * from './utils/log';
 export * from './utils/uuid';
 export * from './utils/sleep';
+export * from './utils/query';
diff --git a/src/internal/utils/query.ts b/src/internal/utils/query.ts
new file mode 100644
index 0000000..6afe716
--- /dev/null
+++ b/src/internal/utils/query.ts
@@ -0,0 +1,23 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { ScanDocumentsError } from '../../core/error';
+
+/**
+ * Basic re-implementation of `qs.stringify` for primitive types.
+ */
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return Object.entries(query)
+    .filter(([_, value]) => typeof value !== 'undefined')
+    .map(([key, value]) => {
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+      }
+      if (value === null) {
+        return `${encodeURIComponent(key)}=`;
+      }
+      throw new ScanDocumentsError(
+        `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
+      );
+    })
+    .join('&');
+}
diff --git a/tests/stringifyQuery.test.ts b/tests/stringifyQuery.test.ts
index 0e0f410..86f502f 100644
--- a/tests/stringifyQuery.test.ts
+++ b/tests/stringifyQuery.test.ts
@@ -1,8 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { ScanDocuments } from 'scan-documents';
-
-const { stringifyQuery } = ScanDocuments.prototype as any;
+import { stringifyQuery } from 'scan-documents/internal/utils/query';
 
 describe(stringifyQuery, () => {
   for (const [input, expected] of [
@@ -15,7 +13,7 @@ describe(stringifyQuery, () => {
         'e=f',
       )}=${encodeURIComponent('g&h')}`,
     ],
-  ]) {
+  ] as const) {
     it(`${JSON.stringify(input)} -> ${expected}`, () => {
       expect(stringifyQuery(input)).toEqual(expected);
     });

From da647e2d55b35d55460133d6787eef4f28d896ef Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Fri, 27 Feb 2026 14:37:08 +0000
Subject: [PATCH 6/7] feat(mcp): add an option to disable code tool

You can now disable the code tool via a flag, in case your server only needs access to the search_docs capability (useful for coding agents).
---
 packages/mcp-server/src/options.ts | 11 ++++++++++-
 packages/mcp-server/src/server.ts  | 16 ++++++++++------
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/packages/mcp-server/src/options.ts b/packages/mcp-server/src/options.ts
index 9e9d15c..069b881 100644
--- a/packages/mcp-server/src/options.ts
+++ b/packages/mcp-server/src/options.ts
@@ -14,6 +14,7 @@ export type CLIOptions = McpOptions & {
 };
 
 export type McpOptions = {
+  includeCodeTool?: boolean | undefined;
   includeDocsTools?: boolean | undefined;
   stainlessApiKey?: string | undefined;
   codeAllowHttpGets?: boolean | undefined;
@@ -92,11 +93,13 @@ export function parseCLIOptions(): CLIOptions {
     : argv.tools?.includes(toolType) ? true
     : undefined;
 
+  const includeCodeTool = shouldIncludeToolType('code');
   const includeDocsTools = shouldIncludeToolType('docs');
 
   const transport = argv.transport as 'stdio' | 'http';
 
   return {
+    ...(includeCodeTool !== undefined && { includeCodeTool }),
     ...(includeDocsTools !== undefined && { includeDocsTools }),
     debug: !!argv.debug,
     stainlessApiKey: argv.stainlessApiKey,
@@ -129,13 +132,19 @@ export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): M
   const queryObject = typeof query === 'string' ? qs.parse(query) : query;
   const queryOptions = QueryOptions.parse(queryObject);
 
+  let codeTool: boolean | undefined =
+    queryOptions.no_tools && queryOptions.no_tools?.includes('code') ? false
+    : queryOptions.tools?.includes('code') ? true
+    : defaultOptions.includeCodeTool;
+
   let docsTools: boolean | undefined =
     queryOptions.no_tools && queryOptions.no_tools?.includes('docs') ? false
     : queryOptions.tools?.includes('docs') ? true
     : defaultOptions.includeDocsTools;
 
   return {
-    codeExecutionMode: defaultOptions.codeExecutionMode,
+    ...(codeTool !== undefined && { includeCodeTool: codeTool }),
     ...(docsTools !== undefined && { includeDocsTools: docsTools }),
+    codeExecutionMode: defaultOptions.codeExecutionMode,
   };
 }
diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts
index 4f95d54..d20c854 100644
--- a/packages/mcp-server/src/server.ts
+++ b/packages/mcp-server/src/server.ts
@@ -156,12 +156,16 @@ export async function initMcpServer(params: {
  * Selects the tools to include in the MCP Server based on the provided options.
  */
 export function selectTools(options?: McpOptions): McpTool[] {
-  const includedTools = [
-    codeTool({
-      blockedMethods: blockedMethodsForCodeTool(options),
-      codeExecutionMode: options?.codeExecutionMode ?? 'stainless-sandbox',
-    }),
-  ];
+  const includedTools = [];
+
+  if (options?.includeCodeTool ?? true) {
+    includedTools.push(
+      codeTool({
+        blockedMethods: blockedMethodsForCodeTool(options),
+        codeExecutionMode: options?.codeExecutionMode ?? 'stainless-sandbox',
+      }),
+    );
+  }
   if (options?.includeDocsTools ?? true) {
     includedTools.push(docsSearchTool);
   }

From 72370231d0ab2292292857a4021e7ca101465e9e Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Fri, 27 Feb 2026 14:37:50 +0000
Subject: [PATCH 7/7] release: 0.1.0-alpha.28

---
 .release-please-manifest.json     |  2 +-
 CHANGELOG.md                      | 17 +++++++++++++++++
 package.json                      |  2 +-
 packages/mcp-server/manifest.json |  2 +-
 packages/mcp-server/package.json  |  2 +-
 packages/mcp-server/src/server.ts |  2 +-
 src/version.ts                    |  2 +-
 7 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index a0c24c3..5a12c39 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.27"
+  ".": "0.1.0-alpha.28"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc8fbd1..3252293 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.0-alpha.28 (2026-02-27)
+
+Full Changelog: [v0.1.0-alpha.27...v0.1.0-alpha.28](https://github.com/Scan-Documents/node-sdk/compare/v0.1.0-alpha.27...v0.1.0-alpha.28)
+
+### Features
+
+* **mcp:** add an option to disable code tool ([da647e2](https://github.com/Scan-Documents/node-sdk/commit/da647e2d55b35d55460133d6787eef4f28d896ef))
+
+
+### Chores
+
+* **internal:** fix MCP Dockerfiles so they can be built without buildkit ([e1a34c1](https://github.com/Scan-Documents/node-sdk/commit/e1a34c1c73ba4bf2cd8aed8e96e857c194fedc9a))
+* **internal:** fix MCP Dockerfiles so they can be built without buildkit ([4b55b1f](https://github.com/Scan-Documents/node-sdk/commit/4b55b1fae74f0ea3106258ccf85863a9172582c2))
+* **internal:** make MCP code execution location configurable via a flag ([1133800](https://github.com/Scan-Documents/node-sdk/commit/1133800e1e21c15a3beb23b14dc3e917b6248146))
+* **internal:** move stringifyQuery implementation to internal function ([3c528b4](https://github.com/Scan-Documents/node-sdk/commit/3c528b41d05fc52d1259d88192f6a9db5ed9717c))
+* **internal:** upgrade @modelcontextprotocol/sdk and hono ([cfd3f73](https://github.com/Scan-Documents/node-sdk/commit/cfd3f730692dcebcab5597407ef7927e057c39da))
+
 ## 0.1.0-alpha.27 (2026-02-24)
 
 Full Changelog: [v0.1.0-alpha.26...v0.1.0-alpha.27](https://github.com/Scan-Documents/node-sdk/compare/v0.1.0-alpha.26...v0.1.0-alpha.27)
diff --git a/package.json b/package.json
index 6d65295..85cc81e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "scan-documents",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.28",
   "description": "The official TypeScript library for the Scan Documents API",
   "author": "Scan Documents <support@scan-documents.com>",
   "types": "dist/index.d.ts",
diff --git a/packages/mcp-server/manifest.json b/packages/mcp-server/manifest.json
index bed36d0..1de2570 100644
--- a/packages/mcp-server/manifest.json
+++ b/packages/mcp-server/manifest.json
@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.2",
   "name": "scan-documents-mcp",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.28",
   "description": "The official MCP Server for the Scan Documents API",
   "author": {
     "name": "Scan Documents",
diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
index bf8bb24..b4c6232 100644
--- a/packages/mcp-server/package.json
+++ b/packages/mcp-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "scan-documents-mcp",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.28",
   "description": "The official MCP Server for the Scan Documents API",
   "author": "Scan Documents <support@scan-documents.com>",
   "types": "dist/index.d.ts",
diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts
index d20c854..890f3da 100644
--- a/packages/mcp-server/src/server.ts
+++ b/packages/mcp-server/src/server.ts
@@ -20,7 +20,7 @@ export const newMcpServer = async (stainlessApiKey: string | undefined) =>
   new McpServer(
     {
       name: 'scan_documents_api',
-      version: '0.1.0-alpha.27',
+      version: '0.1.0-alpha.28',
     },
     {
       instructions: await getInstructions(stainlessApiKey),
diff --git a/src/version.ts b/src/version.ts
index 3287b08..522a9fb 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1 +1 @@
-export const VERSION = '0.1.0-alpha.27'; // x-release-please-version
+export const VERSION = '0.1.0-alpha.28'; // x-release-please-version