Explicitly set Stateless in all WithHttpTransport calls

halter73 · Copilot · halter73 · commit 7e703f3efb67 · 2026-03-26T10:08:46.000-07:00
Every WithHttpTransport() call in samples and docs now explicitly sets
Stateless = true or Stateless = false. This prepares for a potential
future default change and makes the intent clear in code users may copy.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs/concepts/completions/completions.md b/docs/concepts/completions/completions.md
@@ -26,7 +26,7 @@ Register a completion handler when building the server. The handler receives a r
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithPrompts<MyPrompts>()
     .WithResources<MyResources>()
     .WithCompleteHandler(async (ctx, ct) =>
diff --git a/docs/concepts/elicitation/samples/server/Program.cs b/docs/concepts/elicitation/samples/server/Program.cs
@@ -6,8 +6,11 @@
 
 builder.Services.AddMcpServer()
     .WithHttpTransport(options =>
-        options.IdleTimeout = Timeout.InfiniteTimeSpan // Never timeout
-    )
+    {
+        // Elicitation requires stateful mode because it sends server-to-client requests.
+        // Set Stateless = false explicitly for forward compatibility in case the default changes.
+        options.Stateless = false;
+    })
     .WithTools<InteractiveTools>();
 
 builder.Logging.AddConsole(options =>
diff --git a/docs/concepts/filters.md b/docs/concepts/filters.md
@@ -401,7 +401,7 @@ To enable authorization support, call `AddAuthorizationFilters()` when configuri
 
 ```csharp
 services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .AddAuthorizationFilters() // Enable authorization filter support
     .WithTools<WeatherTools>();
 ```
@@ -501,7 +501,7 @@ This allows you to implement logging, metrics, or other cross-cutting concerns t
 
 ```csharp
 services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithRequestFilters(requestFilters =>
     {
         requestFilters.AddListToolsFilter(next => async (context, cancellationToken) =>
diff --git a/docs/concepts/logging/samples/server/Program.cs b/docs/concepts/logging/samples/server/Program.cs
@@ -6,8 +6,11 @@
 
 builder.Services.AddMcpServer()
     .WithHttpTransport(options =>
-        options.IdleTimeout = Timeout.InfiniteTimeSpan // Never timeout
-    )
+    {
+        // Log streaming requires stateful mode because the server pushes log notifications
+        // to clients. Set Stateless = false explicitly for forward compatibility.
+        options.Stateless = false;
+    })
     .WithTools<LoggingTools>();
     // .WithSetLoggingLevelHandler(async (ctx, ct) => new EmptyResult());
 
diff --git a/docs/concepts/pagination/pagination.md b/docs/concepts/pagination/pagination.md
@@ -70,7 +70,7 @@ When implementing custom list handlers on the server, pagination is supported by
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithListResourcesHandler(async (ctx, ct) =>
     {
         const int pageSize = 10;
diff --git a/docs/concepts/prompts/prompts.md b/docs/concepts/prompts/prompts.md
@@ -63,7 +63,7 @@ Register prompt types when building the server:
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithPrompts<MyPrompts>()
     .WithPrompts<CodePrompts>();
 ```
diff --git a/docs/concepts/resources/resources.md b/docs/concepts/resources/resources.md
@@ -74,7 +74,7 @@ Register resource types when building the server:
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithResources<MyResources>()
     .WithResources<DocumentResources>();
 ```
@@ -208,7 +208,9 @@ Register subscription handlers when building the server:
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    // Subscriptions require stateful mode because the server pushes change notifications
+    // to clients. Set Stateless = false explicitly for forward compatibility.
+    .WithHttpTransport(o => o.Stateless = false)
     .WithResources<MyResources>()
     .WithSubscribeToResourcesHandler(async (ctx, ct) =>
     {
diff --git a/docs/concepts/sessions/sessions.md b/docs/concepts/sessions/sessions.md
@@ -303,6 +303,8 @@ For high-availability deployments, <xref:ModelContextProtocol.AspNetCore.ISessio
 builder.Services.AddMcpServer()
     .WithHttpTransport(options =>
     {
+        // Session migration is a stateful-mode feature.
+        options.Stateless = false;
         options.SessionMigrationHandler = new MySessionMigrationHandler();
     });
 ```
@@ -329,6 +331,8 @@ The server can store SSE events for replay when clients reconnect using the `Las
 builder.Services.AddMcpServer()
     .WithHttpTransport(options =>
     {
+        // Session resumability is a stateful-mode feature.
+        options.Stateless = false;
         options.EventStreamStore = new MyEventStreamStore();
     });
 ```
diff --git a/docs/concepts/tasks/tasks.md b/docs/concepts/tasks/tasks.md
@@ -64,7 +64,7 @@ builder.Services.AddMcpServer(options =>
     // Enable tasks by providing a task store
     options.TaskStore = taskStore;
 })
