| 1 | # ADR 0043: MCP transport recovery parity (human ↔ agent) and host boundaries |
| 2 | |
| 3 | **Status:** Proposed |
| 4 | **Date:** 2026-04-13 |
| 5 | |
| 6 | ## Related ADRs |
| 7 | |
| 8 | | ADR | Role | |
| 9 | |-----|------| |
| 10 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | MCP contracts | |
| 11 | | [0016](0016-agent-client-protocol-external-agent.md) | ACP orthogonal to MCP | |
| 12 | | [0002](0002-debug-human-agent-parity.md) | unified debug state layer for human and agent | |
| 13 | |
| 14 | ### Outside ADR |
| 15 | |
| 16 | | Document | Role | |
| 17 | |----------|------| |
| 18 | | [north-star-cursor-mcp-cascade-workbench-v1.md](../../design/north-star-cursor-mcp-cascade-workbench-v1.md) | Cursor + MCP + Cascade | |
| 19 | | [MCP-PROTOCOL.md](../../MCP-PROTOCOL.md) | stdio transport, MCP visibility | |
| 20 | |
| 21 | --- |
| 22 | ## Context |
| 23 | |
| 24 | Product north star assumes a working **Cursor (or equivalent) + MCP + CascadeIDE** loop: the agent calls IDE tools and sees state aligned with the human ([north-star § criteria](../../design/north-star-cursor-mcp-cascade-workbench-v1.md#критерии-мы-в-зоне-цели-проверяемые)). |
| 25 | |
| 26 | <a id="adr0043-motivation"></a> |
| 27 | |
| 28 | ### Product logic: MCP as “way to act in the world” |
| 29 | |
| 30 | For the agent **MCP is not background detail but the action interface**: without a live tool channel it is not “just less convenient” but **limited in the same way a human without a hand** — except humans usually have **workarounds**: another tool, restart, settings, a “prosthesis” (alternate path to the goal). In the host ecosystem some servers may be **built-in**, most are **external processes**; a human operator on failure can **fix any broken link** in their chain. |
| 31 | |
| 32 | **The agent in a typical chat cannot pick the host or restart its own tool:** it sends calls on **that** transport. If MCP is dead or hung the agent **lacks** the self-help class humans treat as normal. That is not pedantic UX complaint — **structural asymmetry of operability**: humans can restore or bypass the chain; the agent often cannot while the same results are expected. That **contradicts parity intuition** “we are in the same work” and deserves explicit product/host design recognition, not “just restart MCP by hand”. |
| 33 | |
| 34 | ### Technical: where the boundary runs |
| 35 | |
| 36 | Host MCP servers are **processes**: stdio exchange with CascadeIDE child `--mcp-stdio`, plus **other host-configured MCP processes** (e.g. separate Roslyn tools server for C#, .NET debug server). That is **not** built-in Roslyn/DAP inside the CascadeIDE window — each process has its own transport and lifecycle managed by the **host**, not the IDE. Agent limitation follows from **ProcessHost** role, not “did not want to” in one repo. |
| 37 | |
| 38 | **Link to [0002](0002-debug-human-agent-parity.md):** there — parity of **debug state** in the IDE; here — another axis: **MCP channel availability** and recovery after failure. |
| 39 | |
| 40 | ## Solution (direction, no deadline commitment) |
| 41 | |
| 42 | <a id="adr0043-p1"></a> |
| 43 | |
| 44 | 1. **Explicit levels:** |
| 45 | - **Level A — host (Cursor and equivalents):** start, stop, restart **any** MCP server the host holds in config. CascadeIDE **does not replace** the host and does not promise arbitrary restart of neighbor servers from the IDE process. |
| 46 | - **Level B — CascadeIDE process:** in prospect — **controlled** recovery of **its own** MCP server role (e.g. re-init stdio session **within** supported model), only if safe for UI and not breaking [0008](0008-mcp-contracts-and-testable-infrastructure.md). Separate design/implementation iterations. |
| 47 | - **Level C — observability:** extend diagnostics “transport alive / command did not arrive / IDE not in MCP mode” so **agent and human** rely on **the same** signals (state snapshot, explicit tool errors), per [MCP-PROTOCOL.md § “MCP visibility”](../../MCP-PROTOCOL.md#видимость-mcp-для-агента-на-будущее-свои-mcp-в-ide). |
| 48 | |
| 49 | <a id="adr0043-p2"></a> |
| 50 | |
| 51 | 2. **Parity goal:** where technically possible, **recovery or explicit degradation** of the channel should be available **both** via human actions in the host **and** via a **supported** contract (IDE tools, host commands, or documented scenario), not only “tell the user to restart MCP”. |
| 52 | |
| 53 | <a id="adr0043-p3"></a> |
| 54 | |
| 55 | 3. **ACP:** external agent per [0016](0016-agent-client-protocol-external-agent.md) stays **orthogonal** to this ADR; MCP transport recovery to IDE is not mixed with ACP transport except **clear errors** and observability. |
| 56 | |
| 57 | ## Consequences |
| 58 | |
| 59 | - **Meaningful** backlog items: MCP health in IDE snapshots, if needed narrow “re-lift own server mode” commands, host alignment — separate. |
| 60 | - Dependence on **Cursor roadmap** (or other client) for full parity “agent restarts any MCP” — reflect honestly in docs and north-star, without promising “everything in one IDE repo”. |
| 61 | |
| 62 | ## Rejected alternatives |
| 63 | |
| 64 | - **Arbitrary restart of foreign MCP processes from CascadeIDE** without host — rejected: violates ProcessHost boundary, unsafe, not portable. |
| 65 | - **Silence on breakage** and treating it as user-only problem — rejected as contradicting north-star on reducing friction moving from Cursor. |
| 66 | |