Merge branch 'main' into feature/oauth-token-endpoint-auth-selector

Author: RobotechUSA

src/ModelContextProtocol.Core/Client/AutoDetectingClientSessionTransport.cs

@@ -77,16 +77,19 @@ private async Task InitializeAsync(JsonRpcMessage message, CancellationToken can
             else if (await StreamableHttpClientSessionTransport.TryReadJsonRpcErrorAsync(response, cancellationToken).ConfigureAwait(false) is { } parsedError)
             {
                 // A JSON-RPC error envelope in the body means the peer IS a Streamable HTTP server.
-                // It just rejected our specific request (e.g., -32022 UnsupportedProtocolVersion,
-                // -32021 MissingRequiredClientCapability, -32020 HeaderMismatch, or any other
-                // application-level error). Don't fall back to SSE — that would mask the real signal
-                // and surface a misleading "session id required" error from the SSE GET path.
-                // Adopt the Streamable HTTP transport and throw the structured exception so the
-                // connect-time fallback logic can react per spec PR #2844. Setting ActiveTransport
-                // first makes the catch filter below leave the now-owned transport alone.
+                // Adopt it before surfacing the failure so the catch filter leaves the now-owned
+                // transport alone, and never mask the response by attempting deprecated SSE.
                 LogUsingStreamableHttp(_name);
                 ActiveTransport = streamableHttpTransport;
-                throw McpSessionHandler.CreateRemoteProtocolExceptionFromError(parsedError);
+
+                if (StreamableHttpClientSessionTransport.ShouldSurfaceJsonRpcErrorAsProtocolException(response.StatusCode, parsedError))
+                {
+                    throw McpSessionHandler.CreateRemoteProtocolExceptionFromError(parsedError);
+                }
+
+                // TryReadJsonRpcErrorAsync buffered the content, so this preserves the same response
+                // body and status without consuming the network stream a second time.
+                throw await HttpResponseMessageExtensions.CreateHttpRequestExceptionWithBodyAsync(response, cancellationToken).ConfigureAwait(false);
             }
             else
             {

src/ModelContextProtocol.Core/Client/McpClientImpl.cs

@@ -367,14 +367,6 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
                         // fallback): falling back to initialize wouldn't fix a malformed envelope.
                         throw;
                     }
-                    catch (McpProtocolException ex) when (
-                        ex.ErrorCode == McpErrorCode.InvalidRequest &&
-                        ex.Message.Contains(McpHttpHeaders.SessionId, StringComparison.Ordinal))
-                    {
-                        // Local transport validation: a 2026-07-28+ response must not carry HTTP session state.
-                        // This is not evidence of an initialize-handshake server, so do not fall back.
-                        throw;
-                    }
                     catch (McpProtocolException)
                     {
                         // Per spec PR #2844, the fallback MUST NOT be keyed to a single error code.

src/ModelContextProtocol.Core/Client/StreamableHttpClientSessionTransport.cs

@@ -80,19 +80,19 @@ public override async Task SendMessageAsync(JsonRpcMessage message, Cancellation
         // for robustness. Servers occasionally emit them with 4xx codes other than 400.
         if (!response.IsSuccessStatusCode &&
             await TryReadJsonRpcErrorAsync(response, cancellationToken).ConfigureAwait(false) is { } parsedError &&
-            (response.StatusCode == HttpStatusCode.BadRequest ||
-             IsPerRequestMetadataProtocolErrorCode((McpErrorCode)parsedError.Error.Code)))
+            ShouldSurfaceJsonRpcErrorAsProtocolException(response.StatusCode, parsedError))
         {
             throw McpSessionHandler.CreateRemoteProtocolExceptionFromError(parsedError);
         }
 
         await response.EnsureSuccessStatusCodeWithResponseBodyAsync(cancellationToken).ConfigureAwait(false);
     }
 
-    private static bool IsPerRequestMetadataProtocolErrorCode(McpErrorCode code) =>
-        code is McpErrorCode.UnsupportedProtocolVersion
-             or McpErrorCode.MissingRequiredClientCapability
-             or McpErrorCode.HeaderMismatch;
+    internal static bool ShouldSurfaceJsonRpcErrorAsProtocolException(HttpStatusCode statusCode, JsonRpcError error) =>
+        statusCode == HttpStatusCode.BadRequest ||
+        (McpErrorCode)error.Error.Code is McpErrorCode.UnsupportedProtocolVersion
+                                          or McpErrorCode.MissingRequiredClientCapability
+                                          or McpErrorCode.HeaderMismatch;
 
     /// <summary>
     /// Reads a JSON-RPC error envelope from an <c>application/json</c> response body, returning

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

@@ -76,9 +76,6 @@ public async ValueTask<bool> HandlePostAsync(JsonRpcMessage message, Cancellatio
             return false;
         }
 
-        CancellationTokenSource? deferredFlushCts = null;
-        Task? deferredFlushTask = null;
-        bool deferHeaderFlush = false;
         using (await _messageLock.LockAsync(cancellationToken).ConfigureAwait(false))
         {
             var primingItem = await TryStartSseEventStreamAsync(_pendingRequest).ConfigureAwait(false);
@@ -87,88 +84,33 @@ public async ValueTask<bool> HandlePostAsync(JsonRpcMessage message, Cancellatio
                 await NotifyResponseStartingAsync(firstMessage: null).ConfigureAwait(false);
                 await _httpSseWriter.WriteAsync(primingItem.Value, cancellationToken).ConfigureAwait(false);
             }
-            else if (onResponseStarting is null)
+            else if (onResponseStarting is not null &&
+                McpProtocolVersions.RequiresPerRequestMetadata(message.Context.ProtocolVersion))
             {
-                // 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);
+                // Per-request-metadata protocol revisions map the first JSON-RPC error onto the HTTP
+                // status line. Keep the headers uncommitted until that message arrives so the mapping
+                // cannot depend on how long dispatch takes.
             }
             else
             {
-                deferHeaderFlush = true;
+                // Earlier protocol revisions keep the eager header flush for long-running handlers.
+                // Mark the response as started before flushing because any later JSON-RPC error must
+                // not attempt to change an already committed status line.
+                await NotifyResponseStartingAsync(firstMessage: null).ConfigureAwait(false);
+                await responseStream.FlushAsync(cancellationToken).ConfigureAwait(false);
             }
 
             // Ensure that we've sent the priming event before processing the incoming request.
             await parentTransport.MessageWriter.WriteAsync(message, cancellationToken).ConfigureAwait(false);
         }
 
-        if (deferHeaderFlush)
-        {
-            // Defer the flush (and the header commit it implies) so the callback can still choose
-            // the HTTP status line for an immediate JSON-RPC error. Start the bounded grace period
-            // only after the request has been queued for dispatch.
-            deferredFlushCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
-            deferredFlushTask = DeferredHeaderFlushAsync(deferredFlushCts.Token);
-        }
-
-        try
-        {
-            // Wait for the response to be written before returning from the handler.
-            // This keeps the HTTP response open until the final response message is sent.
-            await _httpResponseTcs.Task.WaitAsync(cancellationToken).ConfigureAwait(false);
-        }
-        finally
-        {
-            if (deferredFlushCts is not null)
-            {
-                deferredFlushCts.Cancel();
-                await deferredFlushTask!.ConfigureAwait(false);
-                deferredFlushCts.Dispose();
-            }
-        }
+        // Wait for the response to be written before returning from the handler.
+        // This keeps the HTTP response open until the final response message is sent.
+        await _httpResponseTcs.Task.WaitAsync(cancellationToken).ConfigureAwait(false);
 
         return true;
     }
 
