Route server-to-client MCP messages per session

[JAORMX]

Summary

The Streamable HTTP proxy returned 405 on GET and dropped every container→client message (dispatcher.go: "Notifications are ignored for streamable HTTP"). Server-initiated MCP flows — progress, resources/updated, */list_changed, sampling, elicitation — never reached clients over our default transport (the legacy SSE proxy forwarded them; the modern one silently lost them).

This implements a standalone GET SSE stream and routes each server→client message to the correct session — or securely refuses it. The design goal was correctness and zero cross-session leakage over a shared-backend multiplexing proxy, not incremental scoping.

• Per-session delivery streams: a registry keyed by Mcp-Session-Id, at most one standalone GET SSE stream per session (evict-and-replace on reconnect). Each stream has a dedicated stop signal and its data channel is never closed, so a client disconnecting during fan-out can't panic: send on closed channel in the dispatcher goroutine.
• Routing by message type (delivery is targeted, never broadcast-to-all):
  • notifications/{tools,resources,prompts}/list_changed → every connected session once (genuinely global; payload-free; the follow-up tools/list is re-filtered on the POST path — no filter bypass).
  • notifications/progress → the originating request's own POST SSE stream, correlated by rewriting the client's progressToken to a proxy-minted unique token (eliminates cross-session token collisions; the client's original token is restored before delivery).
  • notifications/resources/updated → only sessions subscribed to that URI (per-session subscription registry; ref-counted so the shared backend receives exactly one subscribe/unsubscribe).
  • notifications/message (logging) and server→client requests (sampling/createMessage, elicitation/create) are structurally unattributable over a single shared backend, so they are securely dropped — forwarding them would leak one client's data to another, or let one client answer another's elicitation. Server requests get a JSON-RPC -32601 back so the backend unblocks; the upstream logging level is still reconciled to the max verbosity across sessions.
• Per-URI keyed mutex orders concurrent same-URI subscribe/unsubscribe so the backend never desyncs from the routing table's ref-count.

GET is behind the same auth/middleware chain as POST. Standalone SSE is on by default (opt-out via WithStandaloneSSE(false) → 405). The delivery/routing layer is transport-agnostic so the 2026-07-28 subscriptions/listen replacement plugs into the same registry.

Closes #5744

Type of change

• Bug fix (protocol feature loss on the default transport; also closes a would-be cross-session information-disclosure surface)

Test plan

• Unit tests (task test) — affected packages pass; new unit tests for the stream registry, sessionRouter (subscriptions/progress/logging + reap), the keyed mutex, and the dispatcher routing table.
• go test -race ./pkg/transport/proxy/streamable/... -count=5 — green, incl. concurrent dispatch+evict and concurrent-registry stress tests (no panics/races).
• Linting (task lint-fix) — 0 issues.
• Security regression tests: progress does not leak to a non-originating session (two sessions reusing the same client token); resources/updated reaches subscribers only; upstream subscribe/unsubscribe ref-counted once; logging dropped + upstream level = cross-session max; sampling/elicitation never reach a client and error to the backend; authz-denied subscribe never enters the routing table; concurrent same-URI subscribe/unsubscribe ordered (mutation-verified — the assertion fails without the fix); lifecycle (handleDelete purge, reaper, request-scoped progress cleanup).

Does this introduce a user-facing change?

Yes. Clients connected over the Streamable HTTP transport now receive server-initiated notifications (progress on their request stream, resource-update notifications for their subscriptions, and capability list_changed), which were previously dropped. GET /mcp now opens an SSE stream by default instead of returning 405. Sampling/elicitation and per-session logging remain unavailable on the shared-backend thv run proxy (they require a per-session/vMCP deployment) and return a clean error rather than being mis-delivered.

Special notes for reviewers

• Developed via an architect→implement→panel pipeline with Opus review panels (security + MCP-spec + Go-concurrency), iterated twice. The panel initially found two blockers — a send-on-closed-channel panic and a spec MUST-NOT (broadcast to all streams) — both fixed; then a subscribe/unsubscribe ordering race, fixed with the per-URI keyed mutex. Final Opus passes confirmed: cross-session leakage eliminated on every path, MCP 2025-11-25 conformant, and the keyed mutex correct/deadlock-free/leak-free.
• Honest architectural boundary: over a single shared backend the proxy cannot attribute server-initiated requests (sampling/elicitation) or log lines to a downstream session — proven in the design, not assumed. Correct support needs per-session backend connections (the vMCP model). This PR refuses them securely and documents the follow-up rather than mis-delivering.
• Large but cohesive (mostly tests + docs; core is dispatcher_routing.go, routing in dispatcher.go, and the POST-SSE interleaving in streamable_proxy.go). Requested as a single complete change. docs/arch/03-transport-architecture.md updated.
• Follow-ups (documented): SSE resumability (Last-Event-ID; a spec MAY), sampling/elicitation + per-session logging via per-session backends, and task-augmented progress after CreateTaskResult.

Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 73.66771% with 168 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.79%. Comparing base (3dee7d6) to head (690aafb).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/transport/proxy/streamable/streamable_proxy.go	60.79%	93 Missing and 25 partials ⚠️
pkg/transport/proxy/streamable/dispatcher.go	65.06%	22 Missing and 7 partials ⚠️
pkg/transport/proxy/streamable/utils.go	66.00%	11 Missing and 6 partials ⚠️
...g/transport/proxy/streamable/dispatcher_streams.go	94.59%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5934      +/-   ##
==========================================
+ Coverage   71.77%   71.79%   +0.02%     
==========================================
  Files         702      708       +6     
  Lines       71901    72734     +833     
==========================================
+ Hits        51608    52222     +614     
- Misses      16593    16775     +182     
- Partials     3700     3737      +37     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[amirejaz]

Read closely through the server->client routing and session lifecycle since that's the delicate part here. The overall design holds up well under concurrency - the never-close-data/close-stop-once pattern, the keyed mutex ref-counting, and the per-request progress-token UUID isolation all look correct. A few things stood out around how subscription state and streams are handled on failure and teardown paths; left them inline. The subscribe-rollback and GET-stream-teardown ones look like real bugs to me, the rest are more design questions / suggestions.