Address PR feedback

- Don't store client capabilities in stateless session ID since sampling and roots cannot be supported in stateless mode
- Immediate throw for unsupported operations in stateless mode
- Improve HttpTransportOptions doc comments

Author: halter73

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

@@ -24,25 +24,36 @@ public class HttpServerTransportOptions
 
     /// <summary>
     /// Gets or sets whether the server should run in a stateless mode that does not require all requests for a given session
-    /// to arrive to the same ASP.NET Core application process. If true, the /sse endpoint will be disabled, and
-    /// client capabilities will be round-tripped as part of the mcp-session-id header instead of stored in memory. Defaults to false.
+    /// to arrive to the same ASP.NET Core application process.
     /// </summary>
+    /// <remarks>
+    /// If <see langword="true"/>, the "/sse" endpoint will be disabled, and client information will be round-tripped as part
+    /// of the "mcp-session-id" header instead of stored in memory. Unsolicited server-to-client messages and all server-to-client
+    /// requests are also unsupported, because any responses may arrive at another ASP.NET Core application process.
+    /// Client sampling and roots capabilities are also disabled in stateless mode, because the server cannot make requests.
+    /// Defaults to <see langword="false"/>.
+    /// </remarks>
     public bool Stateless { get; set; }
 
     /// <summary>
-    /// Represents the duration of time the server will wait between any active requests before timing out an
-    /// MCP session. This is checked in background every 5 seconds. A client trying to resume a session will
-    /// receive a 404 status code and should restart their session. A client can keep their session open by
-    /// keeping a GET request open. The default value is set to 2 hours.
+    /// Gets or sets the duration of time the server will wait between any active requests before timing out an MCP session.
     /// </summary>
+    /// <remarks>
+    /// This is checked in background every 5 seconds. A client trying to resume a session will receive a 404 status code
+    /// and should restart their session. A client can keep their session open by keeping a GET request open.
+    /// Defaults to 2 hours.
+    /// </remarks>
     public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromHours(2);
 
     /// <summary>
-    /// The maximum number of idle sessions to track. This is used to limit the number of sessions that can be idle at once.
+    /// Gets or sets maximum number of idle sessions to track in memory. This is used to limit the number of sessions that can be idle at once.
+    /// </summary>
+    /// <remarks>
     /// Past this limit, the server will log a critical error and terminate the oldest idle sessions even if they have not reached
     /// their <see cref="IdleTimeout"/> until the idle session count is below this limit. Clients that keep their session open by
-    /// keeping a GET request open will not count towards this limit. The default value is set to 100,000 sessions.
-    /// </summary>
+    /// keeping a GET request open will not count towards this limit.
+    /// Defaults to 100,000 sessions.
+    /// </remarks>
     public int MaxIdleSessionCount { get; set; } = 100_000;
 
     /// <summary>

src/ModelContextProtocol.AspNetCore/IdleTrackingBackgroundService.cs

