MCP C# SDK Hybrid Sessions: Serve Old and New Clients on One Endpoint

MCP C# SDK hybrid sessions allow both legacy and modern clients to use a single ASP.NET Core endpoint without forcing modern clients to downgrade or stripping features from legacy clients. The stable C# SDK 2.2.0 introduced the HttpServerSessionMode.StatefulForInitializeClients option to enable this hybrid stateful/stateless serving.

The MCP revision from 2026-07-28 removed the initialize handshake and Mcp-Session-Id from the wire format, making clients self-describing. This change made the core stateless, but existing servers needed to handle both old and new clients. With HttpServerSessionMode.Stateful, legacy-era clients receive full sessions, while modern requests are refused to encourage a dual-path for clients to fall back to the older handshake.

Stateless mode makes every request independent, which is the default for servers that don't need session state or older server-to-client flows.

To configure MCP C# SDK hybrid sessions, use the builder with Services.AddMcpServer().WithHttpTransport(options => { options.SessionMode = HttpServerSessionMode.StatefulForInitializeClients; }).WithTools(); Then map the endpoint with app.MapMcp("/mcp");

Legacy-era clients send an initialize request with protocolVersion: 2025-11-25, receiving a Mcp-Session-Id for later requests. Modern clients send server/discover or other operations with their metadata. They don't receive a session ID.

The test server configuration uses Microsoft.AspNetCore.TestHost to verify both protocol versions without running the model. It checks that a modern discovery succeeds without a Mcp-Session-Id, a modern echo tool call remains stateless, a legacy initialize succeeds and sets a non-empty session ID, and a legacy notification or tool call reuses that session.

A modern DELETE returns 405 Method Not Allowed, while a legacy DELETE closes its session successfully. The key assertion is that each side gets the correct session semantics.

The hybrid mode is a bridge, not a universal default. If all clients speak 2026-07-28 and the server needs no session-only behavior, choose Stateless for simplicity and better scaling. Hybrid mode doesn't support unsolicited notifications or resource subscriptions and lacks per-client isolation. Moreover, it retains the operational costs of sessions on the server, such as memory usage and potential affinity issues across multiple instances.

Authentication and authorization are separate concerns; a session ID doesn't prove identity. Keep this regression test until the last initialize-era client is retired, then change the server and test together to the explicit stateless mode.