-    /// <summary>
-    /// Bounds the deferred header flush: after a short grace window, flushes the response headers
-    /// if no response message has been written yet. Immediate rejections land well inside the
-    /// window, so the response-starting callback can still map their JSON-RPC error codes onto the
-    /// HTTP status line; a handler that runs longer commits the headers here so clients see them
-    /// promptly (long-running tool calls must not trip HttpClient's response timeout).
-    /// </summary>
-    private async Task DeferredHeaderFlushAsync(CancellationToken cancellationToken)
-    {
-        try
-        {
-            await Task.Delay(DeferredHeaderFlushGrace, cancellationToken).ConfigureAwait(false);
-            using var _ = await _messageLock.LockAsync(cancellationToken).ConfigureAwait(false);
-            if (!_httpResponseStarted && !_httpResponseCompleted)
-            {
-                await NotifyResponseStartingAsync(firstMessage: null).ConfigureAwait(false);
-                await responseStream.FlushAsync(cancellationToken).ConfigureAwait(false);
-            }
-        }
-        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-        {
-            // The response was written or the request ended before the grace window elapsed.
-        }
-        catch (Exception ex)
-        {
-            // Surface the failure to the awaiting HandlePostAsync when possible. If the response
-            // future has already been resolved (the response started or completed on another path),
-            // TrySetException is a no-op, so log here to keep the deferred-flush failure diagnosable.
-            if (!_httpResponseTcs.TrySetException(ex))
-            {
-                LogDeferredHeaderFlushFailed(ex);
-            }
-        }
-    }
-
-    /// <summary>How long the response-header flush may be deferred waiting for the first response message.</summary>
-    internal static readonly TimeSpan DeferredHeaderFlushGrace = TimeSpan.FromMilliseconds(250);
-
     /// <summary>
     /// Invokes the response-starting callback exactly once, immediately before the first write to
     /// the HTTP response stream, so the HTTP application can still set the response status line.
