Add HttpServerSessionMode for hybrid stateful/stateless HTTP serving - #1796

Closes #1777.

Implements the design @halter73 described, finishing the work from the draft in saicharanpardhu#1.

Problem

Starting with 2026-07-28, Streamable HTTP has no sessions (SEP-2567 removed Mcp-Session-Id, SEP-2575 removed the initialize handshake). Today an ASP.NET Core server must pick one era for the whole endpoint:

• Stateless = true — no sessions for anyone, so legacy clients lose unsolicited notifications, resource subscriptions, and server-to-client requests.
• Stateless = false — 2026-07-28 requests are refused with -32022 UnsupportedProtocolVersion to force a downgrade, so servers can't adopt the new revision until every client has migrated (or is willing to downgrade).

Change

New three-value HttpServerSessionMode on HttpServerTransportOptions:

builder.Services.AddMcpServer()
    .WithHttpTransport(options =>
    {
        options.SessionMode = HttpServerSessionMode.StatefulForInitializeClients;
    });

In hybrid mode the effective mode is decided per request, so lifetimes follow the request rather than the endpoint:

• 2026-07-28 requests resolve from HttpContext.RequestServices with request scoping disabled; ConfigureSessionOptions and RunSessionHandler run per request.
• initialize-handshake sessions resolve from the application provider with per-request scoping; ConfigureSessionOptions and RunSessionHandler run once per session.
• GET/DELETE stay mapped, legacy SSE stays permitted, and idle tracking keeps running — but only legacy sessions can use them; 2026-07-28 GET/DELETE get 405.

Stateless remains a convenience proxy

bool Stateless remains the convenient way to select the two most common modes, while SessionMode exposes the hybrid value:

• Stateless = true → SessionMode = Stateless; Stateless = false → SessionMode = Stateful
• reading Stateless returns true only for SessionMode == Stateless (hybrid reads as false)
• assigning both does not throw — they're the same underlying value, so the last assignment wins

Internal call sites, samples, docs samples, and tests use SessionMode explicitly so their intended behavior is clear; existing applications can continue using the bool without an obsolete warning.

Tests

July2026ProtocolHybridSessionModeTests covers the pre-merge checklist from the issue:

HttpServerTransportOptionsTests covers the Stateless ↔ SessionMode proxy semantics, including that assigning both doesn't throw and the last assignment wins.

Docs

• docs/concepts/stateless/stateless.md — new "Hybrid mode (sessions for initialize clients only)" section, SessionMode in the property reference, and all samples/prose migrated.
• docs/concepts/mrtr/mrtr.md, elicitation.md, sampling.md, roots.md — updated the statements that a stateful HTTP endpoint always refuses 2026-07-28; hybrid mode serves it statelessly (so those clients use MRTR while legacy sessions keep the initialize-era flows).
• docs/list-of-diagnostics.md — rewords MCP9006 for per-request hybrid behavior.
• Complete ASP.NET Core snippets import ModelContextProtocol.AspNetCore, and references to “both session modes” now distinguish the three SessionMode configurations from the two effective request behaviors.

Validation

• dotnet build — 0 warnings, 0 errors
• dotnet test — all targets pass:
  • Analyzers: 57 passed
  • ASP.NET Core: 610 passed, 30 skipped on each of .NET 8, .NET 9, and .NET 10
  • Core: 2355 passed, 6 skipped on each of .NET 8, .NET 9, and .NET 10; 2054 passed, 282 skipped on .NET Framework 4.7.2