Add client completion notification and details

Introduce a new mechanism for reporting MCP client session completion details, including both graceful and error terminations. Add a Completion property to McpClient, exposing a `Task<ClientCompletionDetails>` that completes with details about session closure. Implement extensible completion details (including StdioClientCompletionDetails for stdio transports) and propagate them via a new internal TransportClosedException.

Author: stephentoub

src/ModelContextProtocol.Core/Client/ClientCompletionDetails.cs

@@ -0,0 +1,21 @@
+namespace ModelContextProtocol.Client;
+
+/// <summary>
+/// Provides details about why an MCP client session completed.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Transport implementations may return derived types with additional strongly-typed
+/// information, such as <see cref="StdioClientCompletionDetails"/>.
+/// </para>
+/// </remarks>
+public class ClientCompletionDetails
+{
+    /// <summary>
+    /// Gets the exception that caused the session to close, if any.
+    /// </summary>
+    /// <remarks>
+    /// This is <see langword="null"/> for graceful closure.
+    /// </remarks>
+    public Exception? Exception { get; set; }
+}

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -53,4 +53,21 @@ protected McpClient()
     /// </para>
     /// </remarks>
     public abstract string? ServerInstructions { get; }
+
+    /// <summary>
+    /// Gets a <see cref="Task{TResult}"/> that completes when the client session has completed.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The task always completes successfully. The result provides details about why the session
+    /// completed. Transport implementations may return derived types with additional strongly-typed
+    /// information, such as <see cref="StdioClientCompletionDetails"/>.
+    /// </para>
+    /// <para>
+    /// For graceful closure (e.g., explicit disposal), <see cref="ClientCompletionDetails.Exception"/>
+    /// will be <see langword="null"/>. For unexpected closure (e.g., process crash, network failure),
+    /// it may contain an exception that caused or that represents the failure.
+    /// </para>
+    /// </remarks>
+    public abstract Task<ClientCompletionDetails> Completion { get; }
 }

src/ModelContextProtocol.Core/Client/McpClientImpl.cs

@@ -521,6 +521,9 @@ private void RegisterTaskHandlers(RequestHandlers requestHandlers, IMcpTaskStore
     /// <inheritdoc/>
     public override string? ServerInstructions => _serverInstructions;
 
+    /// <inheritdoc/>
+    public override Task<ClientCompletionDetails> Completion => _sessionHandler.CompletionTask;
+
     /// <summary>
     /// Asynchronously connects to an MCP server, establishes the transport connection, and completes the initialization handshake.
     /// </summary>
@@ -655,6 +658,14 @@ public override async ValueTask DisposeAsync()
         _taskCancellationTokenProvider?.Dispose();
         await _sessionHandler.DisposeAsync().ConfigureAwait(false);
         await _transport.DisposeAsync().ConfigureAwait(false);
+
+        // After disposal, the channel writer is complete but ProcessMessagesCoreAsync
+        // may have been cancelled with unread items still buffered. ChannelReader.Completion
+        // only resolves once all items are consumed, so drain remaining items.
+        while (_transport.MessageReader.TryRead(out var _));
+
+        // Then ensure all work has quiesced.
+        await Completion.ConfigureAwait(false);
     }
 
     [LoggerMessage(Level = LogLevel.Information, Message = "{EndpointName} client received server '{ServerInfo}' capabilities: '{Capabilities}'.")]

src/ModelContextProtocol.Core/Client/SseClientSessionTransport.cs