@@ -12,7 +12,7 @@ internal sealed partial class IdleTrackingBackgroundService(
     ILogger<IdleTrackingBackgroundService> logger) : BackgroundService
 {
     // The compiler will complain about the parameter being unused otherwise despite the source generator.
-    private ILogger _logger = logger;
+    private readonly ILogger _logger = logger;
 
     protected override async Task ExecuteAsync(CancellationToken stoppingToken)
     {

src/ModelContextProtocol.AspNetCore/StatelessSessionId.cs

@@ -5,9 +5,6 @@ namespace ModelContextProtocol.AspNetCore;
 
 internal sealed class StatelessSessionId
 {
-    [JsonPropertyName("capabilities")]
-    public ClientCapabilities? Capabilities { get; init; }
-
     [JsonPropertyName("clientInfo")]
     public Implementation? ClientInfo { get; init; }
 

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -7,6 +7,7 @@
 using Microsoft.Net.Http.Headers;
 using ModelContextProtocol.Protocol.Messages;
 using ModelContextProtocol.Protocol.Transport;
+using ModelContextProtocol.Protocol.Types;
 using ModelContextProtocol.Server;
 using ModelContextProtocol.Utils.Json;
 using System.Collections.Concurrent;
@@ -27,8 +28,6 @@ internal sealed class StreamableHttpHandler(
     ILoggerFactory loggerFactory,
     IServiceProvider applicationServices)
 {
-    private const string StatelessSessionIdPurpose = "Microsoft.AspNetCore.StreamableHttpHandler.StatelessSessionId";
-
     private static readonly JsonTypeInfo<JsonRpcError> s_errorTypeInfo = GetRequiredJsonTypeInfo<JsonRpcError>();
 
     private static readonly MediaTypeHeaderValue s_applicationJsonMediaType = new("application/json");
@@ -38,7 +37,7 @@ internal sealed class StreamableHttpHandler(
 
     public HttpServerTransportOptions HttpServerTransportOptions => httpServerTransportOptions.Value;
 
-    private IDataProtector Protector { get; } = dataProtection.CreateProtector(StatelessSessionIdPurpose);
+    private IDataProtector Protector { get; } = dataProtection.CreateProtector("Microsoft.AspNetCore.StreamableHttpHandler.StatelessSessionId");
 
     public async Task HandlePostRequestAsync(HttpContext context)
     {
@@ -139,7 +138,10 @@ public async Task HandleDeleteRequestAsync(HttpContext context)
         {
             var sessionJson = Protector.Unprotect(sessionId);
             var statelessSessionId = JsonSerializer.Deserialize(sessionJson, StatelessSessionIdJsonContext.Default.StatelessSessionId);
-            var transport = new StreamableHttpServerTransport();
+            var transport = new StreamableHttpServerTransport
+            {
+                Stateless = true,
+            };
             session = await CreateSessionAsync(context, transport, sessionId, statelessSessionId);
         }
         else if (!Sessions.TryGetValue(sessionId, out session))
@@ -148,7 +150,7 @@ public async Task HandleDeleteRequestAsync(HttpContext context)
             // One of the few other usages I found was from some Ethereum JSON-RPC documentation and this
             // JSON-RPC library from Microsoft called StreamJsonRpc where it's called JsonRpcErrorCode.NoMarshaledObjectFound
             // https://learn.microsoft.com/dotnet/api/streamjsonrpc.protocol.jsonrpcerrorcode?view=streamjsonrpc-2.9#fields
-            await WriteJsonRpcErrorAsync(context, "Session not found", StatusCodes.Status404NotFound, 32001);
+            await WriteJsonRpcErrorAsync(context, "Session not found", StatusCodes.Status404NotFound, -32001);
             return null;
         }
 
@@ -182,18 +184,23 @@ await WriteJsonRpcErrorAsync(context,
     private async ValueTask<HttpMcpSession<StreamableHttpServerTransport>> StartNewSessionAsync(HttpContext context)
     {
         string sessionId;
-        var transport = new StreamableHttpServerTransport();
+        StreamableHttpServerTransport transport;
 
         if (!HttpServerTransportOptions.Stateless)
         {
             sessionId = MakeNewSessionId();
+            transport = new();
             context.Response.Headers["mcp-session-id"] = sessionId;
         }
         else
         {
             // "(uninitialized stateless id)" is not written anywhere. We delay writing the mcp-session-id
             // until after we receive the initialize request with the client info we need to serialize.
             sessionId = "(uninitialized stateless id)";
+            transport = new()
+            {
+                Stateless = true,
+            };
             ScheduleStatelessSessionIdWrite(context, transport);
         }
 
@@ -217,15 +224,18 @@ private async ValueTask<HttpMcpSession<StreamableHttpServerTransport>> CreateSes
         string sessionId,
         StatelessSessionId? statelessId = null)
     {
+        var mcpServerServices = applicationServices;
         var mcpServerOptions = mcpServerOptionsSnapshot.Value;
         if (statelessId is not null || HttpServerTransportOptions.ConfigureSessionOptions is not null)
         {
             mcpServerOptions = mcpServerOptionsFactory.Create(Options.DefaultName);
 
             if (statelessId is not null)
             {
-                mcpServerOptions.KnownClientInfo = statelessId.ClientInfo ?? mcpServerOptions.KnownClientInfo;
-                mcpServerOptions.KnownClientCapabilities = statelessId.Capabilities ?? mcpServerOptions.KnownClientCapabilities;
+                // The session does not outlive the request in stateless mode.
+                mcpServerServices = context.RequestServices;
+                mcpServerOptions.ScopeRequests = false;
+                mcpServerOptions.KnownClientInfo = statelessId.ClientInfo;
             }
 
             if (HttpServerTransportOptions.ConfigureSessionOptions is { } configureSessionOptions)
@@ -234,8 +244,7 @@ private async ValueTask<HttpMcpSession<StreamableHttpServerTransport>> CreateSes
             }
         }
 
-        // Use application instead of request services, because the session will likely outlive the first initialization request.
-        var server = McpServerFactory.Create(transport, mcpServerOptions, loggerFactory, applicationServices);
+        var server = McpServerFactory.Create(transport, mcpServerOptions, loggerFactory, mcpServerServices);
         context.Features.Set(server);
 
         var userIdClaim = statelessId?.UserIdClaim ?? GetUserIdClaim(context.User);
@@ -286,8 +295,7 @@ private void ScheduleStatelessSessionIdWrite(HttpContext context, StreamableHttp
         {
             var statelessId = new StatelessSessionId
             {
-                ClientInfo = transport.ClientInfo,
-                Capabilities = transport.ClientCapabilities,
+                ClientInfo = transport?.InitializeRequest?.ClientInfo,
                 UserIdClaim = GetUserIdClaim(context.User),
             };
 

src/ModelContextProtocol/Protocol/Transport/StreamableHttpPostTransport.cs

@@ -42,6 +42,11 @@ public async ValueTask<bool> RunAsync(CancellationToken cancellationToken)
 
     public async Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default)
     {
+        if (parentTransport.Stateless && message is JsonRpcRequest)
+        {
+            throw new InvalidOperationException("Server to client requests are not supported in stateless mode.");
+        }
+
         await _sseWriter.SendMessageAsync(message, cancellationToken).ConfigureAwait(false);
     }
 
@@ -76,11 +81,9 @@ private async ValueTask OnMessageReceivedAsync(JsonRpcMessage? message, Cancella
             _pendingRequest = request.Id;
 
             // Store client capabilities so they can be serialized by "stateless" callers for use in later requests.
-            if (request.Method == RequestMethods.Initialize)
+            if (parentTransport.Stateless && request.Method == RequestMethods.Initialize)
             {
-                var initializeRequestParams = JsonSerializer.Deserialize(request.Params, McpJsonUtilities.JsonContext.Default.InitializeRequestParams);
-                parentTransport.ClientCapabilities = initializeRequestParams?.Capabilities;
-                parentTransport.ClientInfo = initializeRequestParams?.ClientInfo;
+                parentTransport.InitializeRequest = JsonSerializer.Deserialize(request.Params, McpJsonUtilities.JsonContext.Default.InitializeRequestParams);
             }
         }
 

src/ModelContextProtocol/Protocol/Transport/StreamableHttpServerTransport.cs

@@ -38,14 +38,18 @@ public sealed class StreamableHttpServerTransport : ITransport
     private int _getRequestStarted;
 
     /// <summary>
-    /// Gets the capabilities supported by the client if it was received by <see cref="HandlePostRequest(IDuplexPipe, CancellationToken)"/>.
+    /// Configures whether the transport should be in stateless mode that does not require all requests for a given session
+    /// to arrive to the same ASP.NET Core application process. Unsolicited server-to-client messages are not supported in this mode,
+    /// so calling <see cref="HandleGetRequest(Stream, CancellationToken)"/> results in an <see cref="InvalidOperationException"/>.
+    /// Server-to-client requests are also unsupported, because the responses may arrive at another ASP.NET Core application process.
+    /// Client sampling and roots capabilities are also disabled in stateless mode, because the server cannot make requests.
     /// </summary>
-    public ClientCapabilities? ClientCapabilities { get; internal set; }
+    public bool Stateless { get; init; }
 
     /// <summary>
-    /// Gets the version and implementation information of the connected client if it was received by <see cref="HandlePostRequest(IDuplexPipe, CancellationToken)"/>.
+    /// Gets the initialize request if it was received by <see cref="HandlePostRequest(IDuplexPipe, CancellationToken)"/> and <see cref="Stateless"/> is set to <see langword="true"/>.
     /// </summary>
-    public Implementation? ClientInfo { get; internal set; }
+    public InitializeRequestParams? InitializeRequest { get; internal set; }
 
     /// <inheritdoc/>
     public ChannelReader<JsonRpcMessage> MessageReader => _incomingChannel.Reader;
@@ -62,6 +66,11 @@ public sealed class StreamableHttpServerTransport : ITransport
     /// <returns>A task representing the send loop that writes JSON-RPC messages to the SSE response stream.</returns>
     public async Task HandleGetRequest(Stream sseResponseStream, CancellationToken cancellationToken)
     {
+        if (Stateless)
+        {
+            throw new InvalidOperationException("GET requests are not supported in stateless mode.");
+        }
+
         if (Interlocked.Exchange(ref _getRequestStarted, 1) == 1)
         {
             throw new InvalidOperationException("Session resumption is not yet supported. Please start a new session.");
@@ -93,6 +102,11 @@ public async Task<bool> HandlePostRequest(IDuplexPipe httpBodies, CancellationTo
     /// <inheritdoc/>
     public async Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default)
     {
+        if (Stateless)
+        {
+            throw new InvalidOperationException("Unsolicited server to client messages are not supported in stateless mode.");
+        }
+
         await _sseWriter.SendMessageAsync(message, cancellationToken).ConfigureAwait(false);
     }
 

src/ModelContextProtocol/Server/McpServer.cs

@@ -58,7 +58,6 @@ public McpServer(ITransport transport, McpServerOptions options, ILoggerFactory?
         _serverOnlyEndpointName = $"Server ({options.ServerInfo?.Name ?? DefaultImplementation.Name} {options.ServerInfo?.Version ?? DefaultImplementation.Version})";
         _servicesScopePerRequest = options.ScopeRequests;
 
-        ClientCapabilities = options.KnownClientCapabilities;
         ClientInfo = options.KnownClientInfo;
         UpdateEndpointNameWithClientInfo();
 
@@ -80,26 +79,29 @@ public McpServer(ITransport transport, McpServerOptions options, ILoggerFactory?
         }
 
         // Now that everything has been configured, subscribe to any necessary notifications.
-        if (ServerOptions.Capabilities?.Tools?.ToolCollection is { } tools)
+        if (transport is not StreamableHttpServerTransport streamableHttpTransport || streamableHttpTransport.Stateless is false)
         {
-            EventHandler changed = (sender, e) => _ = this.SendNotificationAsync(NotificationMethods.ToolListChangedNotification);
-            tools.Changed += changed;
-            _disposables.Add(() => tools.Changed -= changed);
-        }
+            if (ServerOptions.Capabilities?.Tools?.ToolCollection is { } tools)
+            {
+                EventHandler changed = (sender, e) => _ = this.SendNotificationAsync(NotificationMethods.ToolListChangedNotification);
+                tools.Changed += changed;
+                _disposables.Add(() => tools.Changed -= changed);
+            }
 
-        if (ServerOptions.Capabilities?.Prompts?.PromptCollection is { } prompts)
-        {
-            EventHandler changed = (sender, e) => _ = this.SendNotificationAsync(NotificationMethods.PromptListChangedNotification);
-            prompts.Changed += changed;
-            _disposables.Add(() => prompts.Changed -= changed);
-        }
+            if (ServerOptions.Capabilities?.Prompts?.PromptCollection is { } prompts)
+            {
+                EventHandler changed = (sender, e) => _ = this.SendNotificationAsync(NotificationMethods.PromptListChangedNotification);
+                prompts.Changed += changed;
+                _disposables.Add(() => prompts.Changed -= changed);
+            }
 
-        var resources = ServerOptions.Capabilities?.Resources?.ResourceCollection;
-        if (resources is not null)
-        {
-            EventHandler changed = (sender, e) => _ = this.SendNotificationAsync(NotificationMethods.PromptListChangedNotification);
-            resources.Changed += changed;
-            _disposables.Add(() => resources.Changed -= changed);
+            var resources = ServerOptions.Capabilities?.Resources?.ResourceCollection;
+            if (resources is not null)
+            {
+                EventHandler changed = (sender, e) => _ = this.SendNotificationAsync(NotificationMethods.PromptListChangedNotification);
+                resources.Changed += changed;
+                _disposables.Add(() => resources.Changed -= changed);
+            }
         }
 
         // And initialize the session.

src/ModelContextProtocol/Server/McpServerExtensions.cs

@@ -30,14 +30,10 @@ public static class McpServerExtensions
     /// and token limits.
     /// </remarks>
     public static ValueTask<CreateMessageResult> RequestSamplingAsync(
-        this IMcpServer server, CreateMessageRequestParams request, CancellationToken cancellationToken)
+        this IMcpServer server, CreateMessageRequestParams request, CancellationToken cancellationToken = default)
     {
         Throw.IfNull(server);
-
-        if (server.ClientCapabilities?.Sampling is null)
-        {
-            throw new InvalidOperationException("Client does not support sampling.");
-        }
+        ThrowIfSamplingUnsupported(server);
 
         return server.SendRequestAsync(
             RequestMethods.SamplingCreateMessage,
@@ -163,11 +159,7 @@ public static async Task<ChatResponse> RequestSamplingAsync(
     public static IChatClient AsSamplingChatClient(this IMcpServer server)
     {
         Throw.IfNull(server);
-
-        if (server.ClientCapabilities?.Sampling is null)
-        {
-            throw new InvalidOperationException("Client does not support sampling.");
-        }
+        ThrowIfSamplingUnsupported(server);
 
         return new SamplingChatClient(server);
     }
@@ -198,14 +190,10 @@ public static ILoggerProvider AsClientLoggerProvider(this IMcpServer server)
     /// or other structured data sources that the client makes available through the protocol.
     /// </remarks>
     public static ValueTask<ListRootsResult> RequestRootsAsync(
-        this IMcpServer server, ListRootsRequestParams request, CancellationToken cancellationToken)
+        this IMcpServer server, ListRootsRequestParams request, CancellationToken cancellationToken = default)
     {
         Throw.IfNull(server);
-
-        if (server.ClientCapabilities?.Roots is null)
-        {
-            throw new InvalidOperationException("Client does not support roots.");
-        }
+        ThrowIfRootsUnsupported(server);
 
         return server.SendRequestAsync(
             RequestMethods.RootsList,
@@ -215,6 +203,32 @@ public static ValueTask<ListRootsResult> RequestRootsAsync(
             cancellationToken: cancellationToken);
     }
 
+    private static void ThrowIfSamplingUnsupported(IMcpServer server)
+    {
+        if (server.ClientCapabilities?.Sampling is null)
+        {
+            if (server.ServerOptions.KnownClientInfo is not null)
+            {
+                throw new InvalidOperationException("Sampling is not supported in stateless mode.");
+            }
+
+            throw new InvalidOperationException("Client does not support sampling.");
+        }
+    }
+
+    private static void ThrowIfRootsUnsupported(IMcpServer server)
+    {
+        if (server.ClientCapabilities?.Roots is null)
+        {
+            if (server.ServerOptions.KnownClientInfo is not null)
+            {
+                throw new InvalidOperationException("Roots are not supported in stateless mode.");
+            }
+
+            throw new InvalidOperationException("Client does not support roots.");
+        }
+    }
+
     /// <summary>Provides an <see cref="IChatClient"/> implementation that's implemented via client sampling.</summary>
     private sealed class SamplingChatClient(IMcpServer server) : IChatClient
     {