Let EXECUTOR_MCP_DISCOVERY_TIMEOUT_MS override the MCP discovery timeout

Author: Oudwins

.changeset/mcp-discovery-timeout-env.md

@@ -0,0 +1,5 @@
+---
+"executor": patch
+---
+
+Set `EXECUTOR_MCP_DISCOVERY_TIMEOUT_MS` to change how long Executor waits for an MCP server to connect and list its tools (default 30000). Use it for servers that take longer than the default to start.

apps/docs/hosted/docker.mdx

@@ -70,6 +70,7 @@ the container defaults.
 | `EXECUTOR_ORG_SLUG`                 | `default`                       | URL slug for that org.                                                                          |
 | `EXECUTOR_ALLOW_LOCAL_NETWORK`      | `false`                         | Allow sandboxed code to reach loopback / private addresses. Keep off unless you trust the code. |
 | `EXECUTOR_DISABLE_AUTH_RATE_LIMIT`  | `false`                         | Turn off sign-in rate limiting. Only when a proxy or WAF in front of Executor limits instead.   |
+| `EXECUTOR_MCP_DISCOVERY_TIMEOUT_MS` | `30000`                         | How long to wait for an MCP server to connect and list its tools before marking it degraded.    |
 
 Tracing is configured separately, and off unless you turn it on — see
 [Tracing](/hosted/tracing).

packages/plugins/mcp/src/sdk/discover-timeout.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect } from "effect";
+
+import type { McpConnector } from "./connection";
+import { discoverTools, resolveDiscoverTimeoutMs } from "./discover";
+
+const ENV = "EXECUTOR_MCP_DISCOVERY_TIMEOUT_MS";
+
+// A server that never answers the handshake, so only the deadline ends discovery.
+const neverConnects: McpConnector = Effect.never;
+
+const withEnv = <A, E, R>(value: string | undefined, effect: Effect.Effect<A, E, R>) =>
+  Effect.acquireUseRelease(
+    Effect.sync(() => {
+      const previous = process.env[ENV];
+      if (value === undefined) delete process.env[ENV];
+      else process.env[ENV] = value;
+      return previous;
+    }),
+    () => effect,
+    (previous) =>
+      Effect.sync(() => {
+        if (previous === undefined) delete process.env[ENV];
+        else process.env[ENV] = previous;
+      }),
+  );
+
+describe("MCP discovery timeout", () => {
+  it.effect("defaults to 30 seconds", () =>
+    withEnv(
+      undefined,
+      Effect.sync(() => expect(resolveDiscoverTimeoutMs()).toBe(30_000)),
+    ),
+  );
+
+  it.effect("ignores a value that is not a positive integer", () =>
+    Effect.gen(function* () {
+      for (const value of ["", "abc", "0", "-5", "1.5"]) {
+        const resolved = yield* withEnv(value, Effect.sync(resolveDiscoverTimeoutMs));
+        expect(resolved).toBe(30_000);
+      }
+    }),
+  );
+
+  it.live("uses EXECUTOR_MCP_DISCOVERY_TIMEOUT_MS when discovery has no explicit timeout", () =>
+    withEnv(
+      "250",
+      Effect.gen(function* () {
+        const failure = yield* discoverTools(neverConnects).pipe(Effect.flip);
+        expect(failure.message).toBe("MCP discovery timed out after 250ms");
+        expect(failure.timedOut).toBe(true);
+      }),
+    ),
+  );
+
+  it.live("an explicit timeout wins over the environment", () =>
+    withEnv(
+      "60000",
+      Effect.gen(function* () {
+        const failure = yield* discoverTools(neverConnects, 100).pipe(Effect.flip);
+        expect(failure.message).toBe("MCP discovery timed out after 100ms");
+      }),
+    ),
+  );
+});

packages/plugins/mcp/src/sdk/discover.ts

@@ -32,6 +32,23 @@ const MAX_LIST_TOOLS_PAGES = 100;
 // catalog on first connect.
 const DEFAULT_DISCOVER_TIMEOUT = Duration.seconds(30);
 
+// Operators with servers that legitimately take longer (or that want a probe
+// to give up sooner) override the default without a rebuild.
+const DISCOVER_TIMEOUT_ENV = "EXECUTOR_MCP_DISCOVERY_TIMEOUT_MS";
+
+/** The discovery deadline in milliseconds: `EXECUTOR_MCP_DISCOVERY_TIMEOUT_MS`
+ *  when it is a positive integer, otherwise `DEFAULT_DISCOVER_TIMEOUT`. Read on
+ *  every call so a changed environment applies without a restart, and guarded
+ *  for runtimes without `process` (Workers). */
+export const resolveDiscoverTimeoutMs = (): number => {
+  const raw =
+    typeof process === "undefined" ? undefined : process.env?.[DISCOVER_TIMEOUT_ENV]?.trim();
+  const parsed = raw ? Number(raw) : Number.NaN;
+  return Number.isInteger(parsed) && parsed > 0
+    ? parsed
+    : Duration.toMillis(DEFAULT_DISCOVER_TIMEOUT);
+};
+
 // Teardown is best-effort and paid for by the request that performed discovery.
 // A remote transport may accept close and then never settle, so use the same
 // bound as the invocation connection pool instead of stranding the caller in an
@@ -165,7 +182,7 @@ export const discoverToolsFromInput = (
  * Connect to an MCP server and discover all available tools.
  * Returns the parsed manifest containing server metadata and tool entries.
  *
- * Bounded by `timeoutMs` (default `DEFAULT_DISCOVER_TIMEOUT`): every caller
+ * Bounded by `timeoutMs` (default `resolveDiscoverTimeoutMs()`): every caller
  * is dialing a server we don't control, and neither the connect handshake
  * nor `listTools` has a deadline of its own, so an unresponsive endpoint
  * (dead loopback port, wedged mid-handshake) would otherwise hang the
@@ -183,7 +200,7 @@ export const discoverToolsFromInput = (
  */
 export const discoverTools = (
   connector: McpConnector,
-  timeoutMs: number = Duration.toMillis(DEFAULT_DISCOVER_TIMEOUT),
+  timeoutMs: number = resolveDiscoverTimeoutMs(),
 ): Effect.Effect<McpToolManifest, McpToolDiscoveryError> =>
   Effect.uninterruptibleMask((restore) =>
     Effect.gen(function* () {