@@ -179,6 +179,8 @@ private async Task ReceiveMessagesAsync(CancellationToken cancellationToken)
             }
             else
             {
+                SetDisconnected(ex);
+
                 LogTransportReadMessagesFailed(Name, ex);
                 _connectionEstablished.TrySetException(ex);
                 throw;

src/ModelContextProtocol.Core/Client/StdioClientCompletionDetails.cs

@@ -0,0 +1,22 @@
+namespace ModelContextProtocol.Client;
+
+/// <summary>
+/// Provides details about the completion of a stdio-based MCP client session.
+/// </summary>
+public sealed class StdioClientCompletionDetails : ClientCompletionDetails
+{
+    /// <summary>
+    /// Gets the process ID of the server process, or <see langword="null"/> if unavailable.
+    /// </summary>
+    public int? ProcessId { get; set; }
+
+    /// <summary>
+    /// Gets the exit code of the server process, or <see langword="null"/> if unavailable.
+    /// </summary>
+    public int? ExitCode { get; set; }
+
+    /// <summary>
+    /// Gets the last lines of the server process's standard error output, or <see langword="null"/> if unavailable.
+    /// </summary>
+    public IEnumerable<string>? StandardErrorTail { get; set; }
+}

src/ModelContextProtocol.Core/Client/StdioClientSessionTransport.cs

@@ -5,14 +5,22 @@
 namespace ModelContextProtocol.Client;
 
 /// <summary>Provides the client side of a stdio-based session transport.</summary>
-internal sealed class StdioClientSessionTransport(
-    StdioClientTransportOptions options, Process process, string endpointName, Queue<string> stderrRollingLog, ILoggerFactory? loggerFactory) :
-    StreamClientSessionTransport(process.StandardInput.BaseStream, process.StandardOutput.BaseStream, encoding: null, endpointName, loggerFactory)
+internal sealed class StdioClientSessionTransport : StreamClientSessionTransport
 {
-    private readonly StdioClientTransportOptions _options = options;
-    private readonly Process _process = process;
-    private readonly Queue<string> _stderrRollingLog = stderrRollingLog;
+    private readonly StdioClientTransportOptions _options;
+    private readonly Process _process;
+    private readonly Queue<string> _stderrRollingLog;
     private int _cleanedUp = 0;
+    private readonly int? _processId;
+
+    public StdioClientSessionTransport(StdioClientTransportOptions options, Process process, string endpointName, Queue<string> stderrRollingLog, ILoggerFactory? loggerFactory) :
+        base(process.StandardInput.BaseStream, process.StandardOutput.BaseStream, encoding: null, endpointName, loggerFactory)
+    {
+        _options = options;
+        _process = process;
+        _stderrRollingLog = stderrRollingLog;
+        try { _processId = process.Id; } catch { }
+    }
 
     /// <inheritdoc/>
     public override async Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default)
@@ -47,17 +55,26 @@ protected override async ValueTask CleanupAsync(Exception? error = null, Cancell
         // so create an exception with details about that.
         error ??= await GetUnexpectedExitExceptionAsync(cancellationToken).ConfigureAwait(false);
 
-        // Now terminate the server process.
+        // Terminate the server process (or confirm it already exited), then build
+        // and publish strongly-typed completion details while the process handle
+        // is still valid so we can read the exit code.
         try
         {
-            StdioClientTransport.DisposeProcess(_process, processRunning: true, shutdownTimeout: _options.ShutdownTimeout);
+            StdioClientTransport.DisposeProcess(
+                _process, 
+                processRunning: true,
+                _options.ShutdownTimeout,
+                beforeDispose: () => SetDisconnected(new TransportClosedException(BuildCompletionDetails(error))));
         }
         catch (Exception ex)
         {
             LogTransportShutdownFailed(Name, ex);
+            SetDisconnected(new TransportClosedException(BuildCompletionDetails(error)));
         }
 
-        // And handle cleanup in the base type.
+        // And handle cleanup in the base type. SetDisconnected has already been
+        // called above, so the base call is a no-op for disconnect state but
+        // still performs other cleanup (cancelling the read task, etc.).
         await base.CleanupAsync(error, cancellationToken).ConfigureAwait(false);
     }
 
@@ -104,4 +121,32 @@ protected override async ValueTask CleanupAsync(Exception? error = null, Cancell
 
         return new IOException(errorMessage);
     }
+
+    private StdioClientCompletionDetails BuildCompletionDetails(Exception? error)
+    {
+        StdioClientCompletionDetails details = new()
+        {
+            Exception = error,
+            ProcessId = _processId,
+        };
+        
+        try
+        {
+            if (StdioClientTransport.HasExited(_process))
+            {
+                details.ExitCode = _process.ExitCode;
+            }
+        }
+        catch { }
+
+        lock (_stderrRollingLog)
+        {
+            if (_stderrRollingLog.Count > 0)
+            {
+                details.StandardErrorTail = _stderrRollingLog.ToArray();
+            }
+        }
+
+        return details;
+    }
 }

src/ModelContextProtocol.Core/Client/StdioClientTransport.cs

