Files
claude-agent-acp/src
Ben Brandt c4dd80d739 fix: send MCP servers to Claude Code over stdin, not on its command line (#1647)
## 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.
2026-11-17 13:33:52 +00:00
..