mirror of
https://github.com/agentclientprotocol/claude-agent-acp.git
synced 2026-11-17 23:01:26 +00:00
## Summary The adapter now sends a session's MCP servers to Claude Code over stdin, not on its command line. A server's `env` and `headers` were readable there by other users of the machine (`ps`). That includes the bearer token of the local endpoint that serves an MCP-over-ACP server (#1645). This uses the `mcpServersDelivery` option of SDK 0.3.326. It is stacked on #1646, which updates the SDK and sets the option to `'argv'`. Merge #1646 first. ## What changes `mcpServersDelivery()` in `src/claude-cli.ts` picks the delivery, next to `claudeCliPath()`, because it depends on which CLI is started: - **The CLI that the adapter ships** (next to the executable, or the SDK's platform package) gets the servers in the SDK's initialize request: `'initialize'`. The SDK starts it with `--await-initialize` and without `--mcp-config`. - **A CLI that `CLAUDE_CODE_EXECUTABLE` names** gets them in the `--mcp-config` flag as before: `'argv'`. Its version is not known, and the SDK ends the session at startup when the CLI cannot read the servers from the initialize request. For such a CLI nothing changes, and the README says so. Both cores set the value before the client's options, so a client's `_meta.claudeCode.options.mcpServersDelivery` still wins. A session without MCP servers starts as before: the SDK adds `--await-initialize` only when it has servers to send. ## Why `CLAUDE_CODE_EXECUTABLE` keeps `'argv'` for now Reading the servers from the initialize request needs Claude Code 2.1.326, which came out on 2026-11-16. The `stable` channel of Claude Code is at 2.1.311. With `'initialize'` for every CLI, a session with an MCP server would fail for each user whose `CLAUDE_CODE_EXECUTABLE` CLI is older. Checked with 2.1.323 through the adapter: `session/new` fails with `-32603` and "This Claude Code (version 2.1.323) is too old to read MCP servers from the initialize request". The plan is to drop the `'argv'` case once the `stable` channel is at 2.1.326 or newer, with an error that names `CLAUDE_CODE_EXECUTABLE`. ## Checked against the real CLI Through the built adapter, with a stdio server that has a secret in its `env` and an HTTP server with a secret `Authorization` header, and without a prompt: | | The adapter's CLI | `CLAUDE_CODE_EXECUTABLE` | | --- | --- | --- | | Launch flag | `--await-initialize` | `--mcp-config` | | Secret on a command line (`ps`) | no | yes, as before | | stdio server connects and gets its `env` | yes | yes | This holds on v1 (a probe that is not part of this PR) and on v2. On v2 the MCP-over-ACP integration test now also checks that no command line of the adapter's processes holds the endpoint's bearer token. With `CLAUDE_CODE_EXECUTABLE` set, that check finds the token, so the test skips it there. With the SDK alone, under `'initialize'`: - A resumed session (`--resume`) gets its servers: `mcp_servers_applied` is true and the server connects. - A startup failure still rejects with its reason: an invalid `HTTPS_PROXY` gives `startupFailureReason: "proxy_invalid"` and the same message as under `'argv'`. ## Notes for review - **One difference that the SDK documents:** a Claude Code process that the session's own process starts is not handed servers that came in the initialize request. Subagents run in the session's process and are not affected. - **Unit runs take the `'argv'` case.** `vitest.config.ts` sets `CLAUDE_CODE_EXECUTABLE` for them. So the session tests of v1 and v2 show that the value is passed and that the client's option wins. `src/tests/claude-cli.test.ts` covers the rule, and the integration test covers `'initialize'` end to end. ## Testing - `npm run build`, `npm run check`, `npm run test:run` (4,285 tests pass) - Real CLI: the integration tests (`RUN_INTEGRATION_TESTS=true`, with `CLAUDE_CODE_ENTRYPOINT` unset), 916 tests pass - Real CLI: the probes above. One of them sends a prompt (one short Haiku turn, to make a session to resume). Of 6 full unit runs, 4 passed and 2 had one failure each. The one I captured is "reads only the changed transcript for a subscription" in `src/tests/v1/session-index.test.ts`, which passed in 12 runs alone. It counts the transcripts that the session index reads after a file watcher event (3 where it expects at most 1). This PR does not touch that code. Not changed here. The other failure was not captured.