feat: add JSON response mode for Streamable HTTP

Author: Loi Nguyen

docs/concepts/stateless/stateless.md

@@ -418,6 +418,7 @@ builder.Services.AddMcpServer()
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.Stateless> | `bool` | `true` | Enables stateless mode. No sessions, no `Mcp-Session-Id` header, no server-to-client requests on the legacy protocol. Required by the `2026-07-28` protocol revision. |
+| <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.EnableJsonResponse> | `bool` | `false` | Returns the final JSON-RPC response as `application/json` instead of an SSE stream. Intermediate request-related messages, POST resumability, and polling are unavailable in this mode. |
 | <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.IdleTimeout> | `TimeSpan` | 2 hours | _Stateful only (`MCP9006`)._ Duration of inactivity before a session is closed. Checked every 5 seconds. |
 | <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.MaxIdleSessionCount> | `int` | 10,000 | _Stateful only (`MCP9006`)._ Maximum idle sessions before the oldest are forcibly terminated. |
 | <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.ConfigureSessionOptions> | `Func<HttpContext, McpServerOptions, CancellationToken, Task>?` | `null` | Per-session callback to customize `McpServerOptions` with access to `HttpContext`. In stateless mode (including all `2026-07-28` requests), this runs on every HTTP request. |

docs/concepts/transports/transports.md

