feat(local-mcp): relay importable servers for codex runs

Codex hard-fails a session on any unreachable MCP server, so importable
(public-URL) servers can't go into the sandbox config for GPT runs the way
they do for claude. partitionLocalMcpServersForRun routes them through the
relay instead when the run's adapter is codex: the loopback relay endpoint
always answers codex's reachability probe and the desktop executes the server
from local config, public URLs included. Desktop-only servers still relay for
every adapter. Relayed list is capped at 20 (matching the backend), keeping
desktop-only servers ahead of importables when the cap bites.

Author: richardsolomou

docs/cloud-mcp-import.md

@@ -114,13 +114,21 @@ echoed back from the run detail API), and excluded from logs/analytics.
 PostHog MCP and installation-derived servers. No other transformation — the
 payload shape is already `remoteMcpServerSchema`.
 
-**Adapter caveat**: codex-acp hard-fails on unreachable MCP servers, which is
-why the desktop prunes them for local Codex sessions
-(`filterReachableMcpServers` in
-`packages/workspace-server/src/services/agent/agent.ts`). The sandbox agent
-server does no such pruning. Either restrict `imported_mcp_servers` to
-`runtime_adapter == "claude"` initially, or add an equivalent reachability
-probe to the sandbox before session start for Codex runs.
+**Adapter caveat (resolved for Codex via the relay)**: codex-acp hard-fails a
+session when any configured MCP server is unreachable, and the sandbox agent
+server does no reachability pruning. So imported (direct-URL) servers only go
+into the sandbox config for the Claude adapter — the backend gates
+`get_imported_mcp_server_configs` on `runtime_adapter in {claude, unset}` as
+belt-and-braces. For Codex runs the client instead routes importable servers
+through the **relay** (`partitionLocalMcpServersForRun` in
+`packages/core/src/local-mcp/localMcpImport.ts` puts them in
+`relayed_mcp_servers` when the run's adapter is codex): the loopback relay
+endpoint always answers codex's reachability probe, and the desktop executes
+the server from local config — public-URL servers included. Desktop-only
+servers relay for every adapter. Net effect: a GPT user keeps all their local
+servers, at the cost of one desktop hop per call. `relayed_mcp_servers` is
+capped at 20 (matching the backend), and desktop-only servers are kept ahead
+of importables when the cap bites, since they have no other transport.
 
 ## Auth: header staleness and rotation
 

packages/core/src/local-mcp/localMcpImport.test.ts

@@ -3,8 +3,10 @@ import { describe, expect, it } from "vitest";
 import {
   classifyLocalMcpServer,
   isPrivateHostname,
+  type LocalMcpCloudClassification,
   LocalMcpImportService,
   type LocalMcpWorkspaceClient,
+  partitionLocalMcpServersForRun,
 } from "./localMcpImport";
 
 describe("isPrivateHostname", () => {
@@ -195,3 +197,54 @@ describe("LocalMcpImportService", () => {
     ]);
   });
 });
+
+describe("partitionLocalMcpServersForRun", () => {
+  const importable = (name: string): LocalMcpCloudClassification => ({
+    name,
+    availability: "importable",
+    reason: "public_url",
+    remote: {
+      type: "http",
+      name,
+      url: `https://${name}.example.com/mcp`,
+      headers: [],
+    },
+  });
+  const desktopOnly = (name: string): LocalMcpCloudClassification => ({
+    name,
+    availability: "requires_desktop",
+    reason: "stdio_transport",
+  });
+  const servers = [
+    importable("grafana"),
+    desktopOnly("slack"),
+    { name: "posthog", availability: "built_in", reason: "reserved_name" },
+    { name: "broken", availability: "unsupported", reason: "invalid_url" },
+  ] as LocalMcpCloudClassification[];
+
+  it.each([
+    ["claude", "claude"],
+    ["unset", undefined],
+  ] as const)("imports public servers for the %s adapter", (_name, adapter) => {
+    const result = partitionLocalMcpServersForRun(servers, adapter);
+    expect(result.imported.map((s) => s.name)).toEqual(["grafana"]);
+    expect(result.relayed).toEqual([{ name: "slack" }]);
+  });
+
+  it("relays importable servers instead of importing them for codex", () => {
+    const result = partitionLocalMcpServersForRun(servers, "codex");
+    expect(result.imported).toEqual([]);
+    expect(result.relayed).toEqual([{ name: "slack" }, { name: "grafana" }]);
+  });
+
+  it("keeps desktop-only servers when the codex relay list hits the cap", () => {
+    const many = [
+      ...Array.from({ length: 15 }, (_, i) => importable(`pub-${i}`)),
+      ...Array.from({ length: 10 }, (_, i) => desktopOnly(`desk-${i}`)),
+    ];
+    const result = partitionLocalMcpServersForRun(many, "codex");
+    expect(result.relayed).toHaveLength(20);
+    const names = result.relayed.map((s) => s.name);
+    for (let i = 0; i < 10; i++) expect(names).toContain(`desk-${i}`);
+  });
+});

