Go to file
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
2025-09-02 19:06:32 -03:00
2026-03-26 12:19:06 +01:00

ACP adapter for the Claude Agent SDK

npm

Use Claude Agent SDK from ACP-compatible clients!

This tool implements an ACP agent by using the official Claude Agent SDK, supporting:

  • Context @-mentions
  • Images
  • Tool calls (with permission requests)
  • Compact file changes through the negotiated AIR diff patch extension
  • Following
  • Edit review
  • TODO lists
  • Nested subagent transcripts
  • Interactive (and background) terminals
  • Custom Slash commands
  • Client MCP servers, including the ones that the client serves over the ACP connection (MCP-over-ACP, "type": "acp")
  • An Ultracode session config option, which turns on Claude Code's dynamic workflows for every task. It appears when dynamic workflows are enabled and the model supports ultracode (any model with xhigh effort)
  • /mcp in the chat: the MCP server status as a list. The adapter runs /mcp reconnect, /mcp enable, and /mcp disable through the SDK control API, because Claude Code refuses them in SDK mode. A reconnect of an ACP server that needs authentication starts MCP OAuth through URL elicitation
  • Session-scoped long-running goals for AIR through the goal extension under _meta.jetbrains.air.goal
  • Structured errors, recovery, and warnings through the opt-in session failure extension
  • Concrete model and effort defaults through the opt-in recommended config value extension
  • Tool permission presentation, editable choices, and durable effects through the permission extension
  • One fact per field in every tool call report, as the ACP tool call contract defines
  • All AIR extensions, capabilities, and _meta keys: AIR extensions

Learn more about the Agent Client Protocol.

To try changes that have landed on main but are not released yet, install from the preview channel — every push to main publishes one. See docs/RELEASES.md.

npm install @agentclientprotocol/claude-agent-acp@preview

Standalone executables

Each release attaches archives for Linux (glibc and musl), macOS and Windows, on x64 and arm64, to its GitHub release. They need no Node.js install. Each holds two files: claude-agent-acp, and the Claude CLI (claude) it runs. Keep them in the same directory; a symlink to claude-agent-acp elsewhere works. To use a Claude CLI you already have instead, set CLAUDE_CODE_EXECUTABLE. On Alpine, install libgcc and libstdc++ first.

A CLI named with CLAUDE_CODE_EXECUTABLE gets a session's MCP servers on its command line, where other users of the machine can read their env and headers. The CLI that comes with the adapter gets them over stdin.

To build one for your machine (needs Bun) and check it:

npm run build:binary
npm run smoke:binary            # add `-- --full` to drive a real session; needs a Claude login

Experimental ACP v2

The adapter also serves the draft ACP v2: a client that asks for protocol version 2 or later in initialize gets v2, and every other client gets v1. The draft can still change, and this surface changes with it.

CLAUDE_AGENT_ACP_PROTOCOL limits the adapter to one version. With v1, a client that asks for v2 is negotiated down to v1. With v2, the adapter rejects the initialize of a v1 client. auto, the default, serves both.

On v2 the adapter serves the session baseline (session/new, session/list, session/resume with replay, which replay_complete ends, session/close, session/prompt, session/cancel), session/delete, session/fork, session/status, session/options (with initial configOptions on session/new, session/resume and session/fork), session/set_title, additional directories, config options (the mode is one), plans, notices, compaction, display terminals for commands, permission requests, elicitation, providers, auth, and subagents. Steering is v1 only for now.

v2 is served by the v2 agent in src/v2/, which runs straight on Claude Code instead of translating to v1. A v2 client that declares JetBrains AIR (_meta.jetbrains.air) also gets the AIR extensions that ACP v2 does not cover.

Contribution Policy

This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms:

By contributing to this project, you agree that your contributions will be licensed under the Apache License, Version 2.0. You affirm that you have the legal right to submit your work, that you are not including code you do not have rights to, and that you understand contributions are made without requiring a Contributor License Agreement (CLA).

Description
Pull mirror of agentclientprotocol/claude-agent-acp (Apache-2.0): the ACP bridge that lets Buzz drive Claude Code
Readme 60 MiB
Languages
TypeScript 98.9%
JavaScript 1%
Shell 0.1%