Add HttpClientCompletionDetails for HTTP session completion

Author: stephentoub

src/ModelContextProtocol.Core/Client/HttpClientCompletionDetails.cs

@@ -0,0 +1,15 @@
+using System.Net;
+
+namespace ModelContextProtocol.Client;
+
+/// <summary>
+/// Provides details about the completion of an HTTP-based MCP client session,
+/// including sessions using the legacy SSE transport or the Streamable HTTP transport.
+/// </summary>
+public sealed class HttpClientCompletionDetails : ClientCompletionDetails
+{
+    /// <summary>
+    /// Gets the HTTP status code that caused the session to close, or <see langword="null"/> if unavailable.
+    /// </summary>
+    public HttpStatusCode? HttpStatusCode { get; set; }
+}

src/ModelContextProtocol.Core/Client/SseClientSessionTransport.cs

@@ -2,6 +2,7 @@
 using Microsoft.Extensions.Logging.Abstractions;
 using ModelContextProtocol.Protocol;
 using System.Diagnostics;
+using System.Net;
 using System.Net.Http.Headers;
 using System.Net.ServerSentEvents;
 using System.Text.Json;
@@ -124,7 +125,7 @@ private async Task CloseAsync()
         }
         finally
         {
-            SetDisconnected();
+            SetDisconnected(new TransportClosedException(new HttpClientCompletionDetails()));
         }
     }
 
@@ -143,6 +144,7 @@ public override async ValueTask DisposeAsync()
 
     private async Task ReceiveMessagesAsync(CancellationToken cancellationToken)
     {
+        HttpStatusCode? failureStatusCode = null;
         try
         {
             using var request = new HttpRequestMessage(HttpMethod.Get, _sseEndpoint);
@@ -151,6 +153,11 @@ private async Task ReceiveMessagesAsync(CancellationToken cancellationToken)
 
             using var response = await _httpClient.SendAsync(request, message: null, cancellationToken).ConfigureAwait(false);
 
+            if (!response.IsSuccessStatusCode)
+            {
+                failureStatusCode = response.StatusCode;
+            }
+
             await response.EnsureSuccessStatusCodeWithResponseBodyAsync(cancellationToken).ConfigureAwait(false);
 
             using var stream = await response.Content.ReadAsStreamAsync(cancellationToken).ConfigureAwait(false);
@@ -179,7 +186,11 @@ private async Task ReceiveMessagesAsync(CancellationToken cancellationToken)
             }
             else
             {
-                SetDisconnected(ex);
+                SetDisconnected(new TransportClosedException(new HttpClientCompletionDetails
+                {
+                    HttpStatusCode = failureStatusCode,
+                    Exception = ex,
+                }));
 
                 LogTransportReadMessagesFailed(Name, ex);
                 _connectionEstablished.TrySetException(ex);
@@ -188,7 +199,7 @@ private async Task ReceiveMessagesAsync(CancellationToken cancellationToken)
         }
         finally
         {
-            SetDisconnected();
+            SetDisconnected(new TransportClosedException(new HttpClientCompletionDetails()));
         }
     }
 

src/ModelContextProtocol.Core/Client/StreamableHttpClientSessionTransport.cs

@@ -20,11 +20,12 @@ internal sealed partial class StreamableHttpClientSessionTransport : TransportBa
 
     private readonly McpHttpClient _httpClient;
     private readonly HttpClientTransportOptions _options;
-    private readonly CancellationTokenSource _connectionCts;
+    private readonly CancellationTokenSource _connectionCts = new();
     private readonly ILogger _logger;
 
     private string? _negotiatedProtocolVersion;
     private Task? _getReceiveTask;
+    private volatile TransportClosedException? _disconnectError;
 
     private readonly SemaphoreSlim _disposeLock = new(1, 1);
     private bool _disposed;
@@ -42,7 +43,6 @@ public StreamableHttpClientSessionTransport(
 
         _options = transportOptions;
         _httpClient = httpClient;
-        _connectionCts = new CancellationTokenSource();
         _logger = (ILogger?)loggerFactory?.CreateLogger<HttpClientTransport>() ?? NullLogger.Instance;
 
         // We connect with the initialization request with the MCP transport. This means that any errors won't be observed
@@ -96,6 +96,13 @@ internal async Task<HttpResponseMessage> SendHttpRequestAsync(JsonRpcMessage mes
         // We'll let the caller decide whether to throw or fall back given an unsuccessful response.
         if (!response.IsSuccessStatusCode)
         {
+            // Per the MCP spec, a 404 response to a request containing an Mcp-Session-Id
+            // indicates the session has ended. Signal completion so McpClient.Completion resolves.
+            if (response.StatusCode == HttpStatusCode.NotFound && SessionId is not null)
+            {
+                SetSessionExpired(response.StatusCode);
+            }
+
             return response;
         }
 
@@ -184,18 +191,14 @@ public override async ValueTask DisposeAsync()
             {
                 LogTransportShutdownFailed(Name, ex);
             }
-            finally
-            {
-                _connectionCts.Dispose();
-            }
         }
         finally
         {
             // If we're auto-detecting the transport and failed to connect, leave the message Channel open for the SSE transport.
             // This class isn't directly exposed to public callers, so we don't have to worry about changing the _state in this case.
             if (_options.TransportMode is not HttpTransportMode.AutoDetect || _getReceiveTask is not null)
             {
-                SetDisconnected();
+                SetDisconnected(_disconnectError ?? new TransportClosedException(new HttpClientCompletionDetails()));
             }
         }
     }
