kandev/docs/decisions/2026-07-30-session-owned-mcp-observability.md

ADR-2026-07-30-session-owned-mcp-observability: Keep MCP Attachment Evidence Session Owned

Status: accepted Date: 2026-07-30 Area: backend, frontend, protocol, security

Context

Kandev configures MCP at several boundaries: agent profiles resolve servers, executor policy can filter them, ACP adapters deliver supported transports, passthrough strategies materialize CLI-specific configuration, and agentctl hosts Kandev's task-aware MCP endpoint. The current toolbar collapses those steps into a list derived from the profile, so “configured” is presented as if it meant “attached.”

ACP initialize advertises transport capabilities and session/new accepts mcpServers, but the protocol does not return a standard list of MCP servers that connected successfully. A connection failure can also happen before the target server observes any request. Raw ACP and stderr capture would improve diagnosis but can contain prompts, files, tool arguments, URLs, headers, environment values, and credentials, making unconditional release logging an unacceptable privacy boundary.

Concurrent agents make global status invalid. A task can own several Kandev sessions, and a single session can restart into several execution generations or reset its provider session inside one execution. An old successful connection must not make a new attachment attempt appear healthy.

Decision

MCP attachment observability is owned by the Kandev session and execution:

• Every report is keyed by backend-owned task_id, session_id, execution_id, and attachment_attempt_id, enriched with agent/profile identity and provider ACP session identity when available. Every session/new, session/load, session/reset, or passthrough process start creates a new attempt before delivery.
• Agentctl's instance identity is the authoritative execution generation for local MCP observations. The server injects task and session ownership from that instance; agent-supplied IDs never select the report.
• Each MCP transport client gets an opaque connection ID. Shared connections remain shared; Kandev does not infer internal subagent identity.
• Configuration resolution, filtering, delivery, session acceptance, initialize, tools/list, tool use, explicit errors, disconnect, and supersession are separate evidence events. The UI displays the strongest observed evidence and never treats missing evidence as a connection failure.
• Kandev's in-agentctl MCP server uses transport/session hooks to observe initialize, tools/list, calls, and disconnects. Third-party direct MCP servers remain delivery-unverified unless an explicit agent error or future observable proxy/provider contract exists.
• Release mode persists a bounded structured timeline for the current and two previous attachment attempts. It contains stable reason codes and sanitized summaries, not raw protocol frames or persistent stderr.
• Sanitized network targets retain only scheme and host with optional port. Stdio targets retain only the executable basename. Headers, environment values, arguments, credentials, prompts, files, tool inputs/results, full URLs, and raw agent output are excluded.
• Recent agent stderr remains an explicit, on-demand, bounded, ephemeral diagnostic. It is warned as potentially sensitive and is never included in the default copied report.
• A user-initiated endpoint test runs only against a server already present in the session's effective configuration and from the same executor. Its result is presented as reachability evidence, not proof that the agent attached.
• The toolbar trigger stays visually neutral. Per-server colors and diagnostic actions appear in a desktop hover/focus popover that can be pinned, or an inset mobile drawer opened by a 44px touch target.
• acpdbg gains an opt-in sentinel MCP probe so agent integrations can be tested against the real ACP handshake. Advertised capabilities, delivery, initialize, tool listing, and tool use remain separate findings.

The observable behavior is specified in docs/specs/mcp-session-observability/spec.md.

Consequences

Users can distinguish “Kandev sent this configuration” from “the agent loaded these tools” for each concurrent session, including after restarts. Release diagnostics remain useful without enabling high-risk raw frame logging.

The report is deliberately asymmetric: Kandev can automatically prove more about its own in-session endpoint than about third-party servers. Some rows will remain unverified even when the agent is working correctly. The UI and public documentation must explain that limitation.

Lifecycle, agentctl, orchestrator persistence, boot hydration, WebSocket state, and the chat toolbar must share one versioned report contract. Each new attachment attempt supersedes current display evidence before it can deliver configuration, including resets that reuse an execution. Passthrough agents must emit honest resolution/materialization evidence; a missing passthrough strategy is Filtered or Unavailable, not Active.

Endpoint tests and stderr reads become new session-keyed diagnostic entry points. They must use the existing authorization guards, accept only stored server names, remain bounded, and avoid turning arbitrary user input into network or process execution.

Alternatives Considered

• Keep deriving status from profile configuration. Rejected because it creates false positives and cannot distinguish concurrent executions.
• Parse a connected-server list from ACP. Rejected because ACP defines no such portable response; provider-specific metadata can be supplemental but cannot be the product contract.
• Mark a server failed when no connection appears after a timeout. Rejected because third-party connections may be unobservable or lazy, and absence is not failure evidence.
• Proxy every MCP server through Kandev. Deferred because it changes transport ownership, credentials, performance, and failure domains far beyond an observability feature.
• Enable raw ACP and stderr logging in release mode. Rejected because the diagnostic value does not justify persistent capture of user and credential data.
• Show status colors directly on every toolbar icon. Rejected because many concurrent sessions would create visual noise; the neutral trigger with details on disclosure preserves density.
• Key status only by task or ACP session ID. Rejected because tasks can run several agents and ACP IDs can rotate or collide across providers. Kandev's session, execution, and attachment-attempt identities form the stable ownership boundary.