Go to file
Ben Brandt 96dd2bb10d fix: start a session without an MCP-over-ACP server whose local endpoint cannot open (#1653)
## Summary

An MCP server that the client declares with `"type": "acp"` can no
longer fail session setup. The session starts without the server and the
user gets the usual "failed to start" warning.

This comes out of #1651. It does not make the server of that issue
connect (see "Not fixed here").

## What was failing

The adapter serves an `acp` server to Claude Code through a listener on
`127.0.0.1` (`McpOverAcp`, #1645). When that listener could not open,
for example `listen EPERM` where the process may not open a socket,
`session/new` failed with `-32603`:

> Could not open the local endpoint that serves MCP server tools to
Claude Code: listen EPERM: operation not permitted 127.0.0.1. Start the
session without the server, or try again.

A session starts without any other MCP server that does not connect (a
stdio command that is missing, an HTTP server that is down). The `acp`
case was the only one that ended setup.

## What changes

- **`sdkMcpServers`** (`src/mcp-servers.ts`) returns `{ configs,
unserved }`. An `acp` server that gets no endpoint is in `unserved` with
the error, and the other servers keep their configs.
- **Both cores report it** through the existing notice of a client
server that did not start (`mcpServerStartupNotice`), once per server,
on the first turn. On v1 that is `reportMcpServerStartupFailures`, on v2
`SessionReports.mcpStartupFailures`. A resume of the active session on
v2 (`setMcpServers`) reports it the same way.
- **The notice has the error.** Claude Code was never given the server,
so `/mcp` does not list it and "Run /mcp for the error" would lead
nowhere:

> **MCP server "tools" failed to start:** Its tools are unavailable in
this session. The adapter could not open the local endpoint that serves
it to Claude Code (listen EPERM: operation not permitted 127.0.0.1). A
new session tries again.

- The adapter also logs the server and the error at setup.

A later session, or a restart of the session's query, tries to open the
listener again.

## Not fixed here

In #1651 the server is listed as failed because Claude Code sends
`initialize` first and the endpoint accepts MCP 2026-07-28 requests
only. That is unchanged.

Setup did not fail in that case before this PR either. Checked through
the built adapter with Claude Code 2.1.326, without a model turn:

| Case | `session/new` | The server |
| --- | --- | --- |
| Claude Code as it starts by default | succeeds | connects
(`server/discover`, then `tools/list`) |
| `MCP_PROTOCOL_NEGOTIATION=legacy` (Claude Code sends `initialize`) |
succeeds | failed, with the warning |
| The client rejects `server/discover` | succeeds | failed, with the
warning |
| The client never answers `mcp/message` | succeeds | not connected |
| The listener cannot open, before this PR | fails with `-32603` | |
| The listener cannot open, with this PR | succeeds | left out, with the
warning above |

For the last two rows the adapter ran with a preload that makes
`http.Server.prototype.listen` fail.

## Testing

- `npm run check`, `npm run build`, `npm run test:run` (4,314 tests
pass)
- New tests: `sdkMcpServers` with an endpoint that rejects,
`session/new` on v1, the notice on v1, and on v2 both `session/new` and
a resume of the active session
- The live cases in the table above

Refs #1651
2026-11-18 14:08:22 +01: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 64 MiB
Languages
TypeScript 99%
JavaScript 0.9%
Shell 0.1%