@@ -204,8 +207,8 @@ private async Task ReceiveUnsolicitedMessagesAsync()
     {
         var state = new SseStreamState();
 
-        // Continuously receive unsolicited messages until canceled
-        while (!_connectionCts.Token.IsCancellationRequested)
+        // Continuously receive unsolicited messages until canceled or disconnected
+        while (!_connectionCts.Token.IsCancellationRequested && IsConnected)
         {
             await SendGetSseRequestWithRetriesAsync(
                 relatedRpcRequest: null,
@@ -285,6 +288,13 @@ await SendGetSseRequestWithRetriesAsync(
 
                 if (!response.IsSuccessStatusCode)
                 {
+                    // Per the MCP spec, a 404 response to a request containing an Mcp-Session-Id
+                    // indicates the session has ended. Signal completion so McpClient.Completion resolves.
+                    if (response.StatusCode == HttpStatusCode.NotFound && SessionId is not null)
+                    {
+                        SetSessionExpired(response.StatusCode);
+                    }
+
                     // If the server could be reached but returned a non-success status code,
                     // retrying likely won't change that.
                     return null;
@@ -474,4 +484,23 @@ private static TimeSpan ElapsedSince(long stopwatchTimestamp)
         return TimeSpan.FromSeconds((double)(Stopwatch.GetTimestamp() - stopwatchTimestamp) / Stopwatch.Frequency);
 #endif
     }
+
+    private void SetSessionExpired(HttpStatusCode statusCode)
+    {
+        // Store the error before canceling so DisposeAsync can use it if it races us, especially
+        // after the call to Cancel below, to invoke SetDisconnected.
+        _disconnectError = new TransportClosedException(new HttpClientCompletionDetails
+        {
+            HttpStatusCode = statusCode,
+            Exception = new McpException(
+                "The server returned HTTP 404 for a request with an Mcp-Session-Id, indicating the session has expired. " +
+                "To continue, create a new client session or call ResumeSessionAsync with a new connection."),
+        });
+
+        // Cancel to unblock any in-flight operations (e.g., SSE stream reads in
+        // SendGetSseRequestWithRetriesAsync) that are waiting on _connectionCts.Token.
+        _connectionCts.Cancel();
+
+        SetDisconnected(_disconnectError);
+    }
 }

src/ModelContextProtocol.Core/McpSessionHandler.cs

@@ -916,9 +916,11 @@ public async ValueTask DisposeAsync()
             {
                 await _messageProcessingTask.ConfigureAwait(false);
             }
-            catch (OperationCanceledException)
+            catch
             {
-                // Ignore cancellation
+                // Ignore exceptions from the message processing loop. It may fault with
+                // OperationCanceledException on normal shutdown or TransportClosedException
+                // when the transport's channel completes with an error.
             }
         }
 

src/ModelContextProtocol.Core/Protocol/TransportBase.cs

@@ -90,13 +90,15 @@ internal TransportBase(string name, Channel<JsonRpcMessage>? messageChannel, ILo
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     protected async Task WriteMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default)
     {
+        cancellationToken.ThrowIfCancellationRequested();
+
         if (!IsConnected)
         {
-            throw new InvalidOperationException("Transport is not connected.");
+            // Transport disconnected concurrently. Silently drop rather than throw,
+            // to avoid surfacing spurious errors during shutdown races.
+            return;
         }
 
-        cancellationToken.ThrowIfCancellationRequested();
-
         if (_logger.IsEnabled(LogLevel.Debug))
         {
             var messageId = (message as JsonRpcMessageWithId)?.Id.ToString() ?? "(no id)";

tests/ModelContextProtocol.AspNetCore.Tests/HttpServerIntegrationTests.cs

@@ -314,6 +314,8 @@ public async Task Completion_GracefulDisposal_ReturnsCompletionDetails()
         Assert.True(client.Completion.IsCompleted);
 
         var details = await client.Completion;
-        Assert.Null(details.Exception);
+        var httpDetails = Assert.IsType<HttpClientCompletionDetails>(details);
+        Assert.Null(httpDetails.Exception);
+        Assert.Null(httpDetails.HttpStatusCode);
     }
 }

tests/ModelContextProtocol.AspNetCore.Tests/SseIntegrationTests.cs

@@ -322,7 +322,8 @@ public async Task Completion_ServerShutdown_ReturnsHttpCompletionDetails()
         await app.StopAsync(TestContext.Current.CancellationToken);
 
         var details = await mcpClient.Completion.WaitAsync(TestContext.Current.CancellationToken);
-        Assert.IsType<ClientCompletionDetails>(details);
+        var httpDetails = Assert.IsType<HttpClientCompletionDetails>(details);
+        Assert.Null(httpDetails.HttpStatusCode);
     }
 
     public class Envelope