Add HttpServerSessionMode for hybrid stateful/stateless HTTP serving

[saicharanpardhu]

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;
    });

Mode	initialize clients (2025-11-25 and earlier)	2026-07-28 and later clients
Stateless (default)	Served statelessly	Served statelessly
Stateful	Full session	Refused with -32022 so dual-path clients downgrade
StatefulForInitializeClients	Full session	Served statelessly on the same endpoint

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:

Test	Verifies
ModernAndLegacyClients_ShareOneEndpoint_AndModernDoesNotDowngrade	Both eras work against one app instance; the default modern client negotiates 2026-07-28 instead of downgrading
LegacyClient_OnHybridServer_StillSupportsServerToClientElicitation	Legacy sessions keep server-to-client requests
ModernRequests_UseRequestScopedServices_WhileLegacySessionsUseApplicationServices	Modern requests use stateless DI lifetimes; legacy sessions stay stateful
ConfigureSessionOptions_RunsPerRequestForModernClients_AndOncePerSessionForLegacyClients	ConfigureSessionOptions lifetimes match the per-request mode
RunSessionHandler_RunsPerRequestForModernClients_AndOncePerSessionForLegacyClients	RunSessionHandler follows the same per-request vs. per-session lifetime
ModernPost_DoesNotMintSessionId_WhileLegacyInitializeDoes	No session ID for 2026-07-28
ModernPost_IgnoresMcpSessionIdHeader	A stray Mcp-Session-Id doesn't attach a modern request to a session
LegacyGetAndDelete_RemainAvailable_WhileModernGetAndDeleteReturn405	Legacy GET/DELETE still work while modern ones return 405

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

Note

This pull request description and the accompanying changes were drafted with GitHub Copilot.

[jeffhandley]

The feature design and implementation are excellent, @saicharanpardhu!

Most of my comments are about cleaning up some wording in code comments, API doc comments, conceptual documentation and samples. I also have some requests for changes in the tests to revert test changes that aren't required and augmenting coverage a little bit.

[jeffhandley]

Thanks, @saicharanpardhu. Great work!