-.WithHttpTransport()
+.WithHttpTransport(o => o.Stateless = true)
 .WithTools<MyTools>();
 ```
 
@@ -566,7 +566,7 @@ builder.Services.AddMcpServer(options =>
 {
     options.TaskStore = taskStore;
 })
-.WithHttpTransport()
+.WithHttpTransport(o => o.Stateless = true)
 .WithTools<TaskTools>();
 ```
 
diff --git a/docs/concepts/tools/tools.md b/docs/concepts/tools/tools.md
@@ -39,7 +39,7 @@ Register the tool type when building the server:
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithTools<MyTools>();
 ```
 
diff --git a/docs/concepts/transports/transports.md b/docs/concepts/transports/transports.md
@@ -184,7 +184,7 @@ The ASP.NET Core integration supports SSE transport alongside Streamable HTTP. T
 var builder = WebApplication.CreateBuilder(args);
 
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithTools<MyTools>();
 
 var app = builder.Build();
diff --git a/samples/AspNetCoreMcpPerSessionTools/Program.cs b/samples/AspNetCoreMcpPerSessionTools/Program.cs
@@ -13,6 +13,10 @@
 builder.Services.AddMcpServer()
     .WithHttpTransport(options =>
     {
+        // This sample demonstrates per-session tool filtering, which requires stateful mode.
+        // Set Stateless = false explicitly for forward compatibility in case the default changes.
+        options.Stateless = false;
+
         // Configure per-session options to filter tools based on route category
         options.ConfigureSessionOptions = async (httpContext, mcpOptions, cancellationToken) =>
         {
diff --git a/samples/AspNetCoreMcpPerSessionTools/README.md b/samples/AspNetCoreMcpPerSessionTools/README.md
@@ -65,6 +65,9 @@ The key technique is using `ConfigureSessionOptions` to modify the tool collecti
 ```csharp
 .WithHttpTransport(options =>
 {
+    // Per-session tool filtering requires stateful mode. Set Stateless = false
+    // explicitly for forward compatibility in case the default changes.
+    options.Stateless = false;
     options.ConfigureSessionOptions = async (httpContext, mcpOptions, cancellationToken) =>
     {
         var toolCategory = GetToolCategoryFromRoute(httpContext);
diff --git a/samples/AspNetCoreMcpServer/Program.cs b/samples/AspNetCoreMcpServer/Program.cs
@@ -7,11 +7,11 @@
 
 var builder = WebApplication.CreateBuilder(args);
 // Note: This sample uses SampleLlmTool which calls server.AsSamplingChatClient() to send
-// a server-to-client sampling request. This requires stateful (session-based) mode, which
-// is the default. See https://csharp.sdk.modelcontextprotocol.io/concepts/sessions for details
-// on when to prefer stateless mode instead.
+// a server-to-client sampling request. This requires stateful (session-based) mode. Set
+// Stateless = false explicitly for forward compatibility in case the default changes.
+// See https://csharp.sdk.modelcontextprotocol.io/concepts/sessions/sessions.html for details.
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = false)
     .WithTools<EchoTool>()
     .WithTools<SampleLlmTool>()
     .WithTools<WeatherTools>()
diff --git a/samples/EverythingServer/Program.cs b/samples/EverythingServer/Program.cs
@@ -57,6 +57,10 @@
     })
     .WithHttpTransport(options =>
     {
+        // This sample uses subscriptions, SampleLlmTool (sampling), and RunSessionHandler.
+        // Set Stateless = false explicitly for forward compatibility in case the default changes.
+        options.Stateless = false;
+
         // Add a RunSessionHandler to remove all subscriptions for the session when it ends
 #pragma warning disable MCPEXP002 // RunSessionHandler is experimental
         options.RunSessionHandler = async (httpContext, mcpServer, token) =>
diff --git a/samples/LongRunningTasks/Program.cs b/samples/LongRunningTasks/Program.cs
@@ -26,7 +26,7 @@
         Version = "1.0.0"
     };
 })
-.WithHttpTransport()
+.WithHttpTransport(o => o.Stateless = true)
 .WithTools<TaskTools>();
 
 var app = builder.Build();

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@ When implementing custom list handlers on the server, pagination is supported by`
`70`	`70`
`71`	`71`	```csharp
`72`	`72`	`builder.Services.AddMcpServer()`
`73`		`- .WithHttpTransport()`
	`73`	`+ .WithHttpTransport(o => o.Stateless = true)`
`74`	`74`	`.WithListResourcesHandler(async (ctx, ct) =>`
`75`	`75`	`{`
`76`	`76`	`const int pageSize = 10;`