feat(acp): Add v2 session MCP attachment (#303)

Author: benbrandt

README.md

@@ -22,8 +22,12 @@ This repository is the official **Rust SDK** for ACP. It provides crates for bui
 Native MCP-over-ACP support is currently opt-in through the core crate's
 `unstable_mcp_over_acp` feature. Standalone MCP servers need no ACP transport
 feature; the rmcp integration exposes a matching passthrough feature when those
-servers are attached to ACP. MCP attachment and proxy-session helpers currently
-use stable protocol v1.
+servers are attached to ACP. Stable protocol v1 supports per-session and global
+proxy attachment. Per-session attachment through the draft `V2SessionBuilder`
+is also available when both `unstable_protocol_v2` and
+`unstable_mcp_over_acp` are enabled. Successful v2 attachments remain active
+for the connection lifetime; global proxy attachment and proxy-session helpers
+remain v1-only.
 
 **Proxy orchestration**
 

md/protocol-v2.md

@@ -207,10 +207,19 @@ them in order. If a handler forwards updates to another task, the application
 is responsible for any additional projection-drained barrier it needs before
 treating replay as locally applied.
 
-Dropping command handles has no network or inbound-routing side effect. If an
-application wants stream ergonomics, it can fan typed updates out from the
-connection handler with an explicit buffering and subscriber policy. MCP
-attachment and proxy-session helpers are still v1-only.
+Dropping command handles has no network or inbound-routing side effect. For a
+session created with `V2SessionBuilder::with_mcp_server`, the SDK installs the
+MCP routes and initially polls their runner tasks before publishing
+`session/new`, so the agent can connect to those servers during session setup.
+Runners may continue asynchronous initialization; custom connectors must be
+able to queue connections and messages once constructed. A successful setup
+promotes the attachment to the connection lifetime; any setup failure cleans it
+up. This attachment requires both `unstable_protocol_v2` and
+`unstable_mcp_over_acp`. Global proxy attachment and proxy-session helpers
+remain v1-only.
+
+If an application wants stream ergonomics, it can fan typed updates out from
+the connection handler with an explicit buffering and subscriber policy.
 
 ## Conductor and proxy initialization
 
@@ -346,17 +355,19 @@ agent:
 
 ## Draft schema changes in schema 1.5 and 1.6
 
-The `unstable_protocol_v2` API follows the moving draft schema. Schema 1.5 adds
-semantic newtypes for paths, media types, IDs, and cursors; renames
-`DiffPatch.diff` to `DiffPatch.text`; adds terminal state and output update
-types; and makes v1/v2 conversions fallible and generic. These are draft API
-changes rather than stable v1 wire changes. See [Migrating to
+The `unstable_protocol_v2` API follows the moving draft schema. Schema 1.5 added
+semantic newtypes for paths, media types, IDs, and cursors; renamed
+`DiffPatch.diff` to `DiffPatch.text`; and added terminal state and output update
+types. The next schema dependency update removes the former schema-wide v1/v2
+conversion API: versioned implementations should remain separate, with
+purpose-specific adapters at runtime boundaries where the required state and
+policy are available. These are draft API changes rather than stable v1 wire
+changes. See [Migrating to
 v2.0](./migration_v2.0.md#draft-v2-schema-updates) for concrete source changes.
 
 Schema 1.6 adds `Cancelled` tool-call and plan-entry statuses to draft v2.
 Programmatic tool-call names are available in both protocol versions through
 the separate `unstable_tool_call_name` feature. Draft v2 users must enable both
 `unstable_protocol_v2` and `unstable_tool_call_name`. In v2, an omitted name
 leaves the existing value unchanged, `null` clears it, and a string replaces
-it. V1 cannot clear an existing name, so converting a v2 `null` name to v1
-fails.
+it. V1 cannot express the explicit v2 `null` clear operation.

src/agent-client-protocol/CHANGELOG.md

@@ -14,8 +14,13 @@
   cancellation. `Client.v2()` and `Agent.v2()` callbacks receive a
   `V2ConnectionTo` whose unversioned `build_session*` and `resume_session*`
   methods expose only the v2 lifecycle. Session updates and interactive
-  requests remain on typed connection handlers; MCP attachment and
-  proxy-session helpers remain v1-only.
+  requests remain on typed connection handlers. With
+  `unstable_mcp_over_acp`, `V2SessionBuilder::with_mcp_server` adds native
+  per-session MCP attachment while preserving independent response
+  consumption. MCP routes are installed and runners begin executing before
+  `session/new` is published; successful attachments remain active for the
+  connection lifetime. Global proxy attachment and proxy-session helpers
+  remain v1-only.
 - *(unstable-v2)* Expose protocol-neutral dynamic handler registration on
   `V2ConnectionTo`.
 - *(unstable-v2)* Add `ConnectionTo::spawn_connection_with_context` for raw

src/agent-client-protocol/README.md

@@ -45,7 +45,9 @@ Draft protocol v2 is opt-in through `unstable_protocol_v2`. `Client.v2()` and
 high-level, command-only session helpers because prompt acceptance and inbound
 traffic are independent. Session updates and interactive requests use typed
 connection handlers. See [Protocol V2](https://agentclientprotocol.github.io/rust-sdk/protocol-v2.html#high-level-v2-sessions).
-MCP attachment and proxy-session helpers remain v1-only.
+Per-session MCP attachment through `V2SessionBuilder` is available with both
+`unstable_protocol_v2` and `unstable_mcp_over_acp`. Global proxy attachment and
+proxy-session helpers remain v1-only.
 
 ## MCP Server Attachment
 
@@ -55,7 +57,10 @@ the `with_mcp_server` builder methods requires `unstable_mcp_over_acp`.
 Attached servers are advertised with native `McpServer::Acp` declarations and
 communicate through `mcp/connect`, `mcp/message`, and `mcp/disconnect`. Use
 `agent-client-protocol-polyfill` immediately before an HTTP-capable agent.
-These ACP attachment and proxy paths currently use stable protocol v1.
+Stable protocol v1 supports per-session and global proxy attachment. Draft
+protocol v2 supports per-session `session/new` attachment when both unstable
+features are enabled; successful attachments remain active for the connection
+lifetime, and its global proxy path remains v1-only.
 
 ## Learning More
 

src/agent-client-protocol/src/concepts/sessions.rs

@@ -85,7 +85,10 @@
 //! tools to the agent:
 //!
 //! MCP attachment requires the `unstable_mcp_over_acp` feature. Standalone MCP
-//! servers remain available without it.
+//! servers remain available without it. Draft protocol v2 per-session
+//! attachment uses `V2SessionBuilder::with_mcp_server` and additionally
+//! requires `unstable_protocol_v2`; successful v2 attachments remain active
+//! for the connection lifetime.
 //!
 //! ```ignore
 //! # use agent_client_protocol::{Client, Agent, ConnectTo};