From 09c49159e3bcd8ecb6512cae5dae494d2e310205 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Tue, 17 Nov 2026 22:22:32 +0100 Subject: [PATCH] feat: support MCP-over-ACP in the Codex adapter --- README.md | 2 +- docs/mcp-over-acp.md | 39 ++++ src/AcpAgentRouter.ts | 16 +- src/CodexAcpClient.ts | 57 ++++-- src/CodexAcpServer.ts | 3 +- src/CodexAppServerClient.ts | 14 ++ src/CodexConfigOverride.ts | 26 +++ src/CodexJsonRpcConnection.ts | 6 +- src/McpServerConfig.ts | 39 ++-- .../data/initialize-v1-routed-response.json | 2 +- .../data/initialize-v2-response.json | 3 +- .../mcp-config-unsupported-transports.json | 4 +- .../CodexACPAgent/initialize-v2.test.ts | 30 +++- .../CodexACPAgent/mcp-config-v2.test.ts | 84 ++++++--- .../CodexJsonRpcConnectionLogs.test.ts | 11 ++ .../integration/mcp-over-acp.test.ts | 170 ++++++++++++++++++ src/index.ts | 5 +- 17 files changed, 444 insertions(+), 67 deletions(-) create mode 100644 docs/mcp-over-acp.md create mode 100644 src/__tests__/integration/mcp-over-acp.test.ts diff --git a/README.md b/README.md index 7d03989f4..4394ce3f9 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Use [OpenAI Codex](https://github.com/openai/codex) from [Agent Client Protocol] - Typed warnings and errors through the opt-in [AIR session failure extension](docs/air-extensions.md#session-failure). - All AIR extensions, capabilities, and `_meta` keys: [AIR extensions](docs/air-extensions.md). - A per-turn [agent file-change report](docs/air-extensions.md#agent-file-change-report) after capability negotiation. -- Client-provided MCP servers over command-based stdio config and HTTP transport. +- Client-provided MCP servers over stdio, HTTP, or the existing ACP connection ([MCP-over-ACP](docs/mcp-over-acp.md)). - Slash commands: `/status`, `/mcp` (with `/mcp reconnect`), `/skills`, `/goal`, `/review`, `/review-branch`, `/review-commit`, `/compact`, and `/logout`, as well as configured skills. ## Installation diff --git a/docs/mcp-over-acp.md b/docs/mcp-over-acp.md new file mode 100644 index 000000000..3303c1a68 --- /dev/null +++ b/docs/mcp-over-acp.md @@ -0,0 +1,39 @@ +# MCP-over-ACP + +A client can serve MCP tools over its existing ACP connection. Check `agentCapabilities.mcpCapabilities.acp: true` +on ACP v1 or `capabilities.session.mcp.acp: {}` on v2. Register the server on that connection **before** +sending a session setup request: Codex can discover tools before the request returns. + +```json +{ + "cwd": "/workspace", + "mcpServers": [ + {"type": "acp", "name": "project-tools", "serverId": "project-tools:7a72"} + ] +} +``` + +`name` is the server name in Codex. `serverId` is the provider's opaque registration ID; sessions on the same +connection can share it. The same declaration works on new, resume, fork, and v1 load. The usual rules for +[name conflicts, startup failures, and `/mcp` status](mcp-startup-await-timeout.md) apply. + +Codex speaks HTTP to the ACP SDK's authenticated loopback bridge. The client does not need an HTTP listener. +Each operation arrives at the client as an `mcp/message` request with the `serverId`, a fresh logical `requestId`, +and the MCP method and parameters. Return `{ "result": ... }` or `{ "error": ... }` for the MCP outcome; +outer ACP errors indicate binding failures. Request-scoped `mcp/message` notifications go back to Codex. +The listener closes with the ACP connection, not with an individual session. + +Codex starts with `server/discover`. Include the [discovery result](https://modelcontextprotocol.io/specification/2026-07-28/server/discover) +cache fields: for example, `ttlMs: 0` and `cacheScope: "private"` for an uncached result. +The bridge uses the ACP SDK defaults: 64 concurrent HTTP requests per connection, 1 MiB per request body, +and 1 MiB of buffered stream output for a slow reader. + +Only `type: "acp"` servers must support MCP **2026-07-28**; the bridge does not accept legacy `initialize`. +You can use legacy stdio and HTTP servers alongside them. Codex's `mcp_2026_07_28` setting applies to +the whole thread, so Codex may try `server/discover` on ordinary HTTP servers too. A legacy server that +answers `Method not found` can then use `initialize`; an unresponsive discovery request may fail instead. +Threads without a bridged server keep their existing MCP setting. The adapter checks the running +Codex binary's feature list at initialization. If it cannot confirm `mcp_2026_07_28` support +(for example with an older `CODEX_PATH`), it does not advertise the ACP transport. + +See the [MCP-over-ACP draft](https://agentclientprotocol.com/rfds/mcp-over-acp.md) for the wire contract. diff --git a/src/AcpAgentRouter.ts b/src/AcpAgentRouter.ts index bd98e6567..49e0a8e66 100644 --- a/src/AcpAgentRouter.ts +++ b/src/AcpAgentRouter.ts @@ -1,8 +1,10 @@ import * as acp from "@agentclientprotocol/sdk/unstable"; import * as acpV2 from "@agentclientprotocol/sdk/experimental/v2/unstable"; +import {McpOverAcpHttpBridge} from "@agentclientprotocol/sdk/experimental/mcp-http"; import {z} from "zod"; import type {CodexAcpServer} from "./CodexAcpServer"; import {type AcpClientConnection, AcpV2Connection} from "./ACPSessionConnection"; +import type {McpOverAcpToHttp} from "./McpServerConfig"; import packageJson from "../package.json"; import {AcpResponseDelivery} from "./AcpResponseDelivery"; import {isAbsoluteProtocolPath} from "./PathUtils"; @@ -63,12 +65,14 @@ const hooksTrustParamsParser = z.object({ hooks: z.array(z.object({key: z.string().min(1), currentHash: z.string().min(1)})).min(1), }); +type CreateAgent = (connection: AcpClientConnection | AcpV2Connection, toHttp: McpOverAcpToHttp) => CodexAcpServer; + /** * Builds the ACP router. It picks the v1 or v2 handler chain from the first `initialize` * request, and only the selected chain's `onConnect` runs for the connection. */ export function createAcpAgentRouter( - createAgent: (connection: AcpClientConnection | AcpV2Connection) => CodexAcpServer, + createAgent: CreateAgent, ): Pick { return { connect(stream, options) { @@ -81,9 +85,11 @@ export function createAcpAgentRouter( } function createRouter( - createAgent: (connection: AcpClientConnection | AcpV2Connection) => CodexAcpServer, + createAgent: CreateAgent, responses: AcpResponseDelivery, ): acpV2.AgentProtocolRouter { + const mcp = new acp.McpOverAcpCaller(); + const bridge = new McpOverAcpHttpBridge(mcp); let codexAcpServer: CodexAcpServer | null = null; const getAgent = (params?: {sessionId?: unknown}): CodexAcpServer => { if (!codexAcpServer) { @@ -183,7 +189,8 @@ function createRouter( }; const v1Agent = acp.agent({name: packageJson.name}) - .onConnect((connection) => attachAgent(createAgent(connection.client), connection.signal)) + .onConnect(({client, signal}) => attachAgent(createAgent(client, server => bridge.toHttp(client, server)), signal)) + .onNotification(acp.methods.agent.mcp.message, mcp.handleNotification) .onRequest(acp.methods.agent.initialize, (ctx) => initialize(ctx.requestId, () => getAgent().initialize(ctx.params))) .onRequest(acp.methods.agent.session.new, (ctx) => createdSetup(ctx.requestId, () => getAgentForPaths(ctx.params).newSession(ctx.params))) .onRequest(acp.methods.agent.session.load, (ctx) => setup(ctx.params.sessionId, ctx.requestId, () => getAgentForPaths(ctx.params).loadSession(ctx.params), ctx.signal)) @@ -218,7 +225,8 @@ function createRouter( .onRequest(SESSION_LIST_UNSUBSCRIBE_METHOD, sessionListSubscriptionParamsParser, (ctx) => getAgent().sessionIndex.unsubscribeList(ctx.params)); const v2Agent = acpV2.agent({name: packageJson.name}) - .onConnect((connection) => attachAgent(createAgent(new AcpV2Connection(connection.client)), connection.signal)) + .onConnect(({client, signal}) => attachAgent(createAgent(new AcpV2Connection(client), server => bridge.toHttp(client, server)), signal)) + .onNotification(acpV2.methods.agent.mcp.message, mcp.handleNotification) .onRequest(acpV2.methods.agent.initialize, (ctx) => initialize(ctx.requestId, () => getAgent().initializeV2(ctx.params))) // No `session/load`: v2 folds it into `session/resume` with `replayFrom`. .onRequest(acpV2.methods.agent.session.new, (ctx) => createdSetup(ctx.requestId, () => getAgentForPaths(ctx.params).newSessionV2(ctx.params))) diff --git a/src/CodexAcpClient.ts b/src/CodexAcpClient.ts index b7271800b..5db20f248 100644 --- a/src/CodexAcpClient.ts +++ b/src/CodexAcpClient.ts @@ -32,7 +32,7 @@ import {isDeepStrictEqual} from "node:util"; import {logger} from "./Logger"; import {isAccountReadAuthFailureError, isAccountReadUnavailableError} from "./CodexThreadErrors"; import {listedSessionTitle, normalizeSessionTitle} from "./SessionTitle"; -import {type AcpMcpServer, type WithAcpMcpServers, normalizeMcpServers, toCodexMcpServerConfig} from "./McpServerConfig"; +import {type AcpMcpServer, type McpOverAcpToHttp, type WithAcpMcpServers, normalizeMcpServers, toCodexMcpServerConfig} from "./McpServerConfig"; import type { AccountUpdatedNotification, ApprovalsReviewer, @@ -92,7 +92,7 @@ import { narrowToListedModels, } from "./GatewayModelDiscovery"; import {findSupportedEffort} from "./ModelConfigOption"; -import {type ProviderStartupConfig, configOverride, NO_PROVIDER_STARTUP_CONFIG} from "./CodexConfigOverride"; +import {type ProviderStartupConfig, configOverride, expandConfigTables, NO_PROVIDER_STARTUP_CONFIG} from "./CodexConfigOverride"; import {disableUnsupportedSkills, withoutUnsupportedSkills} from "./UnsupportedSkills"; export type {SessionMetadata, SessionMetadataWithThread} from "./SessionMetadata"; /** A null turn marks unavailable outcome metadata, not a failed turn. */ @@ -123,6 +123,7 @@ type ResumedThread = { export const CUSTOM_GATEWAY_PROVIDER_ID = "custom-gateway"; export const OPENAI_PROVIDER_ID = "openai"; const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1"; +const STATELESS_MCP_FEATURE = "mcp_2026_07_28"; /** * The url-mode variant of the ACP `elicitation/create` request params. @@ -177,9 +178,14 @@ export class CodexAcpClient { private readonly subagents: CodexSubagentSubscriptions; private skillExtraRoots: string[] = []; private configPath: string | null = null; + private verifiedMcpBridge?: McpOverAcpToHttp; - - constructor(codexClient: CodexAppServerClient, codexConfig?: JsonObject, modelProvider?: string) { + constructor( + codexClient: CodexAppServerClient, + codexConfig?: JsonObject, + modelProvider?: string, + private readonly mcpOverAcpToHttp?: McpOverAcpToHttp, + ) { this.codexClient = codexClient; this.config = codexConfig ?? {}; this.modelProvider = modelProvider ?? null; @@ -192,12 +198,16 @@ export class CodexAcpClient { return this.codexClient; } + get supportsMcpOverAcp(): boolean { + return this.verifiedMcpBridge !== undefined; + } + /** * A client of the same configuration for another app-server: the same config and model provider. The routing * that the agent set at runtime (gateway auth, `providers/set`) is copied by {@link adoptRoutingFrom}. */ withAppServer(codexClient: CodexAppServerClient): CodexAcpClient { - const client = new CodexAcpClient(codexClient, this.config, this.modelProvider ?? undefined); + const client = new CodexAcpClient(codexClient, this.config, this.modelProvider ?? undefined, this.mcpOverAcpToHttp); client.adoptRoutingFrom(this); return client; } @@ -227,6 +237,18 @@ export class CodexAcpClient { } }); this.configPath = response?.codexHome ?? null; + // A CODEX_PATH binary may support HTTP but not stateless MCP. Don't offer a bridge it can't use. + if (this.mcpOverAcpToHttp) { + try { + if (await this.codexClient.hasExperimentalFeature(STATELESS_MCP_FEATURE)) { + this.verifiedMcpBridge = this.mcpOverAcpToHttp; + } + } catch (error) { + if (this.codexClient.connectionLoss.lost) throw error; + // Older app-servers need not implement the feature catalog to serve other transports. + logger.log("Could not verify MCP-over-ACP support", {error: String(error)}); + } + } this.isInitialized = true; } @@ -1155,8 +1177,9 @@ export class CodexAcpClient { apiType: activeProvider.apiType, baseUrl: activeProvider.baseUrl, }); + const overrides = mcpServers.length ? expandConfigTables(this.config, "mcp_servers", "features") : this.config; const mergedConfig = { - ...disableUnsupportedSkills(forceGitRootTurnDiffPaths(mergeGatewayConfig(this.config, this.gatewayConfig))), + ...disableUnsupportedSkills(forceGitRootTurnDiffPaths(mergeGatewayConfig(overrides, this.gatewayConfig))), projects: Object.fromEntries(sessionRoots.map(root => [root, { trust_level: "trusted", }])), @@ -1176,11 +1199,13 @@ export class CodexAcpClient { return {config: configWithWorkspaceRoots, skippedMcpServers: [], ...permissionProfileMetadata}; } - const requestedServers = normalizeMcpServers(mcpServers).map(server => ({name: server.name, server})); + // config/read sees Codex's layers, but not the per-thread overrides from CODEX_CONFIG. + const localServers = overrides["mcp_servers"]; + const requestedServers = normalizeMcpServers(mcpServers, this.verifiedMcpBridge); let serversToConfigure = requestedServers; if (shouldDeduplicateMcpConflicts()) { // Prevents Codex from deep-merging incompatible field types, such as url and stdio schemas. - const existingNames = this.getConfigMcpServerNames(effectiveConfig); + const existingNames = this.getConfigMcpServerNames(effectiveConfig, localServers); serversToConfigure = requestedServers.filter(mcp => !existingNames.has(mcp.name)); } const skippedMcpServers = requestedServers @@ -1196,26 +1221,30 @@ export class CodexAcpClient { return {config: configWithWorkspaceRoots, skippedMcpServers, ...permissionProfileMetadata}; } + const configs = await Promise.all(serversToConfigure.map(async server => + [server.name, await toCodexMcpServerConfig(server)] as const)); + const features = configWithWorkspaceRoots["features"]; return { config: { ...configWithWorkspaceRoots, - "mcp_servers": Object.fromEntries(serversToConfigure.map(mcp => [mcp.name, toCodexMcpServerConfig(mcp.server)])), + // Without modern discovery Codex sends `initialize`, which the ACP bridge does not accept. + ...(serversToConfigure.some(server => server.type === "acp") && { + features: {...(isJsonObject(features) ? features : {}), [STATELESS_MCP_FEATURE]: true}, + }), + mcp_servers: {...(isJsonObject(localServers) ? localServers : {}), ...Object.fromEntries(configs)}, }, skippedMcpServers, ...permissionProfileMetadata, }; } - private getConfigMcpServerNames(response: ConfigReadResponse): Set { + private getConfigMcpServerNames(response: ConfigReadResponse, localServers: JsonValue | undefined): Set { const effectiveMcpServers = response?.config?.["mcp_servers"]; const configLayers = response?.layers ?? []; const layerMcpServers = configLayers.map(layer => { return isJsonObject(layer.config) ? layer.config["mcp_servers"] : undefined; }); - const configuredMcpServers = [effectiveMcpServers, ...layerMcpServers].filter(isJsonObject); - if (configuredMcpServers.length === 0) { - return new Set(); - } + const configuredMcpServers = [localServers, effectiveMcpServers, ...layerMcpServers].filter(isJsonObject); return new Set(configuredMcpServers.flatMap(server => Object.keys(server))); } diff --git a/src/CodexAcpServer.ts b/src/CodexAcpServer.ts index a1c16dfd7..1d98a5c50 100644 --- a/src/CodexAcpServer.ts +++ b/src/CodexAcpServer.ts @@ -854,7 +854,7 @@ export class CodexAcpServer { }, sessionCapabilities, mcpCapabilities: { - acp: false, + acp: this.codexAcpClient.supportsMcpOverAcp, http: true, sse: false }, @@ -911,6 +911,7 @@ export class CodexAcpServer { mcp: { stdio: {}, http: {}, + ...(this.codexAcpClient.supportsMcpOverAcp && {acp: {}}), }, delete: {}, additionalDirectories: {}, diff --git a/src/CodexAppServerClient.ts b/src/CodexAppServerClient.ts index fa5b2f53c..8db679f23 100644 --- a/src/CodexAppServerClient.ts +++ b/src/CodexAppServerClient.ts @@ -18,6 +18,7 @@ import type { ConfigReadResponse, ConfigBatchWriteParams, ConfigWriteResponse, + ExperimentalFeatureListResponse, GetAccountParams, GetAccountRateLimitsResponse, GetAccountResponse, @@ -877,6 +878,19 @@ export class CodexAppServerClient { return await this.sendRequest({ method: "mcpServerStatus/list", params }); } + /** Whether this binary implements a feature, regardless of its default enablement. */ + async hasExperimentalFeature(name: string): Promise { + let cursor: string | null = null; + do { + const page: ExperimentalFeatureListResponse = await this.sendRequest({ + method: "experimentalFeature/list", params: {cursor, limit: 256}, + }); + if (page.data.some(feature => feature.name === name && feature.stage !== "removed")) return true; + cursor = page.nextCursor ?? null; + } while (cursor !== null); + return false; + } + async mcpServerReload(): Promise { return await this.sendRequest({ method: "config/mcpServer/reload", params: undefined }); } diff --git a/src/CodexConfigOverride.ts b/src/CodexConfigOverride.ts index 1a1173953..954a8f849 100644 --- a/src/CodexConfigOverride.ts +++ b/src/CodexConfigOverride.ts @@ -1,10 +1,36 @@ import type {JsonValue} from "./app-server/serde_json/JsonValue"; +import type {JsonObject} from "./CodexAcpClient"; /** A Codex `-c key=value` override, the value written as TOML. */ export function configOverride(key: string, value: JsonValue | undefined): string[] { return ["-c", `${key}=${toToml(value)}`]; } +/** + * Fold dotted overrides into the tables the adapter is about to edit. Codex applies thread overrides + * from an unordered map: sending both `mcp_servers` and `mcp_servers.x.url` could pair a URL with + * the wrong credentials. More specific keys win; do not mutate the config shared by other threads. + */ +export function expandConfigTables(config: JsonObject, ...tables: string[]): JsonObject { + const paths = Object.keys(config).filter(key => tables.some(table => key.startsWith(`${table}.`))).sort(); + if (paths.length === 0) return config; + const result = {...config}; + for (const path of paths) { + const parts = path.split("."); + const field = parts.pop()!; + let parent = result; + for (const part of parts) { + const existing = parent[part]; + // Server and header names are data, including names such as "__proto__". + parent = parent[part] = Object.assign(Object.create(null), + existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {}); + } + parent[field] = result[path]; + delete result[path]; + } + return result; +} + // JSON strings, numbers, booleans, and arrays are already valid TOML; only objects need `key = value` syntax. function toToml(value: JsonValue | undefined): string { if (Array.isArray(value)) return `[${value.map(toToml).join(", ")}]`; diff --git a/src/CodexJsonRpcConnection.ts b/src/CodexJsonRpcConnection.ts index 94fb23bb0..0ed4c4ff3 100644 --- a/src/CodexJsonRpcConnection.ts +++ b/src/CodexJsonRpcConnection.ts @@ -87,7 +87,11 @@ export function startCodexConnection( export function attachLogs(proc: ChildProcessWithoutNullStreams) { const originalWrite = proc.stdin.write.bind(proc.stdin); proc.stdin.write = (chunk: any, encoding?: any, callback?: any): boolean => { - if (logger.enabled) logger.log(`[IN] ${chunk.toString()}`); + if (logger.enabled) { + // The writer sends one complete JSON message. Keep MCP endpoint credentials out of its trace. + const line = chunk.toString().replace(/("Authorization"\s*:\s*")Bearer [^"]+"/gi, '$1Bearer [REDACTED]"'); + logger.log(`[IN] ${line}`); + } return originalWrite(chunk, encoding, callback); }; diff --git a/src/McpServerConfig.ts b/src/McpServerConfig.ts index bdf2e7d9c..0084185e3 100644 --- a/src/McpServerConfig.ts +++ b/src/McpServerConfig.ts @@ -1,6 +1,7 @@ import type * as acp from "@agentclientprotocol/sdk/unstable"; -import {RequestError} from "@agentclientprotocol/sdk/unstable"; +import {isMcpServerAcp, RequestError} from "@agentclientprotocol/sdk/unstable"; import type * as acpV2 from "@agentclientprotocol/sdk/experimental/v2/unstable"; +import type {McpServerHttpDeclaration} from "@agentclientprotocol/sdk/experimental/mcp-http"; import type {JsonObject} from "./CodexAcpClient"; import {sanitizeMcpServerName} from "./McpServerName"; @@ -9,22 +10,21 @@ import {sanitizeMcpServerName} from "./McpServerName"; */ export type AcpMcpServer = acp.McpServer | acpV2.McpServer; +/** Re-exports one registration as HTTP for Codex, on the ACP connection that declared it. */ +export type McpOverAcpToHttp = (server: acp.McpServerAcpDeclaration) => Promise; + /** * Version-independent MCP server config. Optional v2 fields are already defaulted. */ export type NormalizedMcpServer = + | {type: "acp"; name: string; toHttp(): Promise} + | McpServerHttpDeclaration | { type: "stdio"; name: string; command: string; args: string[]; env: Array<{name: string; value: string}>; - } - | { - type: "http"; - name: string; - url: string; - headers: Array<{name: string; value: string}>; }; /** @@ -35,21 +35,21 @@ export function getMcpServerName(server: AcpMcpServer): string { } /** Validate the whole request before filtering out servers configured independently of ACP. */ -export function normalizeMcpServers(servers: AcpMcpServer[]): NormalizedMcpServer[] { +export function normalizeMcpServers(servers: AcpMcpServer[], toHttp?: McpOverAcpToHttp): NormalizedMcpServer[] { const names = new Set(); return servers.map(server => { const name = sanitizeMcpServerName(getMcpServerName(server)); // Codex keys servers by the sanitized name, so collisions must not silently overwrite one. if (names.has(name)) throw RequestError.invalidParams({name: getMcpServerName(server)}, "MCP server names must be unique"); names.add(name); - return {...normalizeMcpServer(server), name}; + return {...normalizeMcpServer(server, toHttp), name}; }); } /** * Converts a v1 or v2 MCP server entry into one shape, rejecting transports Codex can't run. */ -export function normalizeMcpServer(server: AcpMcpServer): NormalizedMcpServer { +export function normalizeMcpServer(server: AcpMcpServer, toHttp?: McpOverAcpToHttp): NormalizedMcpServer { if (!("type" in server)) { // v1 stdio entries have no `type` tag. return {type: "stdio", name: server.name, command: server.command, args: server.args, env: server.env}; @@ -69,8 +69,14 @@ export function normalizeMcpServer(server: AcpMcpServer): NormalizedMcpServer { const http = server as acp.McpServerHttp | acpV2.McpServerHttp; return {type: "http", name: http.name, url: http.url, headers: http.headers ?? []}; } - case "acp": - throw RequestError.invalidParams(undefined, "Codex doesn't support MCP ACP transport protocol"); + case "acp": { + if (!isMcpServerAcp(server)) { + throw RequestError.invalidParams(undefined, "An ACP MCP server requires a string name and serverId"); + } + if (!toHttp) throw RequestError.invalidParams(undefined, "MCP-over-ACP is unavailable on this connection"); + // Validate now, but open a listener only if this server survives name filtering. + return {type: "acp", name: server.name, toHttp: () => toHttp(server)}; + } case "sse": throw RequestError.invalidParams(undefined, "Codex doesn't support MCP SSE transport protocol"); default: @@ -82,7 +88,14 @@ export function normalizeMcpServer(server: AcpMcpServer): NormalizedMcpServer { /** * Creates a Codex `mcp_servers` config entry. */ -export function toCodexMcpServerConfig(server: NormalizedMcpServer): JsonObject { +export async function toCodexMcpServerConfig(server: NormalizedMcpServer): Promise { + if (server.type === "acp") { + try { + server = await server.toHttp(); + } catch (error) { + throw RequestError.internalError({name: server.name}, `Could not open the MCP-over-ACP endpoint for ${server.name}: ${error}`); + } + } switch (server.type) { case "stdio": return { diff --git a/src/__tests__/CodexACPAgent/data/initialize-v1-routed-response.json b/src/__tests__/CodexACPAgent/data/initialize-v1-routed-response.json index afa99af42..26325dbee 100644 --- a/src/__tests__/CodexACPAgent/data/initialize-v1-routed-response.json +++ b/src/__tests__/CodexACPAgent/data/initialize-v1-routed-response.json @@ -26,7 +26,7 @@ "systemPrompt": {} }, "mcpCapabilities": { - "acp": false, + "acp": true, "http": true, "sse": false }, diff --git a/src/__tests__/CodexACPAgent/data/initialize-v2-response.json b/src/__tests__/CodexACPAgent/data/initialize-v2-response.json index 419e2b658..ce4bb34c2 100644 --- a/src/__tests__/CodexACPAgent/data/initialize-v2-response.json +++ b/src/__tests__/CodexACPAgent/data/initialize-v2-response.json @@ -13,7 +13,8 @@ }, "mcp": { "stdio": {}, - "http": {} + "http": {}, + "acp": {} }, "delete": {}, "additionalDirectories": {}, diff --git a/src/__tests__/CodexACPAgent/data/mcp-config-unsupported-transports.json b/src/__tests__/CodexACPAgent/data/mcp-config-unsupported-transports.json index a2ae9f4f6..678bc6562 100644 --- a/src/__tests__/CodexACPAgent/data/mcp-config-unsupported-transports.json +++ b/src/__tests__/CodexACPAgent/data/mcp-config-unsupported-transports.json @@ -11,8 +11,8 @@ "code": -32602, "message": "Invalid params: Codex doesn't support MCP SSE transport protocol" }, - "v1 acp": { + "obsolete acp id": { "code": -32602, - "message": "Invalid params: Codex doesn't support MCP ACP transport protocol" + "message": "Invalid params: An ACP MCP server requires a string name and serverId" } } \ No newline at end of file diff --git a/src/__tests__/CodexACPAgent/initialize-v2.test.ts b/src/__tests__/CodexACPAgent/initialize-v2.test.ts index 05d03aa8a..56621c328 100644 --- a/src/__tests__/CodexACPAgent/initialize-v2.test.ts +++ b/src/__tests__/CodexACPAgent/initialize-v2.test.ts @@ -31,12 +31,17 @@ const v2ClientCapabilities: acpV2.ClientCapabilities = { }, }; -function connectRouter() { +function connectRouter(hasModernMcp = true) { const mocks = createMockConnections(); + mocks.mockCodexConnection.sendRequest.mockImplementation(async (method: string, params: {cursor?: string}) => { + if (method !== "experimentalFeature/list") return {}; + if (!params.cursor) return {data: [], nextCursor: "next"}; + return {data: hasModernMcp ? [{name: "mcp_2026_07_28", enabled: false, stage: "underDevelopment"}] : [], nextCursor: null}; + }); let agent: CodexAcpServer; let codexClient: CodexAcpClient; - const router = createAcpAgentRouter((connection) => { - const codexAcpClient = new CodexAcpClient(new CodexAppServerClient(mocks.mockCodexConnection as any)); + const router = createAcpAgentRouter((connection, toHttp) => { + const codexAcpClient = new CodexAcpClient(new CodexAppServerClient(mocks.mockCodexConnection as any), undefined, undefined, toHttp); codexClient = codexAcpClient; vi.spyOn(codexAcpClient, "getAgentConfiguredModelProvider").mockResolvedValue("openai"); vi.spyOn(codexAcpClient, "getAccount").mockResolvedValue({account: null, requiresOpenaiAuth: true}); @@ -135,7 +140,24 @@ describe('CodexACPAgent - initialize over ACP v2', () => { await expect(initialize(v2ClientCapabilities)).resolves.toHaveProperty("protocolVersion", 2); }); - it('still routes a v1 initialize to the unchanged v1 chain', async () => { + it.each([1, 2] as const)('does not advertise ACP transport over v%i if Codex lacks modern MCP', async version => { + const {clientStream} = connectRouter(false); + if (version === 1) { + const connection = acp.client().connect(clientStream); + closeClient = () => connection.close(); + const response = await connection.agent.request(acp.methods.agent.initialize, {protocolVersion: 1}); + expect(response.agentCapabilities?.mcpCapabilities).toMatchObject({http: true, acp: false}); + } else { + const connection = acpV2.client().connect(clientStream); + closeClient = () => connection.close(); + const response = await connection.agent.request(acpV2.methods.agent.initialize, { + protocolVersion: 2, info: {name: "test", version: "1"}, + }); + expect(response.capabilities?.session?.mcp).toEqual({http: {}, stdio: {}}); + } + }); + + it('still routes a v1 initialize to the v1 chain', async () => { const {clientStream} = connectRouter(); const connection = acp.client({name: "test-client"}).connect(clientStream); closeClient = () => connection.close(); diff --git a/src/__tests__/CodexACPAgent/mcp-config-v2.test.ts b/src/__tests__/CodexACPAgent/mcp-config-v2.test.ts index 2902e76ed..fbb5777e7 100644 --- a/src/__tests__/CodexACPAgent/mcp-config-v2.test.ts +++ b/src/__tests__/CodexACPAgent/mcp-config-v2.test.ts @@ -1,17 +1,20 @@ import {describe, expect, it, vi} from 'vitest'; import type * as acp from '@agentclientprotocol/sdk/unstable'; import type * as acpV2 from '@agentclientprotocol/sdk/experimental/v2/unstable'; -import {createCodexMockTestFixture, createTestModel} from '../acp-test-utils'; -import type {AcpMcpServer} from '../../McpServerConfig'; - -/** - * Starts a session with the given MCP servers and returns the `mcp_servers` config - * sent to Codex `thread/start`. - */ -async function startSessionWithMcpServers(mcpServers: Array | undefined, configuredNames: string[] = []) { - const mockFixture = createCodexMockTestFixture(); - const codexAcpClient = mockFixture.getCodexAcpClient(); - const codexAppServerClient = mockFixture.getCodexAppServerClient(); +import {createTestModel} from '../acp-test-utils'; +import {createMockConnections} from './test-utils'; +import type {AcpMcpServer, McpOverAcpToHttp} from '../../McpServerConfig'; +import {CodexAcpClient, type JsonObject} from '../../CodexAcpClient'; +import {CodexAppServerClient} from '../../CodexAppServerClient'; + +/** Starts a session and returns the config sent to Codex `thread/start`. */ +async function startSessionWithMcpServers( + mcpServers: Array | undefined, configuredNames: string[] = [], toHttp?: McpOverAcpToHttp, overrides?: JsonObject, +) { + const codexAppServerClient = new CodexAppServerClient(createMockConnections().mockCodexConnection); + const codexAcpClient = new CodexAcpClient(codexAppServerClient, overrides, undefined, toHttp); + vi.spyOn(codexAppServerClient, "hasExperimentalFeature").mockResolvedValue(true); + await codexAcpClient.initialize({}); vi.spyOn(codexAppServerClient, "listSkills").mockResolvedValue({data: []}); vi.spyOn(codexAppServerClient, "configRead").mockResolvedValue({ @@ -32,8 +35,7 @@ async function startSessionWithMcpServers(mcpServers: Array | unde cwd: "/workspace", ...(mcpServers !== undefined && {mcpServers}), }); - const config = threadStartSpy.mock.calls[0]![0].config; - return config?.["mcp_servers"] ?? null; + return threadStartSpy.mock.calls[0]![0].config!; } describe('MCP server config from ACP v1 and v2 session requests', () => { @@ -56,7 +58,9 @@ describe('MCP server config from ACP v1 and v2 session requests', () => { {type: "http", name: "http-minimal", url: "https://example.com/minimal"}, ]; - await expect(JSON.stringify(await startSessionWithMcpServers(v2Servers), null, 2)) + const config = await startSessionWithMcpServers(v2Servers); + expect(config["features"]).not.toHaveProperty("mcp_2026_07_28"); + await expect(JSON.stringify(config["mcp_servers"], null, 2)) .toMatchFileSnapshot("data/mcp-config-v2-servers.json"); }); @@ -71,20 +75,53 @@ describe('MCP server config from ACP v1 and v2 session requests', () => { }, ]; - await expect(JSON.stringify(await startSessionWithMcpServers(v1Servers), null, 2)) + await expect(JSON.stringify((await startSessionWithMcpServers(v1Servers))["mcp_servers"], null, 2)) .toMatchFileSnapshot("data/mcp-config-v1-servers.json"); }); it('adds no MCP config when mcpServers is omitted', async () => { - expect(await startSessionWithMcpServers(undefined)).toBeNull(); + expect(await startSessionWithMcpServers(undefined)).not.toHaveProperty("mcp_servers"); + }); + + it('re-exports ACP registrations after name filtering and preserves their opaque server IDs', async () => { + const toHttp = vi.fn().mockResolvedValue({ + type: "http", name: "my_tools", url: "http://127.0.0.1:1234/tools", headers: [{name: "Authorization", value: "Bearer test-only"}], + }); + const tools = {type: "acp", name: "my tools", serverId: "client/opaque id"} as const; + const skipped = {...tools, name: "existing"}; + const local = {...tools, name: "local"}; + const overrides = { + mcp_servers: {other: {command: "other"}}, + "mcp_servers.local.url": "https://example.com/local", + "features.mcp_2026_07_28": false, features: {other: true}, + }; + const config = await startSessionWithMcpServers([tools, skipped, local], ["existing"], toHttp, overrides); + expect(toHttp.mock.calls).toEqual([[tools]]); + expect(config["mcp_servers"]).toEqual({ + other: {command: "other"}, local: {url: "https://example.com/local"}, + my_tools: {url: "http://127.0.0.1:1234/tools", http_headers: {Authorization: "Bearer test-only"}}, + }); + expect(Object.keys(config)).not.toContain("mcp_servers.local.url"); + expect(Object.keys(config)).not.toContain("features.mcp_2026_07_28"); + expect(config["features"]).toMatchObject({other: true, mcp_2026_07_28: true}); + + const filtered = await startSessionWithMcpServers([skipped, local], ["existing"], toHttp, overrides); + expect(filtered["features"]).toMatchObject({other: true, mcp_2026_07_28: false}); + expect(toHttp).toHaveBeenCalledTimes(1); + }); + + it('reports a bridge failure instead of starting the session without its tools', async () => { + const toHttp = vi.fn().mockRejectedValue(new Error("listen failed")); + await expect(startSessionWithMcpServers([{type: "acp", name: "tools", serverId: "id"}], [], toHttp)) + .rejects.toMatchObject({code: -32603, data: {name: "tools"}, message: expect.stringContaining("listen failed")}); }); - it('rejects sse, acp, and custom transports', async () => { + it('rejects sse, custom transports, and an ACP declaration without a serverId', async () => { const unsupported: Record = { "v2 sse": {type: "sse", name: "sse", url: "https://example.com/sse"}, "v2 custom": {type: "_custom", name: "custom", endpoint: "somewhere"}, "v1 sse": {type: "sse", name: "sse", url: "https://example.com/sse", headers: []} satisfies acp.McpServer, - "v1 acp": {type: "acp", name: "acp", id: "server-1"}, + "obsolete acp id": {type: "acp", name: "acp", id: "server-1"}, }; const rejections: Record = {}; for (const [label, server] of Object.entries(unsupported)) { @@ -96,10 +133,11 @@ describe('MCP server config from ACP v1 and v2 session requests', () => { .toMatchFileSnapshot("data/mcp-config-unsupported-transports.json"); }); - it('rejects an unsupported transport even when its name is already configured', async () => { - await expect(startSessionWithMcpServers([ - {type: "sse", name: "existing", url: "https://example.com/sse", headers: []}, - ], ["existing"])).rejects.toMatchObject({code: -32602}); + it.each([ + {type: "sse", name: "existing", url: "https://example.com/sse", headers: []}, + {type: "acp", name: "existing", serverId: "not-available"}, + ] satisfies AcpMcpServer[])('rejects unavailable $type transport even when its name is already configured', async server => { + await expect(startSessionWithMcpServers([server], ["existing"])).rejects.toMatchObject({code: -32602}); }); it.each([ @@ -116,6 +154,6 @@ describe('MCP server config from ACP v1 and v2 session requests', () => { it('uses the last stdio environment entry with a repeated name', async () => { const config = await startSessionWithMcpServers([{type: "stdio", name: "files", command: "mcp-fs", env: [{name: "EXAMPLE", value: "first"}, {name: "EXAMPLE", value: "last"}]}]); - expect(config).toMatchObject({files: {env: {EXAMPLE: "last"}}}); + expect(config["mcp_servers"]).toMatchObject({files: {env: {EXAMPLE: "last"}}}); }); }); diff --git a/src/__tests__/CodexJsonRpcConnectionLogs.test.ts b/src/__tests__/CodexJsonRpcConnectionLogs.test.ts index c0d3ac45d..5444e52ba 100644 --- a/src/__tests__/CodexJsonRpcConnectionLogs.test.ts +++ b/src/__tests__/CodexJsonRpcConnectionLogs.test.ts @@ -70,6 +70,17 @@ describe("attachLogs", () => { ]); }); + it("sends the MCP bearer header to Codex but redacts it from the trace", () => { + vi.spyOn(logger, "enabled", "get").mockReturnValue(true); + const log = vi.spyOn(logger, "log").mockImplementation(() => {}); + const proc = fakeProcess(); + const wire = JSON.stringify({config: {mcp_servers: {tools: {http_headers: {Authorization: "Bearer test-only"}}}}}) + "\n"; + proc.stdin.write(wire); + + expect(proc.stdin.read().toString()).toBe(wire); + expect(log.mock.calls).toEqual([[`[IN] ${wire.replace("test-only", "[REDACTED]")}`]]); + }); + it("writes the traffic to the log file when APP_SERVER_LOGS is set", async () => { const directory = fs.mkdtempSync(path.join(os.tmpdir(), "app-server-logs-")); try { diff --git a/src/__tests__/integration/mcp-over-acp.test.ts b/src/__tests__/integration/mcp-over-acp.test.ts new file mode 100644 index 000000000..34fad1206 --- /dev/null +++ b/src/__tests__/integration/mcp-over-acp.test.ts @@ -0,0 +1,170 @@ +import * as acp from "@agentclientprotocol/sdk/unstable"; +import * as acpV2 from "@agentclientprotocol/sdk/experimental/v2/unstable"; +import {once} from "node:events"; +import {mkdtempSync} from "node:fs"; +import {createServer} from "node:http"; +import type {AddressInfo} from "node:net"; +import {tmpdir} from "node:os"; +import {join} from "node:path"; +import {fileURLToPath} from "node:url"; +import {expect, it} from "vitest"; +import {createAcpAgentRouter} from "../../AcpAgentRouter"; +import {CodexAcpClient} from "../../CodexAcpClient"; +import {CodexAcpServer} from "../../CodexAcpServer"; +import {CodexAppServerClient} from "../../CodexAppServerClient"; +import {startCodexConnection} from "../../CodexJsonRpcConnection"; +import {removeDirectoryWithRetry, writeCodexHomeConfig} from "../acp-test-utils"; +import {describeIntegration} from "./integration-fixture"; + +async function connectClient(version: 1 | 2, stream: acp.Stream, provider: acp.McpOverAcpProvider) { + if (version === 1) { + const {agent} = acp.client().onRequest(acp.methods.client.mcp.message, provider.handleRequest).connect(stream); + await agent.request(acp.methods.agent.initialize, {protocolVersion: 1}); + return {agent, closeSession: (sessionId: string) => agent.request(acp.methods.agent.session.close, {sessionId})}; + } + const {agent} = acpV2.client().onRequest(acpV2.methods.client.mcp.message, provider.handleRequest).connect(stream); + await agent.request(acpV2.methods.agent.initialize, {protocolVersion: 2, info: {name: "test", version: "1"}}); + return {agent, closeSession: (sessionId: string) => agent.request(acpV2.methods.agent.session.close, {sessionId})}; +} + +const progress = {progressToken: "missing-tool", progress: 1}; +const error = {code: -32000, message: "Unknown tool", data: null}; +const cache = {ttlMs: 0, cacheScope: "private"}; + +/** An HTTP server that only speaks the initialize-based protocol. */ +async function legacyHttpServer() { + const methods: string[] = []; + const server = createServer(async (req, res) => { + if (req.method !== "POST") { res.writeHead(405).end(); return; } + const chunks = []; + for await (const chunk of req) chunks.push(chunk); + const {id, method} = JSON.parse(Buffer.concat(chunks).toString()); + methods.push(method); + if (id == null) { res.writeHead(202).end(); return; } + const outcome = method === "initialize" ? {result: { + protocolVersion: "2025-06-18", serverInfo: {name: "legacy", version: "1"}, capabilities: {tools: {}}, + }} : method === "tools/list" ? {result: {tools: []}} : {error: {code: -32601, message: "Method not found"}}; + res.writeHead(200, {"content-type": "application/json"}).end(JSON.stringify({jsonrpc: "2.0", id, ...outcome})); + }); + server.listen(0, "127.0.0.1"); + await once(server, "listening"); + return {server, methods, url: `http://127.0.0.1:${(server.address() as AddressInfo).port}/mcp`}; +} + +async function serve(request: acp.McpOperationContext): Promise { + switch (request.method) { + case "server/discover": + return {result: { + resultType: "complete", supportedVersions: [acp.MCP_PROTOCOL_VERSION], capabilities: {tools: {}}, + _meta: {"io.modelcontextprotocol/serverInfo": {name: "test", version: "1"}}, ...cache, + }}; + case "tools/list": + return {result: {resultType: "complete", tools: [{name: "echo", inputSchema: {type: "object"}}], ...cache}}; + case "tools/call": + if (request.params?.["name"] === "echo") { + return {result: {resultType: "complete", content: [{type: "text", text: "hello from ACP"}]}}; + } + await request.notify("notifications/progress", progress); + return {error}; + default: + throw new acp.McpProtocolError(-32601, `Unknown method: ${request.method}`); + } +} + +/** Inspect the HTTP stream directly: the app-server tool-call response contains only its final result. */ +async function expectProgressAndError(http: acp.McpServerHttp) { + const response = await fetch(http.url, { + method: "POST", + signal: AbortSignal.timeout(5000), + headers: { + ...Object.fromEntries(http.headers.map(h => [h.name, h.value])), + "Content-Type": "application/json", Accept: "application/json, text/event-stream", + "MCP-Protocol-Version": acp.MCP_PROTOCOL_VERSION, "MCP-Method": "tools/call", "MCP-Name": "missing", + }, + body: JSON.stringify({jsonrpc: "2.0", id: 7, method: "tools/call", + params: acp.withMcpRequestMeta({name: "missing", _meta: {progressToken: progress.progressToken}})}), + }); + expect(response.headers.get("content-type")).toContain("text/event-stream"); + const data = (await response.text()).split("\n").filter(line => line.startsWith("data:")); + expect(data.map(line => JSON.parse(line.slice(5)))).toEqual([ + {jsonrpc: "2.0", method: "notifications/progress", params: progress}, + {jsonrpc: "2.0", id: 7, error}, + ]); +} + +// Drive the bundled Codex MCP client directly; no model, API key, or external MCP server. +describeIntegration("integration: MCP-over-ACP", () => { + it.each([1, 2] as const)("calls an ACP v%i client tool alongside legacy HTTP and stdio servers", async version => { + const cwd = mkdtempSync(join(tmpdir(), "codex-acp-mcp-")); + writeCodexHomeConfig(cwd, { + model_provider: "offline", + "model_providers.offline.name": "Offline test", + "model_providers.offline.base_url": "http://127.0.0.1:1/v1", + "model_providers.offline.wire_api": "responses", + }); + const legacy = await legacyHttpServer(); + const overrides = {mcp_servers: {legacy_stdio: { + command: process.execPath, args: [fileURLToPath(import.meta.resolve("mcp-hello-world/build/stdio.js"))], + }}}; + const codex = startCodexConnection(undefined, {...process.env, CODEX_HOME: cwd}); + const exited = once(codex.process, "exit"); + const appServer = new CodexAppServerClient(codex.connection); + const incoming = new TransformStream(); + const outgoing = new TransformStream(); + let endpoint!: acp.McpServerHttp; + const router = createAcpAgentRouter((connection, toHttp) => { + const client = new CodexAcpClient(appServer, overrides, undefined, async server => { + const http = await toHttp(server); + endpoint = http; + return http; + }); + return new CodexAcpServer(connection, client); + }); + const routed = router.connect(acp.ndJsonStream(outgoing.writable, incoming.readable)); + const stream = acp.ndJsonStream(incoming.writable, outgoing.readable); + const provider = new acp.McpOverAcpProvider(); + const requests: acp.McpOperationContext[] = []; + try { + const {agent, closeSession} = await connectClient(version, stream, provider); + const {declaration} = provider.registerServer(agent, {name: "client tools", handler: request => { + requests.push(request); + return serve(request); + }}); + const session = await agent.buildSession(cwd) + .withMcpServer(declaration) + .withMcpServer({type: "http", name: "legacy_http", url: legacy.url, headers: []}) + .start(); + const names = ["client_tools", "legacy_http", "legacy_stdio"]; + const startup = await appServer.mcpStartup.await(names, 0, { + threadId: session.sessionId, signal: AbortSignal.timeout(10000), + }); + expect(startup.ready).toEqual(names); + expect(legacy.methods).toContain("initialize"); + const result = await codex.connection.sendRequest("mcpServer/tool/call", { + threadId: session.sessionId, server: "client_tools", tool: "echo", arguments: {message: "hello"}, + }); + expect(result).toMatchObject({content: [{type: "text", text: "hello from ACP"}]}); + expect(requests[0]?.method).toBe("server/discover"); + expect(requests.map(r => r.method)).toContain("tools/list"); + expect(requests.filter(r => r.method === "tools/call")).toMatchObject([{ + serverId: declaration.serverId, params: {name: "echo", arguments: {message: "hello"}}, + }]); + expect(requests.every(r => r.protocolVersion === acp.MCP_PROTOCOL_VERSION)).toBe(true); + expect(new Set(requests.map(r => r.requestId)).size).toBe(requests.length); + + await closeSession(session.sessionId); + expect((await fetch(endpoint.url)).status).toBe(401); + await expectProgressAndError(endpoint); // The registration belongs to the connection, not the session. + } finally { + await incoming.writable.close(); + await routed.closed; + await outgoing.writable.close(); + codex.process.stdin.end(); + await exited; + legacy.server.closeAllConnections(); + await new Promise(done => legacy.server.close(() => done())); + removeDirectoryWithRetry(cwd); + } + await expect(fetch(endpoint.url)).rejects.toThrow(); + }); +}); diff --git a/src/index.ts b/src/index.ts index fac623a79..e1e89f2a4 100644 --- a/src/index.ts +++ b/src/index.ts @@ -14,6 +14,7 @@ import {runCodexCli} from "./CodexCli"; import {prepareCodexHookConfig} from "./CodexHookConfig"; import {createAcpAgentRouter} from "./AcpAgentRouter"; import type {AcpClientConnection, AcpV2Connection} from "./ACPSessionConnection"; +import type {McpOverAcpToHttp} from "./McpServerConfig"; if (process.argv.includes("--version")) { console.log(`${packageJson.name} ${packageJson.version}`); @@ -84,9 +85,9 @@ function startAcpServer() { const acpJsonStream = createJsonStream(process.stdin, process.stdout); - function createAgent(connection: AcpClientConnection | AcpV2Connection): CodexAcpServer { + function createAgent(connection: AcpClientConnection | AcpV2Connection, toHttp: McpOverAcpToHttp): CodexAcpServer { const appServerClient = new CodexAppServerClient(codexProcessState.connection.connection); - const codexClient = new CodexAcpClient(appServerClient, hookConfig.sessionConfig, modelProvider); + const codexClient = new CodexAcpClient(appServerClient, hookConfig.sessionConfig, modelProvider, toHttp); return new CodexAcpServer( connection, codexClient,