The best way to control Claude Code, Codex and more from any computer or phone
fix(server): Codex MCP servers that fail to start show a notice in the thread (#34771)
Julius Marminge committed
Nov 11, 2026 at 22:17 UTC
5c6f2f1229514881a18af286b8a63e15ab4bef70
2 files changed
+157
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts
+95
@@ -2334,6 +2334,101 @@ describe("CodexAdapterV2 post-settle continuation", () => {
2334
),
2335
);
2336
2337
+ it.effect.each(["before", "during"] as const)(
2338
+ "surfaces a user MCP server that fails to start %s the turn",
2339
+ (timing) =>
2340
+ Effect.scoped(
2341
+ Effect.gen(function* () {
2342
+ const nativeThreadId = "mcp-startup-failed-thread";
2343
+ const nativeTurnId = "mcp-startup-failed-turn";
2344
+ const startupError =
2345
+ "MCP client for `example_mcp` failed to start: MCP startup failed: handshaking with MCP server failed";
2346
+ const startup: Array<CodexReplay.CodexAppServerReplayEntry> = [
2347
+ {
2348
+ type: "emit_inbound",
2349
+ label: "mcp-starting",
2350
+ frame: {
2351
+ method: "mcpServer/startupStatus/updated",
2352
+ params: {
2353
+ threadId: nativeThreadId,
2354
+ name: "example_mcp",
2355
+ status: "starting",
2356
+ error: null,
2357
+ failureReason: null,
2358
+ },
2359
+ },
2360
+ },
2361
+ {
2362
+ type: "emit_inbound",
2363
+ label: "mcp-failed",
2364
+ frame: {
2365
+ method: "mcpServer/startupStatus/updated",
2366
+ params: {
2367
+ threadId: nativeThreadId,
2368
+ name: "example_mcp",
2369
+ status: "failed",
2370
+ error: startupError,
2371
+ failureReason: null,
2372
+ },
2373
+ },
2374
+ },
2375
+ ];
2376
+ const preamble = codexReplayPreamble({
2377
+ nativeThreadId,
2378
+ nativeTurnId,
2379
+ prompt: "use example_mcp",
2380
+ });
2381
+ const turnStart = preamble.findIndex(
2382
+ (entry) => entry.type === "expect_outbound" && entry.label === "turn/start",
2383
+ );
2384
+ const transcript = makeCodexReplayTranscript({
2385
+ scenario: "codex-mcp-startup-failed",
2386
+ entries: [
2387
+ ...(timing === "before"
2388
+ ? [...preamble.slice(0, turnStart), ...startup, ...preamble.slice(turnStart)]
2389
+ : [...preamble, ...startup]),
2390
+ {
2391
+ type: "emit_inbound",
2392
+ label: "complete",
2393
+ frame: {
2394
+ method: "turn/completed",
2395
+ params: {
2396
+ threadId: nativeThreadId,
2397
+ turn: makeCodexReplayTurn({ id: nativeTurnId, status: "completed" }),
2398
+ },
2399
+ },
2400
+ },
2401
+ ],
2402
+ });
2403
+ const harness = yield* makeCodexReplayHarness(transcript);
2404
+ yield* harness.runtime.startTurn(
2405
+ makeCodexTestTurnInput({
2406
+ threadId: harness.threadId,
2407
+ providerThread: harness.providerThread,
2408
+ now: yield* DateTime.now,
2409
+ attemptId: RunAttemptId.make("mcp-startup-failed-attempt"),
2410
+ text: "use example_mcp",
2411
+ }),
2412
+ );
2413
+ yield* harness.firstTerminal;
2414
+ const surfaced = harness.events.filter((event) => {
2415
+ const serialized = JSON.stringify(event);
2416
+ return serialized.includes("example_mcp") && serialized.includes("failed to start");
2417
+ });
2418
+ assert.isNotEmpty(surfaced);
2419
+ }).pipe(
2420
+ Effect.provide(
2421
+ Layer.mergeAll(
2422
+ IdAllocator.layer,
2423
+ McpProviderSessions.layer,
2424
+ NodeServices.layer,
2425
+ NodeCrypto.layer,
2426
+ ),
2427
+ ),
2428
+ ),
2429
+ ),
2430
+ );
2431
+
2432
it.effect("stops asking for commands the user allowed for the session", () =>
2433
Effect.scoped(
2434
Effect.gen(function* () {
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
+62
@@ -1907,6 +1907,8 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
1907
new Map<ProviderThreadId, Extract<OrchestrationV2TurnItem, { type: "error" }>>(),
1908
);
1909
const activeTurns = yield* Ref.make(new Map<string, ActiveCodexTurnContext>());
1910
+ // Codex reports MCP startup on thread start, usually before the turn context exists.
1911
+ const mcpStartupFailures = new Map<string, Map<string, string>>();
1912
const turnTokenUsageByThread = new Map<string, CodexTurnTokenUsageState>();
1913
const usageStateForThread = (nativeThreadId: string) => {
1914
let state = turnTokenUsageByThread.get(nativeThreadId);
@@ -2158,6 +2160,45 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
2160
yield* emitGoalUpdate(nativeThreadId);
2161
});
2162
2163
+ const emitMcpStartupFailures = Effect.fn("CodexAdapterV2.emitMcpStartupFailures")(
2164
+ function* (context: ActiveCodexTurnContext) {
2165
+ const nativeThreadId = context.providerThread.nativeThreadRef?.nativeId;
2166
+ if (nativeThreadId == null) return;
2167
+ const failures = mcpStartupFailures.get(nativeThreadId);
2168
+ if (failures === undefined) return;
2169
+ mcpStartupFailures.delete(nativeThreadId);
2170
+ for (const [name, message] of failures) {
2171
+ const nativeItemId = `mcp-startup-failed:${context.providerTurnId}:${name}`;
2172
+ const { ordinal, startedAt } = yield* resolveItemPosition(context, nativeItemId);
2173
+ yield* emitProviderEvent({
2174
+ type: "turn_item.updated",
2175
+ driver: CODEX_PROVIDER,
2176
+ turnItem: {
2177
+ id: idAllocator.derive.turnItemFromProviderItem({
2178
+ driver: CODEX_PROVIDER,
2179
+ nativeItemId,
2180
+ }),
2181
+ threadId: context.projectionThreadId,
2182
+ runId: context.projectionRunId,
2183
+ nodeId: context.providerNodeId,
2184
+ providerThreadId: context.providerThread.id,
2185
+ providerTurnId: context.providerTurnId,
2186
+ nativeItemRef: { ...codexNativeItemRef(nativeItemId), strength: "weak" },
2187
+ parentItemId: null,
2188
+ ordinal,
2189
+ type: "system_notice",
2190
+ status: "completed",
2191
+ title: `MCP server ${name} failed to start`,
2192
+ message,
2193
+ startedAt,
2194
+ completedAt: startedAt,
2195
+ updatedAt: startedAt,
2196
+ },
2197
+ });
2198
+ }
2199
+ },
2200
+ );
2201
+
2202
const releaseGoalUpdates = (nativeThreadId: string) =>
2203
Effect.suspend(() => {
2204
goalUpdatesHeld.delete(nativeThreadId);
@@ -2278,6 +2319,7 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
2319
},
2320
});
2321
yield* rememberRootProviderThread(input.turnInput.providerThread);
2322
+ yield* emitMcpStartupFailures(context);
2323
return context;
2324
});
2325
@@ -4752,6 +4794,26 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
4794
}).pipe(Effect.andThen(updateSubagentSelection(payload.threadId, payload.toModel))),
4795
);
4796
4797
+ yield* client.handleServerNotification("mcpServer/startupStatus/updated", (payload) =>
4798
+ Effect.gen(function* () {
4799
+ if (payload.threadId == null) return;
4800
+ const failures = mcpStartupFailures.get(payload.threadId) ?? new Map<string, string>();
4801
+ if (payload.status === "failed") {
4802
+ failures.set(
4803
+ payload.name,
4804
+ payload.error?.trim() || `MCP server ${payload.name} failed to start.`,
4805
+ );
4806
+ mcpStartupFailures.set(payload.threadId, failures);
4807
+ } else {
4808
+ failures.delete(payload.name);
4809
+ if (failures.size === 0) mcpStartupFailures.delete(payload.threadId);
4810
+ return;
4811
+ }
4812
+ const context = yield* findActiveTurnByNativeThreadId(payload.threadId);
4813
+ if (context !== undefined) yield* emitMcpStartupFailures(context);
4814
+ }),
4815
+ );
4816
+
4817
yield* client.handleServerNotification("hook/completed", (payload) =>
4818
Effect.gen(function* () {
4819
if (payload.turnId == null || payload.run.status !== "stopped") return;