packages/core/src/local-mcp/localMcpImport.ts

@@ -1,5 +1,7 @@
 import type {
+  Adapter,
   CloudMcpServerImport,
+  CloudMcpServerRelayDesignation,
   LocalMcpServerDescriptor,
 } from "@posthog/shared";
 import { isPrivateIpv4Octets, isPrivateIpv6Literal } from "@posthog/shared";
@@ -141,6 +143,53 @@ export function classifyLocalMcpServer(
   };
 }
 
+/** Mirrors the run-creation API's per-field caps (MAX_RELAYED_MCP_SERVERS). */
+const MAX_RELAYED_MCP_SERVERS = 20;
+
+export interface LocalMcpServersForRun {
+  imported: CloudMcpServerImport[];
+  relayed: CloudMcpServerRelayDesignation[];
+}
+
+/**
+ * Split classified local servers into the run-creation payload's imported and
+ * relayed lists for the run's adapter.
+ *
+ * Claude tolerates an unreachable configured server, so importable (public
+ * URL) servers go straight into the sandbox config. Codex hard-fails the whole
+ * session on any unreachable MCP server, so for codex runs importable servers
+ * ride the relay instead: the loopback relay endpoint always answers codex's
+ * reachability probe, and the desktop executes the server from local config —
+ * public URLs included. Desktop-only servers relay for every adapter.
+ */
+export function partitionLocalMcpServersForRun(
+  servers: LocalMcpCloudClassification[],
+  adapter: Adapter | undefined,
+): LocalMcpServersForRun {
+  const relayImportable = adapter === "codex";
+  const imported = relayImportable
+    ? []
+    : servers.flatMap((server) => (server.remote ? [server.remote] : []));
+  const relayed = servers
+    .filter(
+      (server) =>
+        server.availability === "requires_desktop" ||
+        (relayImportable && server.availability === "importable"),
+    )
+    // Desktop-only servers first: unlike importables they have no other
+    // transport, so they must survive the count cap.
+    .sort((a, b) =>
+      a.availability === b.availability
+        ? 0
+        : a.availability === "requires_desktop"
+          ? -1
+          : 1,
+    )
+    .slice(0, MAX_RELAYED_MCP_SERVERS)
+    .map((server) => ({ name: server.name }));
+  return { imported, relayed };
+}
+
 @injectable()
 export class LocalMcpImportService {
   constructor(

packages/ui/src/features/task-detail/hooks/useTaskCreation.ts

@@ -1,3 +1,4 @@
+import { partitionLocalMcpServersForRun } from "@posthog/core/local-mcp/localMcpImport";
 import {
   getErrorTitle,
   prepareTaskInput,
@@ -341,6 +342,10 @@ export function useTaskCreation({
             ? personalChannel?.id
             : undefined;
 
+        const localMcpServersForRun = partitionLocalMcpServersForRun(
+          localMcpServers,
+          adapter,
+        );
         const input = prepareTaskInput(serializedContent, filePaths, {
           // In channels chat-box mode no repo is attached up front, even if a
           // directory/repo is lingering in the persisted picker state.
@@ -368,12 +373,8 @@ export function useTaskCreation({
           autoPublishCloudRuns: settings.autoPublishCloudRuns,
           rtkEnabledCloud: settings.rtkEnabledCloud,
           allowNoRepo,
-          importedMcpServers: localMcpServers.flatMap((server) =>
-            server.remote ? [server.remote] : [],
-          ),
-          relayedMcpServers: localMcpServers
-            .filter((server) => server.availability === "requires_desktop")
-            .map((server) => ({ name: server.name })),
+          importedMcpServers: localMcpServersForRun.imported,
+          relayedMcpServers: localMcpServersForRun.relayed,
         });
 
         if (executionMode) {