Flip Stateless default to true and obsolete stateful Streamable HTTP options (MCP9005)

Default `HttpServerTransportOptions.Stateless` to true so new code on the 2026-07-28
draft revision (SEP-2567) is sessionless from the start. Mark the surface that only
makes sense in the legacy stateful HTTP mode as obsolete behind the new MCP9005
diagnostic so callers see a deprecation hint but can still pin Stateless = false
to keep using session-based behaviors during back-compat:

* `HttpServerTransportOptions.EventStreamStore` (resumability)
* `HttpServerTransportOptions.SessionMigrationHandler` (multi-node migration)
* `HttpServerTransportOptions.PerSessionExecutionContext`
* `HttpServerTransportOptions.IdleTimeout`
* `HttpServerTransportOptions.MaxIdleSessionCount`

Internal infrastructure that legitimately reads those options for the back-compat
stateful path now suppresses MCP9005 at the use site. Test projects suppress it
globally via NoWarn because the suite intentionally exercises both modes.

Update tests/samples that previously relied on the implicit `Stateless = false`
default to set it explicitly:

* TestSseServer.Program — SSE always needs stateful state shared across GET/POST.
* ConformanceServer.Program — resumability + OAuth conformance scenarios are stateful.
* ResumabilityIntegrationTestsBase — resumability is a stateful concern.
* SseIntegrationTests / MapMcpSseTests — SSE requires stateful.
* OAuthTestBase — OAuth flow uses the GET /sse session-based endpoint.
* MrtrProtocolTests / SessionMigrationTests / StreamableHttpServerConformanceTests —
  these tests intentionally drive the legacy stateful session machinery.
* DraftHttpHandlerTests — tests draft rejection of GET/DELETE endpoints, which are
  only mapped when Stateless = false.

Rework HTTP header conformance helpers (HttpHeaderConformanceTests +
StreamableHttpServerConformanceTests) to stop asserting an mcp-session-id response
header from draft/non-draft initialize, because the sessionless default means none
is returned.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: halter73

src/Common/Obsoletions.cs

@@ -33,4 +33,8 @@ internal static class Obsoletions
     public const string EnableLegacySse_DiagnosticId = "MCP9004";
     public const string EnableLegacySse_Message = "Legacy SSE transport has no built-in request backpressure and should only be used with completely trusted clients in isolated processes. Use Streamable HTTP instead.";
     public const string EnableLegacySse_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#obsolete-apis";
+
+    public const string LegacyStatefulHttp_DiagnosticId = "MCP9005";
+    public const string LegacyStatefulHttp_Message = "Stateful Streamable HTTP mode is a back-compat-only escape hatch for legacy clients. Set HttpServerTransportOptions.Stateless = true (the default as of the 2026-07-28 protocol revision) for new code. See SEP-2567.";
+    public const string LegacyStatefulHttp_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#obsolete-apis";
 }

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

@@ -50,16 +50,23 @@ public class HttpServerTransportOptions
     /// allowing for load balancing without session affinity.
     /// </summary>
     /// <value>
-    /// <see langword="true"/> if the server runs in a stateless mode; <see langword="false"/> if the server tracks state between requests. The default is <see langword="false"/>.
+    /// <see langword="true"/> if the server runs in a stateless mode; <see langword="false"/> if the server tracks state between requests.
+    /// The default is <see langword="true"/> as of the <c>2026-07-28</c> draft protocol revision (SEP-2567);
+    /// set to <see langword="false"/> only when you need to support legacy clients that rely on session affinity.
     /// </value>
     /// <remarks>
     /// If <see langword="true"/>, <see cref="McpSession.SessionId"/> will be null, and the "MCP-Session-Id" header will not be used,
     /// the <see cref="RunSessionHandler"/> will be called once for each request, and the "/sse" endpoint will be disabled.
     /// Unsolicited server-to-client messages and all server-to-client requests are also unsupported, because any responses
     /// might arrive at another ASP.NET Core application process.
     /// Client sampling, elicitation, and roots capabilities are also disabled in stateless mode, because the server cannot make requests.
+    /// <para>
+    /// Requests that declare the <c>2026-07-28</c> draft protocol revision via the <c>MCP-Protocol-Version</c> header
+    /// are always routed through the stateless path regardless of this property's value, because that revision
+    /// removes <c>Mcp-Session-Id</c> entirely (SEP-2567).
+    /// </para>
     /// </remarks>
