Skip to content

Commit fbb15ad

Browse files
bgeisbergerclaude
andauthored
feat: report the MCP servers that the Codex config replaces (#587)
## Summary When the Codex config already defines the name of a requested MCP server, the adapter skips that server and Codex runs its own entry. The client was not told, and the startup wait still counted the skipped name: - A disabled Codex entry never reports a startup, so `session/new` waited for the whole `mcpStartupAwaitTimeoutMs`, and the startup report of the session was lost. - An enabled Codex entry reported its startup under the requested name. Changes: - **fix:** the startup wait leaves the skipped servers out. - **feat:** the startup report shows each skipped server as a failed `mcp__<server>__startup` tool call, like the other startup reports. ## Open question The report is on for every client. If you prefer, it could be opt-in through `clientCapabilities._meta.mcp_startup_skipped`, like `terminal_output`. The fix would stay unconditional. ## Tests - `mcp-config-merge.test.ts` (real Codex): a server that a disabled config entry replaces, plus a broken one. Before the fix, the test times out. - `CodexAcpClient.test.ts`, and the tool call contract snapshots. - `npm run typecheck`, `npm run build`, `npm test` pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent ca1d971 commit fbb15ad

12 files changed

Lines changed: 218 additions & 29 deletions

‎docs/mcp-startup-await-timeout.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ as soon as the session is created. With the field, the wait ends when the startu
4343
whichever comes first. The adapter never cancels the startup.
4444
It keeps tracking every requested server in the background.
4545

46+
A requested server whose name the Codex config already defines is not passed to Codex: Codex runs its own entry
47+
instead. The wait leaves such a server out, because its startup events, if any, belong to the entry of Codex. A disabled
48+
entry sends none. The adapter reports such a server with the other startup reports, in the same shape, with a text that
49+
says the server was not started.
50+
4651
When the requested servers reach a terminal state, the adapter reports each of them that failed or was cancelled.
4752
Each report is a `session/update` with a new `tool_call` in the `failed` status and the title `mcp__<server>__startup`.
4853
A server that starts successfully gets no report. When a server fails because it needs authentication and the client

‎src/CodexAcpClient.ts‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -635,9 +635,10 @@ export class CodexAcpClient {
635635
const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
636636
await this.refreshSkills(request.cwd, additionalDirectories);
637637

638+
const sessionConfig = await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers ?? []);
638639
const response = await this.resumeThread({
639640
excludeTurns: true,
640-
config: await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers ?? []),
641+
config: sessionConfig.config,
641642
cwd: request.cwd,
642643
modelProvider: await this.getResumeModelProvider(),
643644
threadId: request.sessionId,
@@ -654,6 +655,7 @@ export class CodexAcpClient {
654655
modelProvider: response.modelProvider,
655656
currentServiceTier: response.serviceTier as ServiceTier ?? null,
656657
additionalDirectories,
658+
skippedMcpServers: sessionConfig.skippedMcpServers,
657659
}
658660
}
659661

@@ -676,9 +678,10 @@ export class CodexAcpClient {
676678
const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
677679
await this.refreshSkills(request.cwd, additionalDirectories);
678680

681+
const sessionConfig = await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers ?? []);
679682
const response = await this.resumeThread({
680683
excludeTurns: true,
681-
config: await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers ?? []),
684+
config: sessionConfig.config,
682685
cwd: request.cwd,
683686
modelProvider: await this.getResumeModelProvider(),
684687
threadId: request.sessionId,
@@ -711,6 +714,7 @@ export class CodexAcpClient {
711714
thread,
712715
history,
713716
additionalDirectories,
717+
skippedMcpServers: sessionConfig.skippedMcpServers,
714718
};
715719
}
716720

@@ -744,8 +748,9 @@ export class CodexAcpClient {
744748
const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
745749
await this.refreshSkills(request.cwd, additionalDirectories);
746750

751+
const sessionConfig = await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers);
747752
const response = await this.codexClient.threadStart({
748-
config: await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers),
753+
config: sessionConfig.config,
749754
modelProvider: this.getModelProvider(),
750755
cwd: request.cwd,
751756
});
@@ -763,6 +768,7 @@ export class CodexAcpClient {
763768
modelProvider: response.modelProvider,
764769
currentServiceTier: response.serviceTier as ServiceTier ?? null,
765770
additionalDirectories,
771+
skippedMcpServers: sessionConfig.skippedMcpServers,
766772
};
767773
}
768774