@@ -213,7 +213,7 @@ public async Task<ITransport> ConnectAsync(CancellationToken cancellationToken =
     }
 
     internal static void DisposeProcess(
-        Process? process, bool processRunning, TimeSpan shutdownTimeout)
+        Process? process, bool processRunning, TimeSpan shutdownTimeout, Action? beforeDispose = null)
     {
         if (process is not null)
         {
@@ -239,6 +239,10 @@ internal static void DisposeProcess(
                 {
                     process.WaitForExit();
                 }
+
+                // Invoke the callback while the process handle is still valid,
+                // e.g. to read ExitCode before Dispose() invalidates it.
+                beforeDispose?.Invoke();
             }
             finally
             {

src/ModelContextProtocol.Core/Client/TransportClosedException.cs

@@ -0,0 +1,19 @@
+using ModelContextProtocol.Protocol;
+using System.Threading.Channels;
+
+namespace ModelContextProtocol.Client;
+
+/// <summary>
+/// <see cref="IOException"/> used to smuggle <see cref="ClientCompletionDetails"/> through
+/// the <see cref="ChannelWriter{T}.TryComplete(Exception?)"/> mechanism.
+/// </summary>
+/// <remarks>
+/// This could be made public in the future to allow custom <see cref="ITransport"/>
+/// implementations to provide their own <see cref="ClientCompletionDetails"/>-derived types
+/// by completing their channel with this exception.
+/// </remarks>
+internal sealed class TransportClosedException(ClientCompletionDetails details) :
+    IOException(details.Exception?.Message, details.Exception)
+{
+    public ClientCompletionDetails Details { get; } = details;
+}

src/ModelContextProtocol.Core/McpSessionHandler.cs

@@ -132,6 +132,7 @@ public McpSessionHandler(
         _incomingMessageFilter = incomingMessageFilter ?? (next => next);
         _outgoingMessageFilter = outgoingMessageFilter ?? (next => next);
         _logger = logger;
+
         LogSessionCreated(EndpointName, _sessionId, _transportKind);
     }
 
@@ -145,6 +146,15 @@ public McpSessionHandler(
     /// </summary>
     public string? NegotiatedProtocolVersion { get; set; }
 
+    /// <summary>
+    /// Gets a task that completes when the client session has completed, providing details about the closure.
+    /// Completion details are resolved from the transport's channel completion exception: if a transport
+    /// completes its channel with a <see cref="TransportClosedException"/>, the wrapped
+    /// <see cref="ClientCompletionDetails"/> is unwrapped. Otherwise, a default instance is returned.
+    /// </summary>
+    internal Task<ClientCompletionDetails> CompletionTask => 
+        field ??= GetCompletionDetailsAsync(_transport.MessageReader.Completion);
+
     /// <summary>
     /// Starts processing messages from the transport. This method will block until the transport is disconnected.
     /// This is generally started in a background task or thread from the initialization logic of the derived class.
@@ -297,6 +307,28 @@ ex is OperationCanceledException &&
         }
     }
 
+    /// <summary>
+    /// Resolves <see cref="ClientCompletionDetails"/> from the transport's channel completion.
+    /// If the channel was completed with a <see cref="TransportClosedException"/>, the wrapped
+    /// details are returned. Otherwise a default instance is created from the completion state.
+    /// </summary>
+    private static async Task<ClientCompletionDetails> GetCompletionDetailsAsync(Task channelCompletion)
+    {
+        try
+        {
+            await channelCompletion.ConfigureAwait(false);
+            return new ClientCompletionDetails();
+        }
+        catch (TransportClosedException tce)
+        {
+            return tce.Details;
+        }
+        catch (Exception ex)
+        {
+            return new ClientCompletionDetails { Exception = ex };
+        }
+    }
+
     private async Task HandleMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken)
     {
         Histogram<double> durationMetric = _isServer ? s_serverOperationDuration : s_clientOperationDuration;

tests/ModelContextProtocol.AspNetCore.Tests/HttpServerIntegrationTests.cs

@@ -303,4 +303,17 @@ public async Task CallTool_Sse_EchoServer_Concurrently()
             Assert.Equal($"Echo: Hello MCP! {i}", textContent.Text);
         }
     }
+
+    [Fact]
+    public async Task Completion_GracefulDisposal_ReturnsCompletionDetails()
+    {
+        var client = await GetClientAsync();
+        Assert.False(client.Completion.IsCompleted);
+
+        await client.DisposeAsync();
+        Assert.True(client.Completion.IsCompleted);
+
+        var details = await client.Completion;
+        Assert.Null(details.Exception);
+    }
 }