-    public bool Stateless { get; set; }
+    public bool Stateless { get; set; } = true;
 
     /// <summary>
     /// Gets or sets a value that indicates whether the server maps legacy SSE endpoints (<c>/sse</c> and <c>/message</c>)
@@ -112,6 +119,7 @@ public class HttpServerTransportOptions
     /// If this property is not set, the server will attempt to resolve an <see cref="ISseEventStreamStore"/> from DI.
     /// </para>
     /// </remarks>
+    [Obsolete(Obsoletions.LegacyStatefulHttp_Message, DiagnosticId = Obsoletions.LegacyStatefulHttp_DiagnosticId, UrlFormat = Obsoletions.LegacyStatefulHttp_Url)]
     public ISseEventStreamStore? EventStreamStore { get; set; }
 
     /// <summary>
@@ -128,6 +136,7 @@ public class HttpServerTransportOptions
     /// If this property is not set, the server will attempt to resolve an <see cref="ISessionMigrationHandler"/> from DI.
     /// </para>
     /// </remarks>
+    [Obsolete(Obsoletions.LegacyStatefulHttp_Message, DiagnosticId = Obsoletions.LegacyStatefulHttp_DiagnosticId, UrlFormat = Obsoletions.LegacyStatefulHttp_Url)]
     public ISessionMigrationHandler? SessionMigrationHandler { get; set; }
 
     /// <summary>
@@ -144,6 +153,7 @@ public class HttpServerTransportOptions
     /// Enabling a per-session <see cref="ExecutionContext"/> can be useful for setting <see cref="AsyncLocal{T}"/> variables
     /// that persist for the entire session, but it prevents you from using IHttpContextAccessor in handlers.
     /// </remarks>
+    [Obsolete(Obsoletions.LegacyStatefulHttp_Message, DiagnosticId = Obsoletions.LegacyStatefulHttp_DiagnosticId, UrlFormat = Obsoletions.LegacyStatefulHttp_Url)]
     public bool PerSessionExecutionContext { get; set; }
 
     /// <summary>
@@ -162,6 +172,7 @@ public class HttpServerTransportOptions
     /// tied to the open GET <c>/sse</c> request, and they are removed immediately when the client disconnects.
     /// </para>
     /// </remarks>
+    [Obsolete(Obsoletions.LegacyStatefulHttp_Message, DiagnosticId = Obsoletions.LegacyStatefulHttp_DiagnosticId, UrlFormat = Obsoletions.LegacyStatefulHttp_Url)]
     public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromHours(2);
 
     /// <summary>
@@ -182,6 +193,7 @@ public class HttpServerTransportOptions
     /// exactly as long as the SSE connection is open.
     /// </para>
     /// </remarks>
+    [Obsolete(Obsoletions.LegacyStatefulHttp_Message, DiagnosticId = Obsoletions.LegacyStatefulHttp_DiagnosticId, UrlFormat = Obsoletions.LegacyStatefulHttp_Url)]
     public int MaxIdleSessionCount { get; set; } = 10_000;
 
     /// <summary>

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptionsSetup.cs

