RFC: Adopt a dual-stack migration for MCP 2026-07-28

## Summary

Propose a stateless-first, dual-stack migration for AGT MCP support so the repo can interoperate with MCP `2026-07-28` while preserving compatibility with existing `2025-11-25` integrations during a bounded transition window. This discussion is based on ADR 0027 and is intended to gather OSS feedback before any cross-cutting implementation work starts.

ADR reference: https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/adr/0027-adopt-dual-stack-migration-for-mcp-2026-07-28.md

## Motivation

The MCP `2026-07-28` release candidate introduces several breaking changes relative to the lifecycle currently assumed in parts of this repository, including removal of protocol-level sessions, a shift away from `initialize` / `notifications/initialized` as the primary flow, movement of client info and capabilities into per-request `_meta`, and preference for `server/discover`.

AGT currently has MCP-aware surfaces that still encode the older lifecycle, including:

- `agent-governance-python\agent-os\src\agent_os\cli\mcp_scan.py`
- `agent-governance-claude-code\server\agt-mcp.mjs`
- `agent-governance-antigravity-cli\assets\extensions\agt-global-policy\mcp\server.mjs`
- MCP docs and tests that assume `initialize`, `notifications/initialized`, and `Mcp-Session-Id`

Without adaptation, AGT will fail to interoperate cleanly with RC-compliant MCP clients and servers, continue teaching obsolete MCP patterns in docs, and keep governance features coupled to transport semantics that MCP is removing.

## Detailed Design

If accepted, AGT would adopt a version-aware MCP compatibility layer that supports both:

1. **Legacy flow (`2025-11-25`)**: send `initialize`, validate `protocolVersion`, `capabilities`, and `serverInfo`, optionally send `notifications/initialized`, then continue with primitive listing.
2. **Stateless flow (`2026-07-28`)**: send `server/discover`, read capability and extension declarations, then issue self-contained requests with `MCP-Protocol-Version: 2026-07-28`, `Mcp-Method`, `Mcp-Name` when required, and per-request `_meta` carrying client info and capabilities.

The compatibility layer would:

- identify whether the peer is using legacy or stateless behavior
- normalize discovery behavior
- normalize request construction for list, read, and call flows
- attach per-request `_meta` for stateless requests
- centralize Streamable HTTP header generation
- isolate legacy session handling so it does not leak into higher-level governance logic

During migration, AGT bundled servers would become stateless-first while retaining legacy compatibility shims. Components such as `mcp_session_auth.py` and `MCPSessionStore` would be treated as application-level auth or state helpers rather than protocol-session helpers.

Expected implementation work streams:

- update `mcp_scan.py` to use supported-version negotiation, add `server/discover`, move client metadata into per-request `_meta`, stop depending on `Mcp-Session-Id`, generate `Mcp-Method` / `Mcp-Name`, and preserve explicit fallback to the legacy lifecycle
- update bundled MCP servers to implement `server/discover`, become stateless-first, keep `initialize` as a compatibility path, and treat `notifications/initialized` as a no-op compatibility shim
- update docs and tests to describe `2026-07-28` as the preferred target, explain the dual-stack transition, stop teaching `Mcp-Session-Id` as part of the normal lifecycle, and distinguish AGT application auth/state from MCP protocol sessions

## Alternatives Considered

- **Stay on the legacy lifecycle only**: lowest short-term cost, but leaves AGT misaligned with the MCP direction and risks interoperability failures with RC-compliant peers.
- **Cut directly to `2026-07-28` with no compatibility window**: simpler long-term architecture, but unnecessarily breaks existing AGT integrations and raises migration risk.
- **Treat migration as piecemeal implementation work without an explicit design decision**: faster to start, but risky for a cross-cutting change that spans scanner behavior, bundled servers, docs, and tests.

## Security Implications

This change should reduce coupling between governance behavior and wire-level lifecycle assumptions, which is good for clarity and auditability. At the same time, it changes how client metadata and request context are conveyed, so the design needs careful review to ensure:

- auth and trust decisions do not implicitly depend on deprecated transport-session semantics
- legacy compatibility paths fail closed when peer negotiation or request metadata is invalid
- request metadata carried in `_meta` is validated consistently across supported versions
- AGT-managed auth/state helpers remain clearly separated from MCP protocol behavior

## Migration / Backward Compatibility

The proposal is explicitly dual-stack and preserves `2025-11-25` compatibility during a bounded transition window. Migration would be considered complete when:

- AGT can inspect `2026-07-28` MCP servers without relying on `initialize` or `Mcp-Session-Id`
- bundled MCP servers interoperate with stateless clients
- existing `2025-11-25` integrations still work during the transition window
- repo docs no longer describe the legacy session-based lifecycle as the default

## Scope

Architecture-wide

## Target Placement

Core (agent-os, agent-mesh, agent-hypervisor)

## Prior Art

- ADR 0027: https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/adr/0027-adopt-dual-stack-migration-for-mcp-2026-07-28.md
- MCP `2026-07-28` release candidate and related protocol discussions

## Checklist

- [x] I have searched existing issues and RFCs for duplicates
- [x] I have read the ADR index (`adr/index.md`) for related decisions
- [x] I am willing to implement this RFC or help review an implementation