@@ -888,7 +894,7 @@ export class CodexAcpClient {
888894
projectPath: string,
889895
additionalDirectories: string[],
890896
mcpServers: Array<McpServer>
891-
): Promise<JsonObject> {
897+
): Promise<SessionConfig> {
892898
const sessionRoots = [projectPath, ...additionalDirectories];
893899
const activeProvider = this.gatewayConfig
894900
? {
@@ -911,7 +917,7 @@ export class CodexAcpClient {
911917
};
912918
const configWithWorkspaceRoots = mergeSandboxWorkspaceWriteRoots(mergedConfig, additionalDirectories);
913919
if (mcpServers.length === 0) {
914-
return configWithWorkspaceRoots;
920+
return {config: configWithWorkspaceRoots, skippedMcpServers: []};
915921
}
916922

917923
const requestedServers = mcpServers.map(mcp => ({
@@ -924,13 +930,25 @@ export class CodexAcpClient {
924930
const existingNames = await this.getConfigMcpServerNames(projectPath);
925931
serversToConfigure = requestedServers.filter(mcp => !existingNames.has(mcp.name));
926932
}
933+
const skippedMcpServers = requestedServers
934+
.filter(mcp => !serversToConfigure.includes(mcp))
935+
.map(mcp => mcp.name);
936+
if (skippedMcpServers.length > 0) {
937+
logger.log("Skipping requested MCP servers that the Codex config already defines", {
938+
projectPath,
939+
skippedMcpServers,
940+
});
941+
}
927942
if (serversToConfigure.length === 0) {
928-
return configWithWorkspaceRoots;
943+
return {config: configWithWorkspaceRoots, skippedMcpServers};
929944
}
930945

931946
return {
932-
...configWithWorkspaceRoots,
933-
"mcp_servers": Object.fromEntries(serversToConfigure.map(mcp => [mcp.name, this.createMcpSeverConfig(mcp.server)])),
947+
config: {
948+
...configWithWorkspaceRoots,
949+
"mcp_servers": Object.fromEntries(serversToConfigure.map(mcp => [mcp.name, this.createMcpSeverConfig(mcp.server)])),
950+
},
951+
skippedMcpServers,
934952
};
935953
}
936954

@@ -1289,6 +1307,11 @@ export class CodexAcpClient {
12891307

12901308
export type JsonObject = { [key in string]?: JsonValue }
12911309

1310+
export type SessionConfig = {
1311+
config: JsonObject,
1312+
skippedMcpServers: string[],
1313+
}
1314+
12921315
function buildPromptItems(prompt: acp.ContentBlock[]): UserInput[] {
12931316
return prompt.map((block): UserInput | null => {
12941317
switch (block.type) {

‎src/CodexAcpServer.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -835,6 +835,7 @@ export class CodexAcpServer {
835835
const startupWait = this.mcpSessionStartup.begin(sessionId, requestedMcpServers, mcpServerStartupVersion, {
836836
publish: canPublishSessionUpdates,
837837
awaitTimeoutMs: parseMcpStartupAwaitTimeoutMs(request._meta),
838+
skippedServers: sessionMetadata.skippedMcpServers,
838839
});
839840
if (startupWait !== null) {
840841
try {
@@ -2259,7 +2260,10 @@ export class CodexAcpServer {
22592260
subscribed = false;
22602261

22612262
if (requestedMcpServers.length > 0 && mcpServerStartupVersion !== null) {
2262-
this.mcpSessionStartup.begin(sessionId, requestedMcpServers, mcpServerStartupVersion, {publish: true});
2263+
this.mcpSessionStartup.begin(sessionId, requestedMcpServers, mcpServerStartupVersion, {
2264+
publish: true,
2265+
skippedServers: sessionMetadata.skippedMcpServers,
2266+
});
22632267
}
22642268

22652269
await this.publishAvailableCommands(sessionState, requestedSessionGeneration);

‎src/SessionFork.ts‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
import {createHash} from "node:crypto";
22
import type * as acp from "@agentclientprotocol/sdk";
33
import {RequestError} from "@agentclientprotocol/sdk";
4+
import type {SessionConfig} from "./CodexAcpClient";
45
import type {CodexAppServerClient} from "./CodexAppServerClient";
56
import type {ModeKind} from "./app-server/ModeKind";
67
import type {ServiceTier} from "./app-server/ServiceTier";
7-
import type {Model, ThreadForkParams} from "./app-server/v2";
8+
import type {Model} from "./app-server/v2";
89
import type {SessionMetadata} from "./SessionMetadata";
910

1011
export type SessionForkDependencies = {
@@ -14,7 +15,7 @@ export type SessionForkDependencies = {
1415
cwd: string,
1516
additionalDirectories: string[],
1617
mcpServers: acp.McpServer[],
17-
): Promise<NonNullable<ThreadForkParams["config"]>>;
18+
): Promise<SessionConfig>;
1819
getResumeModelProvider(): Promise<string>;
1920
fetchAvailableModels(): Promise<Model[]>;
2021
createCurrentModelId(models: Model[], model: string, reasoningEffort: string | null): string;
@@ -28,13 +29,14 @@ export async function forkSession(
2829
): Promise<SessionMetadata> {
2930
await dependencies.refreshSkills(request.cwd, additionalDirectories);
3031
const lastTurnId = await resolveForkTurnId(request, dependencies.codexClient);
32+
const sessionConfig = await dependencies.createSessionConfig(
33+
request.cwd,
34+
additionalDirectories,
35+
request.mcpServers ?? [],
36+
);
3137
const response = await dependencies.codexClient.threadFork({
3238
excludeTurns: true,
33-
config: await dependencies.createSessionConfig(
34-
request.cwd,
35-
additionalDirectories,
36-
request.mcpServers ?? [],
37-
),
39+
config: sessionConfig.config,
3840
cwd: request.cwd,
3941
...(lastTurnId !== undefined && {lastTurnId}),
4042
modelProvider: await dependencies.getResumeModelProvider(),
@@ -51,6 +53,7 @@ export async function forkSession(
5153
modelProvider: response.modelProvider,
5254
currentServiceTier: response.serviceTier as ServiceTier ?? null,
5355
additionalDirectories,
56+
skippedMcpServers: sessionConfig.skippedMcpServers,
5457
};
5558
}
5659

‎src/SessionMetadata.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ export type SessionMetadata = {
1010
modelProvider?: string | null,
1111
currentServiceTier?: ServiceTier | null,
1212
additionalDirectories: string[],
13+
skippedMcpServers?: string[],
1314
}
1415

1516
export type SessionMetadataWithThread = SessionMetadata & {

‎src/__tests__/CodexACPAgent/CodexAcpClient.test.ts‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1113,6 +1113,70 @@ describe('ACP server test', { timeout: 40_000 }, () => {
11131113
});
11141114
});
11151115

1116+
it('does not wait for the startup of MCP servers that the Codex config already defines', async () => {
1117+
const mockFixture = createCodexMockTestFixture();
1118+
const codexAcpAgent = mockFixture.getCodexAcpAgent();
1119+
const codexAcpClient = mockFixture.getCodexAcpClient();
1120+
1121+
vi.spyOn(codexAcpClient, "readAuthRequirement").mockResolvedValue({required: false, account: null});
1122+
vi.spyOn(codexAcpClient, "getAccount").mockResolvedValue({account: null, requiresOpenaiAuth: false});
1123+
vi.spyOn(codexAcpClient, "listSkills").mockResolvedValue({data: []});
1124+
vi.spyOn(codexAcpClient, "newSession").mockResolvedValue({
1125+
sessionId: "new-id",
1126+
currentModelId: "gpt-5[medium]",
1127+
models: [createTestModel({id: "gpt-5"})],
1128+
collaborationMode: "default",
1129+
currentServiceTier: null,
1130+
additionalDirectories: [],
1131+
skippedMcpServers: ["codex-mcp"],
1132+
});
1133+
const awaitMcpStartupSpy = vi.spyOn(codexAcpClient, "awaitMcpServerStartup")
1134+
.mockResolvedValue({ready: ["new-mcp"], failed: [], cancelled: []});
1135+
1136+
await codexAcpAgent.newSession({
1137+
cwd: "/workspace",
1138+
mcpServers: [
1139+
{name: "codex-mcp", command: "npx", args: ["codex"], env: []},
1140+
{name: "new-mcp", command: "npx", args: ["new"], env: []},
1141+
],
1142+
_meta: {mcpStartupAwaitTimeoutMs: 30_000},
1143+
});
1144+
1145+
expect(awaitMcpStartupSpy).toHaveBeenCalledWith(["new-mcp"], expect.any(Number), {threadId: "new-id", signal: expect.any(AbortSignal)});
1146+
});
1147+
1148+
it('reports the MCP servers that the Codex config already defines', async () => {
1149+
const mockFixture = createCodexMockTestFixture();
1150+
const codexAcpAgent = mockFixture.getCodexAcpAgent();
1151+
const codexAcpClient = mockFixture.getCodexAcpClient();
1152+
1153+
vi.spyOn(codexAcpClient, "readAuthRequirement").mockResolvedValue({required: false, account: null});
1154+
vi.spyOn(codexAcpClient, "getAccount").mockResolvedValue({account: null, requiresOpenaiAuth: false});
1155+
vi.spyOn(codexAcpClient, "listSkills").mockResolvedValue({data: []});
1156+
vi.spyOn(codexAcpClient, "newSession").mockResolvedValue({
1157+
sessionId: "new-id",
1158+
currentModelId: "gpt-5[medium]",
1159+
models: [createTestModel({id: "gpt-5"})],
1160+
collaborationMode: "default",
1161+
currentServiceTier: null,
1162+
additionalDirectories: [],
1163+
skippedMcpServers: ["codex-mcp"],
1164+
});
1165+
vi.spyOn(codexAcpClient, "awaitMcpServerStartup").mockResolvedValue({ready: [], failed: [], cancelled: []});
1166+
1167+
await codexAcpAgent.newSession({
1168+
cwd: "/workspace",
1169+
mcpServers: [{name: "codex-mcp", command: "npx", args: ["codex"], env: []}],
1170+
});
1171+
1172+
await vi.waitFor(() => {
1173+
const dump = mockFixture.getAcpConnectionDump([]);
1174+
expect(dump).toMatch(/"toolCallId": "mcp_startup\.codex-mcp\.[0-9a-f-]{36}"/);
1175+
expect(dump).toContain('"title": "mcp__codex-mcp__startup"');
1176+
expect(dump).toContain("MCP server `codex-mcp` was not started, because the Codex config already defines an MCP server with this name.");
1177+
});
1178+
});
1179+
11161180
it('skips waiting for MCP startup when _meta.mcpStartupAwaitTimeoutMs is <= 0', async () => {
11171181
const mockFixture = createCodexMockTestFixture();
11181182
const codexAcpAgent = mockFixture.getCodexAcpAgent();

‎src/__tests__/CodexACPAgent/mcp-config-merge.test.ts‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ describe('MCP config merge across configured MCP servers and ACP request', { tim
2020
const globalConfig = `
2121
[mcp_servers.shared-mcp]
2222
url = "https://example.com/mcp"
23+
24+
[mcp_servers.disabled-mcp]
25+
command = "./node_modules/.bin/mcp-hello-world"
26+
enabled = false
2327
`;
2428

2529
const projectConfig = `
@@ -97,6 +101,37 @@ url = "https://example.com/mcp"
97101
})).resolves.toBeDefined();
98102
});
99103

104+
it('should not wait for an ACP MCP that a disabled MCP of the same name in the config replaces', async () => {
105+
const codexAcpAgent = fixture.getCodexAcpAgent();
106+
await codexAcpAgent.initialize({protocolVersion: 1});
107+
fixture.getCodexAcpClient().readAuthRequirement = vi.fn().mockResolvedValue({required: false, account: null});
108+
109+
const replacedMcp: McpServerStdio = {
110+
name: "disabled-mcp",
111+
command: "./node_modules/.bin/mcp-hello-world",
112+
args: ["example"],
113+
env: [],
114+
};
115+
const brokenMcp: McpServerStdio = {
116+
name: "broken-mcp",
117+
command: "./node_modules/.bin/missing-mcp-server",
118+
args: [],
119+
env: [],
120+
};
121+
122+
await codexAcpAgent.newSession({
123+
cwd: "",
124+
mcpServers: [replacedMcp, brokenMcp],
125+
_meta: {mcpStartupAwaitTimeoutMs: 60_000},
126+
});
127+
128+
await vi.waitFor(() => {
129+
const dump = fixture.getAcpConnectionDump([]);
130+
expect(dump).toContain("MCP server `broken-mcp` failed to start");
131+
expect(dump).toContain("MCP server `disabled-mcp` was not started, because the Codex config already defines an MCP server with this name.");
132+
});
133+
});
134+
100135
it('should not filter the conflicting ACP MCP when config filtering is disabled', async () => {
101136
vi.stubEnv("DISABLE_MCP_CONFIG_FILTERING", "true");
102137
const codexAcpAgent = fixture.getCodexAcpAgent();

‎src/__tests__/tool-calls/data/tool-calls-air.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -349,5 +349,23 @@
349349
}
350350
]
351351
}
352+
],
353+
"mcpSkipped": [
354+
{
355+
"sessionUpdate": "tool_call",
356+
"toolCallId": "mcp_startup.docs",
357+
"kind": "other",
358+
"title": "mcp__docs__startup",
359+
"status": "failed",
360+
"content": [
361+
{
362+
"type": "content",
363+
"content": {
364+
"type": "text",
365+
"text": "[codex-acp] MCP server `docs` was not started, because the Codex config already defines an MCP server with this name. Codex uses its own entry, or no server if that entry is disabled."
366+
}
367+
}
368+
]
369+
}
352370
]
353371
}

‎src/__tests__/tool-calls/data/tool-calls-zed.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -360,5 +360,23 @@
360360
}
361361
]
362362
}
363+
],
364+
"mcpSkipped": [
365+
{
366+
"sessionUpdate": "tool_call",
367+
"toolCallId": "mcp_startup.docs",
368+
"kind": "other",
369+
"title": "mcp__docs__startup",
370+
"status": "failed",
371+
"content": [
372+
{
373+
"type": "content",
374+
"content": {
375+
"type": "text",
376+
"text": "[codex-acp] MCP server `docs` was not started, because the Codex config already defines an MCP server with this name. Codex uses its own entry, or no server if that entry is disabled."
377+
}
378+
}
379+
]
380+
}
363381
]
364382
}

‎src/__tests__/tool-calls/tool-call-contract.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,8 @@ function reportsOfEachKind(): Record<string, ToolFacts[]> {
8787
elicitation: [ElicitationReporter.answered("ask", "accept")],
8888
mcpStartup: McpStartupReporter.failures({ready: [], failed: [{server: "db", error: "boom", failureReason: null}], cancelled: []} as never)
8989
.map(facts => ({...facts, toolCallId: "mcp_startup.db"})),
90+
mcpSkipped: McpStartupReporter.skipped(["docs"])
91+
.map(facts => ({...facts, toolCallId: "mcp_startup.docs"})),
9092
};
9193
}
9294

0 commit comments

Comments
 (0)