@@ -12,7 +12,9 @@ internal sealed class HttpServerTransportOptionsSetup(IServiceProvider servicePr
 {
     public void Configure(HttpServerTransportOptions options)
     {
+#pragma warning disable MCP9005 // Stateful Streamable HTTP options are obsolete but still wired up internally.
         options.EventStreamStore ??= serviceProvider.GetService<ISseEventStreamStore>();
         options.SessionMigrationHandler ??= serviceProvider.GetService<ISessionMigrationHandler>();
+#pragma warning restore MCP9005
     }
 }

src/ModelContextProtocol.AspNetCore/IdleTrackingBackgroundService.cs

@@ -18,12 +18,14 @@ public IdleTrackingBackgroundService(
         ILogger<IdleTrackingBackgroundService> logger)
     {
         // Still run loop given infinite IdleTimeout to enforce the MaxIdleSessionCount and assist graceful shutdown.
+#pragma warning disable MCP9005 // Stateful Streamable HTTP options are obsolete but still wired up internally.
         if (options.Value.IdleTimeout != Timeout.InfiniteTimeSpan)
         {
             ArgumentOutOfRangeException.ThrowIfLessThan(options.Value.IdleTimeout, TimeSpan.Zero);
         }
 
         ArgumentOutOfRangeException.ThrowIfLessThan(options.Value.MaxIdleSessionCount, 0);
+#pragma warning restore MCP9005
 
         _sessions = sessions;
         _options = options;

src/ModelContextProtocol.AspNetCore/StatefulSessionManager.cs

@@ -17,9 +17,11 @@ internal sealed partial class StatefulSessionManager(
     private readonly ConcurrentDictionary<string, StreamableHttpSession> _sessions = new(StringComparer.Ordinal);
 
     private readonly TimeProvider _timeProvider = httpServerTransportOptions.Value.TimeProvider;
+#pragma warning disable MCP9005 // Stateful Streamable HTTP options are obsolete but still wired up internally.
     private readonly TimeSpan _idleTimeout = httpServerTransportOptions.Value.IdleTimeout;
     private readonly long _idleTimeoutTicks = GetIdleTimeoutInTimestampTicks(httpServerTransportOptions.Value.IdleTimeout, httpServerTransportOptions.Value.TimeProvider);
     private readonly int _maxIdleSessionCount = httpServerTransportOptions.Value.MaxIdleSessionCount;
+#pragma warning restore MCP9005
 
     private readonly object _idlePruningLock = new();
     private readonly List<long> _idleTimestamps = [];

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -307,10 +307,12 @@ await WriteJsonRpcErrorAsync(context,
 
     private async ValueTask<StreamableHttpSession?> TryMigrateSessionAsync(HttpContext context, string sessionId)
     {
+#pragma warning disable MCP9005 // Stateful Streamable HTTP options are obsolete but still wired up internally.
         if (HttpServerTransportOptions.SessionMigrationHandler is not { } handler)
         {
             return null;
         }
+#pragma warning restore MCP9005
 
         var migrationLock = _migrationLocks.GetOrAdd(sessionId, static _ => new SemaphoreSlim(1, 1));
         await migrationLock.WaitAsync(context.RequestAborted);
@@ -414,6 +416,7 @@ private async ValueTask<StreamableHttpSession> StartNewSessionAsync(HttpContext
         if (!isStateless)
         {
             sessionId = MakeNewSessionId();
+#pragma warning disable MCP9005 // Stateful Streamable HTTP options are obsolete but still wired up internally.
             transport = new(loggerFactory)
             {
                 SessionId = sessionId,
@@ -423,6 +426,7 @@ private async ValueTask<StreamableHttpSession> StartNewSessionAsync(HttpContext
                     ? (initParams, ct) => handler.OnSessionInitializedAsync(context, sessionId, initParams, ct)
                     : null,
             };
+#pragma warning restore MCP9005
 
             context.Response.Headers[McpSessionIdHeaderName] = sessionId;
         }
@@ -493,8 +497,10 @@ private async ValueTask<StreamableHttpSession> MigrateSessionAsync(
         var transport = new StreamableHttpServerTransport(loggerFactory)
         {
             SessionId = sessionId,
+#pragma warning disable MCP9005 // Stateful Streamable HTTP options are obsolete but still wired up internally.
             FlowExecutionContextFromRequests = !HttpServerTransportOptions.PerSessionExecutionContext,
             EventStreamStore = HttpServerTransportOptions.EventStreamStore,
+#pragma warning restore MCP9005
         };
 
         // Initialize the transport with the migrated session's init params.
@@ -511,7 +517,9 @@ private async ValueTask<StreamableHttpSession> MigrateSessionAsync(
 
     private async ValueTask<ISseEventStreamReader?> GetEventStreamReaderAsync(HttpContext context, string lastEventId)
     {
+#pragma warning disable MCP9005 // Stateful Streamable HTTP options are obsolete but still wired up internally.
         if (HttpServerTransportOptions.EventStreamStore is not { } eventStreamStore)
+#pragma warning restore MCP9005
         {
             await WriteJsonRpcErrorAsync(context,
                 "Bad Request: This server does not support resuming streams.",

tests/ModelContextProtocol.AspNetCore.Tests/DraftHttpHandlerTests.cs

@@ -24,7 +24,12 @@ private async Task StartAsync()
         Builder.Services.AddMcpServer(options =>
         {
             options.ServerInfo = new Implementation { Name = nameof(DraftHttpHandlerTests), Version = "1" };
-        }).WithHttpTransport();
+        }).WithHttpTransport(options =>
+        {
+            // Map the GET/DELETE endpoints so we can exercise the draft-mode rejection paths
+            // (these endpoints are not registered in stateless mode, which is the new default).
+            options.Stateless = false;
+        });
 
         _app = Builder.Build();
         _app.MapMcp();

tests/ModelContextProtocol.AspNetCore.Tests/HttpHeaderConformanceTests.cs

@@ -437,9 +437,9 @@ private async Task InitializeWithDraftVersionAsync()
         using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken);
         Assert.Equal(HttpStatusCode.OK, response.StatusCode);
 
-        var sessionId = Assert.Single(response.Headers.GetValues("mcp-session-id"));
-        HttpClient.DefaultRequestHeaders.Remove("mcp-session-id");
-        HttpClient.DefaultRequestHeaders.Add("mcp-session-id", sessionId);
+        // Draft protocol revision (SEP-2567) is sessionless: the server does not return a
+        // mcp-session-id header. Subsequent requests carry MCP-Protocol-Version=2026-07-28
+        // to route through the sessionless path.
     }
 
     private async Task InitializeWithNonDraftVersionAsync()
@@ -449,9 +449,8 @@ private async Task InitializeWithNonDraftVersionAsync()
         using var response = await HttpClient.PostAsync("", JsonContent(InitializeRequest), TestContext.Current.CancellationToken);
         Assert.Equal(HttpStatusCode.OK, response.StatusCode);
 
-        var sessionId = Assert.Single(response.Headers.GetValues("mcp-session-id"));
-        HttpClient.DefaultRequestHeaders.Remove("mcp-session-id");
-        HttpClient.DefaultRequestHeaders.Add("mcp-session-id", sessionId);
+        // Server is stateless by default (SEP-2567), so initializing with the non-draft protocol does not return
+        // a mcp-session-id header. Subsequent requests are independent, just like the draft path.
     }
 
     private static StringContent JsonContent(string json) => new(json, Encoding.UTF8, "application/json");

tests/ModelContextProtocol.AspNetCore.Tests/MapMcpSseTests.cs

@@ -1,4 +1,4 @@
-using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Builder;
 using Microsoft.Extensions.DependencyInjection;
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
@@ -21,7 +21,7 @@ protected override void ConfigureStateless(HttpServerTransportOptions options)
     [InlineData("/mcp/secondary")]
     public async Task Allows_Customizing_Route(string pattern)
     {
-        Builder.Services.AddMcpServer().WithHttpTransport(options => options.EnableLegacySse = true);
+        Builder.Services.AddMcpServer().WithHttpTransport(options => { options.EnableLegacySse = true; options.Stateless = false; });
         await using var app = Builder.Build();
 
         app.MapMcp(pattern);
@@ -53,7 +53,7 @@ public async Task CanConnect_WithMcpClient_AfterCustomizingRoute(string routePat
                 Name = "TestCustomRouteServer",
                 Version = "1.0.0",
             };
-        }).WithHttpTransport(options => options.EnableLegacySse = true);
+        }).WithHttpTransport(options => { options.EnableLegacySse = true; options.Stateless = false; });
         await using var app = Builder.Build();
 
         app.MapMcp(routePattern);
@@ -83,7 +83,7 @@ public async Task EnablePollingAsync_ThrowsInvalidOperationException_InSseMode()
             return "Complete";
         }, options: new() { Name = "polling_tool" });
 
-        Builder.Services.AddMcpServer().WithHttpTransport(options => options.EnableLegacySse = true).WithTools([pollingTool]);
+        Builder.Services.AddMcpServer().WithHttpTransport(options => { options.EnableLegacySse = true; options.Stateless = false; }).WithTools([pollingTool]);
 
         await using var app = Builder.Build();
         app.MapMcp();

tests/ModelContextProtocol.AspNetCore.Tests/ModelContextProtocol.AspNetCore.Tests.csproj

@@ -7,6 +7,8 @@
     <IsPackable>false</IsPackable>
     <IsTestProject>true</IsTestProject>
     <RootNamespace>ModelContextProtocol.AspNetCore.Tests</RootNamespace>
+    <!-- The test suite intentionally exercises the obsoleted stateful Streamable HTTP surface. -->
+    <NoWarn>$(NoWarn);MCP9005</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(TargetFramework)' == 'net9.0'">