@@ -343,6 +285,4 @@ public async ValueTask DisposeAsync()
     [LoggerMessage(Level = LogLevel.Warning, Message = "Failed to dispose SSE event stream writer.")]
     private partial void LogStoreStreamDisposalFailed(Exception exception);
 
-    [LoggerMessage(Level = LogLevel.Warning, Message = "Failed to flush deferred Streamable HTTP response headers.")]
-    private partial void LogDeferredHeaderFlushFailed(Exception exception);
 }

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

@@ -216,14 +216,14 @@ public Task<bool> HandlePostRequestAsync(JsonRpcMessage message, Stream response
     /// This overload additionally reports the first JSON-RPC message written to the response via
     /// <paramref name="onResponseStarting"/>, before any response bytes are written, so the HTTP
     /// application can still choose the response status line (SEP-2575 maps some JSON-RPC error
-    /// codes to HTTP statuses). When <paramref name="onResponseStarting"/> is provided, the eager
-    /// response-header flush that normally precedes request processing is deferred until that first
-    /// message; the callback receives <see langword="null"/> when the first write is not a JSON-RPC
-    /// message (e.g. a resumability priming event).
+    /// codes to HTTP statuses). When <paramref name="onResponseStarting"/> is provided for a
+    /// per-request-metadata protocol revision, the eager response-header flush that normally precedes
+    /// request processing is deferred until that first message; the callback receives
+    /// <see langword="null"/> when the first write is not a JSON-RPC message (e.g. a resumability
+    /// priming event).
     /// The status line can only be influenced by the FIRST write: when a handler streams a
-    /// notification (e.g. progress) before failing, or runs past the transport's bounded
-    /// header-flush grace window, the status is already committed and a later JSON-RPC error
-    /// rides the committed status.
+    /// notification (e.g. progress) before failing, the status is already committed and a later
+    /// JSON-RPC error rides the committed status.
     /// </summary>
     /// <param name="message">The JSON-RPC message to process.</param>
     /// <param name="responseStream">The response stream to write any JSON-RPC responses to.</param>

tests/ModelContextProtocol.AspNetCore.Tests/July2026ProtocolHttpFallbackTests.cs

@@ -57,15 +57,22 @@ public async ValueTask DisposeAsync()
         base.Dispose();
     }
 
-    private async Task StartServerAsync(RequestDelegate handler)
+    private async Task StartServerAsync(RequestDelegate handler, bool acceptGet = false)
     {
         Builder.Services.Configure<JsonOptions>(options =>
         {
             options.SerializerOptions.TypeInfoResolverChain.Add(McpJsonUtilities.DefaultOptions.TypeInfoResolver!);
         });
 
         _app = Builder.Build();
-        _app.MapPost("/mcp", handler);
+        if (acceptGet)
+        {
+            _app.MapMethods("/mcp", [HttpMethods.Get, HttpMethods.Post], handler);
+        }
+        else
+        {
+            _app.MapPost("/mcp", handler);
+        }
         await _app.StartAsync(TestContext.Current.CancellationToken);
     }
 