@@ -185,6 +185,21 @@ app.Run();
 
 By default, the HTTP transport runs **statelessly** — the server does not assign an `Mcp-Session-Id` or track transport session state in memory. This simplifies deployment, enables horizontal scaling without session affinity, and matches the `2026-07-28` Streamable HTTP wire format. Set `Stateless = false` explicitly when your server needs stateful sessions for unsolicited notifications, resource subscriptions, or per-client isolation. For a detailed guide on when to use stateless vs. stateful mode, configure session options, and understand [cancellation and disposal](xref:stateless#cancellation-and-disposal) behavior during shutdown, see [Stateless and Stateful](xref:stateless).
 
+#### JSON response mode
+
+By default, each Streamable HTTP POST returns an SSE stream so the server can send progress notifications and other intermediate messages before the final JSON-RPC response. Set <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.EnableJsonResponse> to `true` when an intermediary, such as a web application firewall or reverse proxy, cannot pass SSE responses:
+
+```csharp
+builder.Services.AddMcpServer()
+    .WithHttpTransport(options =>
+    {
+        options.EnableJsonResponse = true;
+    })
+    .WithTools<MyTools>();
+```
+
+In this mode, POST requests return the final JSON-RPC response directly with an `application/json` content type. Request-related progress notifications and other intermediate messages are omitted, event-store resumability and polling are unavailable for POST responses, and notification-only POST requests still return an empty `202 Accepted` response. Stateful servers can still use the standalone GET SSE stream for unsolicited messages.
+
 #### Host name validation
 
 For local HTTP servers, keep the set of accepted host names limited to loopback values. This helps protect against DNS rebinding, where a browser reaches a local server through an attacker-controlled DNS name while sending that DNS name in the HTTP `Host` header. ASP.NET Core's Kestrel server doesn't validate `Host` headers by default, so configure `AllowedHosts` with known host names rather than `"*"`. This also avoids reflecting untrusted host names through ASP.NET Core features such as absolute URL generation. See [Host filtering with ASP.NET Core Kestrel web server | Microsoft Learn](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/host-filtering) and [URL generation concepts | Microsoft Learn](https://learn.microsoft.com/aspnet/core/fundamentals/routing#url-generation-concepts).
@@ -244,7 +259,7 @@ app.MapMcp("/mcp").RequireCors("McpBrowserClient");
 
 #### How messages flow
 
-In Streamable HTTP, client requests arrive as HTTP `POST` requests. The server holds each `POST` response body open as an SSE stream and writes the JSON-RPC response — plus any intermediate messages like progress notifications or server-to-client requests — back through it. This provides natural HTTP-level backpressure: each `POST` holds its connection until the handler completes.
+In Streamable HTTP, client requests arrive as HTTP POST requests. By default, the server holds each POST response body open as an SSE stream and writes the JSON-RPC response — plus any intermediate messages like progress notifications or server-to-client requests — back through it. JSON response mode instead returns only the final response as `application/json`. Both modes provide natural HTTP-level backpressure because each POST remains open until the handler completes.
 
 In stateful mode, the client can also open a long-lived `GET` request to receive **unsolicited** messages — notifications or server-to-client requests that the server initiates outside any active request handler (for example, resource-changed notifications from a background watcher). In stateless mode, the `GET` endpoint is not mapped, so every message must be part of a `POST` response. For a detailed breakdown, see [How Streamable HTTP delivers messages](xref:stateless#how-streamable-http-delivers-messages).
 

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

@@ -72,6 +72,21 @@ public class HttpServerTransportOptions
     /// </remarks>
     public bool Stateless { get; set; } = true;
 
+    /// <summary>
+    /// Gets or sets a value that indicates whether Streamable HTTP POST requests return a single JSON response
+    /// instead of an SSE stream.
+    /// </summary>
+    /// <value>
+    /// <see langword="true"/> to return the final JSON-RPC response as <c>application/json</c>;
+    /// <see langword="false"/> to use an SSE response stream. The default is <see langword="false"/>.
+    /// </value>
+    /// <remarks>
+    /// JSON response mode is intended for simple request/response scenarios where intermediaries do not support SSE.
+    /// Request-related notifications and other intermediate messages are not included in the response. Standalone GET
+    /// requests continue to use SSE when stateful mode is enabled.
+    /// </remarks>
+    public bool EnableJsonResponse { get; set; }
+
     /// <summary>
     /// Gets or sets a value that indicates whether the server maps legacy SSE endpoints (<c>/sse</c> and <c>/message</c>)
     /// for backward compatibility with clients that do not support the Streamable HTTP transport.

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -178,7 +178,15 @@ await WriteJsonRpcErrorAsync(context,
             };
         }
 
-        InitializeSseResponse(context);
+        if (session.Transport.EnableJsonResponse)
+        {
+            context.Response.ContentType = "application/json";
+        }
+        else
+        {
+            InitializeSseResponse(context);
+        }
+
         var wroteResponse = await session.Transport.HandlePostRequestAsync(message, context.Response.Body, onResponseStarting, context.RequestAborted);
         if (!wroteResponse)
         {
@@ -503,6 +511,7 @@ private async ValueTask<StreamableHttpSession> StartNewSessionAsync(HttpContext
             transport = new(loggerFactory)
             {
                 SessionId = sessionId,
+                EnableJsonResponse = HttpServerTransportOptions.EnableJsonResponse,
                 FlowExecutionContextFromRequests = !HttpServerTransportOptions.PerSessionExecutionContext,
                 EventStreamStore = HttpServerTransportOptions.EventStreamStore,
                 OnSessionInitialized = HttpServerTransportOptions.SessionMigrationHandler is { } handler
@@ -522,6 +531,7 @@ private async ValueTask<StreamableHttpSession> StartNewSessionAsync(HttpContext
             transport = new(loggerFactory)
             {
                 Stateless = true,
+                EnableJsonResponse = HttpServerTransportOptions.EnableJsonResponse,
             };
         }
 
@@ -578,6 +588,7 @@ private async ValueTask<StreamableHttpSession> MigrateSessionAsync(
         var transport = new StreamableHttpServerTransport(loggerFactory)
         {
             SessionId = sessionId,
+            EnableJsonResponse = HttpServerTransportOptions.EnableJsonResponse,
 #pragma warning disable MCP9006 // Stateful Streamable HTTP options are obsolete but still wired up internally.
             FlowExecutionContextFromRequests = !HttpServerTransportOptions.PerSessionExecutionContext,
             EventStreamStore = HttpServerTransportOptions.EventStreamStore,

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

@@ -20,7 +20,7 @@ internal sealed partial class StreamableHttpPostTransport(
 {
     private readonly SemaphoreSlim _messageLock = new(1, 1);
     private readonly TaskCompletionSource<bool> _httpResponseTcs = new(TaskCreationOptions.RunContinuationsAsynchronously);
-    private readonly SseEventWriter _httpSseWriter = new(responseStream);
+    private readonly SseEventWriter? _httpSseWriter = parentTransport.EnableJsonResponse ? null : new(responseStream);
 
     private TaskCompletionSource<bool>? _storeStreamTcs;
 #pragma warning disable MCP9006 // Stateful Streamable HTTP resumability types are obsolete but still wired up internally.
@@ -81,25 +81,28 @@ public async ValueTask<bool> HandlePostAsync(JsonRpcMessage message, Cancellatio
         bool deferHeaderFlush = false;
         using (await _messageLock.LockAsync(cancellationToken).ConfigureAwait(false))
         {
-            var primingItem = await TryStartSseEventStreamAsync(_pendingRequest).ConfigureAwait(false);
-            if (primingItem.HasValue)
+            if (!parentTransport.EnableJsonResponse)
             {
-                await NotifyResponseStartingAsync(firstMessage: null).ConfigureAwait(false);
-                await _httpSseWriter.WriteAsync(primingItem.Value, cancellationToken).ConfigureAwait(false);
-            }
-            else if (onResponseStarting is null)
-            {
-                // If there's no priming write, flush the stream to ensure HTTP response headers are
-                // sent to the client now that the server is ready to process the request.
-                // This prevents HttpClient timeout for long-running requests.
-                await responseStream.FlushAsync(cancellationToken).ConfigureAwait(false);
-            }
-            else
-            {
-                deferHeaderFlush = true;
+                var primingItem = await TryStartSseEventStreamAsync(_pendingRequest).ConfigureAwait(false);
+                if (primingItem.HasValue)
+                {
+                    await NotifyResponseStartingAsync(firstMessage: null).ConfigureAwait(false);
+                    await _httpSseWriter!.WriteAsync(primingItem.Value, cancellationToken).ConfigureAwait(false);
+                }
+                else if (onResponseStarting is null)
+                {
+                    // If there's no priming write, flush the stream to ensure HTTP response headers are
+                    // sent to the client now that the server is ready to process the request.
+                    // This prevents HttpClient timeout for long-running requests.
+                    await responseStream.FlushAsync(cancellationToken).ConfigureAwait(false);
+                }
+                else
+                {
+                    deferHeaderFlush = true;
+                }
             }
 
-            // Ensure that we've sent the priming event before processing the incoming request.
+            // In SSE mode, ensure that we've sent the priming event before processing the incoming request.
             await parentTransport.MessageWriter.WriteAsync(message, cancellationToken).ConfigureAwait(false);
         }
 
@@ -200,6 +203,41 @@ public async Task SendMessageAsync(JsonRpcMessage message, CancellationToken can
 
         try
         {
+            if (parentTransport.EnableJsonResponse)
+            {
+                if (_finalResponseMessageSent)
+                {
+                    return;
+                }
+
+                if ((message is JsonRpcResponse or JsonRpcError) && ((JsonRpcMessageWithId)message).Id == _pendingRequest)
+                {
+                    try
+                    {
+                        if (!_httpResponseCompleted)
+                        {
+                            await NotifyResponseStartingAsync(message).ConfigureAwait(false);
+                            await JsonSerializer.SerializeAsync(
+                                responseStream,
+                                message,
+                                McpJsonUtilities.JsonContext.Default.JsonRpcMessage,
+                                cancellationToken).ConfigureAwait(false);
+                        }
+                    }
+                    catch (Exception ex) when (!cancellationToken.IsCancellationRequested)
+                    {
+                        _httpResponseTcs.TrySetException(ex);
+                    }
+                    finally
+                    {
+                        _finalResponseMessageSent = true;
+                        _httpResponseTcs.TrySetResult(true);
+                    }
+                }
+
+                // JSON mode only returns the final correlated response. Intermediate messages are omitted.
+                return;
+            }
 
             if (_finalResponseMessageSent)
             {
@@ -223,7 +261,7 @@ public async Task SendMessageAsync(JsonRpcMessage message, CancellationToken can
                 try
                 {
                     await NotifyResponseStartingAsync(message).ConfigureAwait(false);
-                    await _httpSseWriter.WriteAsync(item, cancellationToken).ConfigureAwait(false);
+                    await _httpSseWriter!.WriteAsync(item, cancellationToken).ConfigureAwait(false);
                 }
                 catch (Exception ex) when (!cancellationToken.IsCancellationRequested)
                 {
@@ -245,6 +283,11 @@ public async Task SendMessageAsync(JsonRpcMessage message, CancellationToken can
 
     public async ValueTask EnablePollingAsync(TimeSpan retryInterval, CancellationToken cancellationToken)
     {
+        if (parentTransport.EnableJsonResponse)
+        {
+            throw new InvalidOperationException("Polling is not supported when JSON responses are enabled.");
+        }
+
         if (parentTransport.Stateless)
         {
             throw new InvalidOperationException("Polling is not supported in stateless mode.");
@@ -267,7 +310,7 @@ public async ValueTask EnablePollingAsync(TimeSpan retryInterval, CancellationTo
         if (!_httpResponseCompleted)
         {
             await NotifyResponseStartingAsync(firstMessage: null).ConfigureAwait(false);
-            await _httpSseWriter.WriteAsync(primingItem, cancellationToken).ConfigureAwait(false);
+            await _httpSseWriter!.WriteAsync(primingItem, cancellationToken).ConfigureAwait(false);
         }
 
         // Set the mode to 'Polling' so that the replay stream ends as soon as all available messages have been sent.
@@ -334,7 +377,7 @@ public async ValueTask DisposeAsync()
 
         _httpResponseTcs.TrySetResult(true);
 
-        _httpSseWriter.Dispose();
+        _httpSseWriter?.Dispose();
 
         // Don't dispose the event stream writer here, as we may continue to write to the event store
         // after disposal if there are pending messages.

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

@@ -69,6 +69,20 @@ public StreamableHttpServerTransport(ILoggerFactory? loggerFactory = null)
     /// </summary>
     public bool Stateless { get; init; }
 
+    /// <summary>
+    /// Gets or initializes a value that indicates whether POST requests return the final JSON-RPC response as JSON
+    /// instead of streaming messages as SSE events.
+    /// </summary>
+    /// <value>
+    /// <see langword="true"/> to write a single JSON response; <see langword="false"/> to use SSE. The default is
+    /// <see langword="false"/>.
+    /// </value>
+    /// <remarks>
+    /// When enabled, request-related notifications and other intermediate messages are omitted from POST responses.
+    /// Standalone GET requests are unaffected and continue to use SSE.
+    /// </remarks>
+    public bool EnableJsonResponse { get; init; }
+
     /// <summary>
     /// Gets or initializes a value indicating whether the execution context should flow from the calls to <see cref="HandlePostRequestAsync(JsonRpcMessage, Stream, CancellationToken)"/>
     /// to the corresponding <see cref="JsonRpcMessageContext.ExecutionContext"/> property contained in the <see cref="JsonRpcMessage"/> instances returned by the <see cref="MessageReader"/>.