@@ -302,6 +309,63 @@ await WriteJsonRpcErrorAsync(context, HttpStatusCode.BadRequest,
         Assert.False(initializeReceived);
     }
 
+    [Theory]
+    [InlineData(HttpStatusCode.Unauthorized)]
+    [InlineData(HttpStatusCode.Forbidden)]
+    [InlineData(HttpStatusCode.InternalServerError)]
+    public async Task AutoDetect_OnNonModernJsonRpcErrorOutside400_PreservesHttpFailure_NoFallback(HttpStatusCode statusCode)
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var initializeRequests = 0;
+        var sseGetRequests = 0;
+
+        await StartServerAsync(async context =>
+        {
+            if (HttpMethods.IsGet(context.Request.Method))
+            {
+                sseGetRequests++;
+                context.Response.StatusCode = StatusCodes.Status405MethodNotAllowed;
+                return;
+            }
+
+            var message = await JsonSerializer.DeserializeAsync(
+                context.Request.Body,
+                GetJsonTypeInfo<JsonRpcMessage>(),
+                ct);
+
+            if (message is JsonRpcRequest { Method: RequestMethods.Initialize })
+            {
+                initializeRequests++;
+            }
+
+            await WriteJsonRpcErrorAsync(
+                context,
+                statusCode,
+                code: (int)McpErrorCode.InvalidRequest,
+                message: "non-modern structured error");
+        }, acceptGet: true);
+
+        await using var transport = new HttpClientTransport(new()
+        {
+            Endpoint = new("http://localhost:5000/mcp"),
+            TransportMode = HttpTransportMode.AutoDetect,
+        }, HttpClient, LoggerFactory);
+
+        var exception = await Assert.ThrowsAsync<HttpRequestException>(async () =>
+        {
+            await using var client = await McpClient.CreateAsync(
+                transport,
+                new McpClientOptions(),
+                loggerFactory: LoggerFactory,
+                cancellationToken: ct);
+        });
+
+        Assert.Equal(statusCode, exception.StatusCode);
+        Assert.Contains("non-modern structured error", exception.Message);
+        Assert.Equal(0, initializeRequests);
+        Assert.Equal(0, sseGetRequests);
+    }
+
     [Fact]
     public async Task Client_OnPerRequestMetadataResponseWithMcpSessionId_IgnoresSessionState()
     {

tests/ModelContextProtocol.AspNetCore.Tests/MapMcpTests.cs

@@ -239,10 +239,9 @@ public async Task Server_ShutsDownQuickly_WhenClientIsConnected()
     [Fact]
     public async Task LongRunningToolCall_DoesNotTimeout_WhenNoEventStreamStore()
     {
-        // Regression test for: Tool calls that last over HttpClient timeout without producing
-        // intermediate notifications will timeout because HttpClient doesn't see the 200 response
-        // until the first message is written. When primingItem is null (no ISseEventStreamStore),
-        // we should flush the response stream so HttpClient sees the 200 immediately.
+        // Legacy Streamable HTTP tool calls that run past the HttpClient timeout without producing
+        // intermediate notifications need an eager response flush. Per-request-metadata protocol
+        // revisions instead wait for the first JSON-RPC message so SEP-2575 can map its status.
 
         Builder.Services.AddMcpServer().WithHttpTransport(ConfigureStateless).WithTools<LongRunningTools>();
 
@@ -274,7 +273,11 @@ public async Task LongRunningToolCall_DoesNotTimeout_WhenNoEventStreamStore()
                     TransportMode = transportMode,
                 }, shortTimeoutClient, LoggerFactory);
 
-                await using var mcpClient = await McpClient.CreateAsync(transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken);
+                await using var mcpClient = await McpClient.CreateAsync(
+                    transport,
+                    new McpClientOptions { ProtocolVersion = "2025-11-25" },
+                    LoggerFactory,
+                    TestContext.Current.CancellationToken);
 
                 // Call a tool that takes 2 seconds - this should succeed despite the 1 second HttpClient timeout
                 // because the response stream is flushed immediately after receiving the request