Automatically fall back from Streamable HTTP to SSE on the client by default

src/ModelContextProtocol/Client/AutoDetectingClientSessionTransport.cs

@@ -0,0 +1,142 @@
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using ModelContextProtocol.Protocol;
+using System.Net;
+using System.Threading.Channels;
+
+namespace ModelContextProtocol.Client;
+
+/// <summary>
+/// A transport that automatically detects whether to use Streamable HTTP or SSE transport
+/// by trying Streamable HTTP first and falling back to SSE if that fails.
+/// </summary>
+internal sealed partial class AutoDetectingClientSessionTransport : ITransport
+{
+    private readonly SseClientTransportOptions _options;
+    private readonly HttpClient _httpClient;
+    private readonly ILoggerFactory? _loggerFactory;
+    private readonly ILogger _logger;
+    private readonly string _name;
+    private readonly Channel<JsonRpcMessage> _messageChannel;
+
+    public AutoDetectingClientSessionTransport(SseClientTransportOptions transportOptions, HttpClient httpClient, ILoggerFactory? loggerFactory, string endpointName)
+    {
+        Throw.IfNull(transportOptions);
+        Throw.IfNull(httpClient);
+
+        _options = transportOptions;
+        _httpClient = httpClient;
+        _loggerFactory = loggerFactory;
+        _logger = (ILogger?)loggerFactory?.CreateLogger<AutoDetectingClientSessionTransport>() ?? NullLogger.Instance;
+        _name = endpointName;
+
+        // Same as TransportBase.cs.
+        _messageChannel = Channel.CreateUnbounded<JsonRpcMessage>(new UnboundedChannelOptions
+        {
+            SingleReader = true,
+            SingleWriter = false,
+        });
+    }
+
+    /// <summary>
+    /// Returns the active transport (either StreamableHttp or SSE)
+    /// </summary>
+    internal ITransport? ActiveTransport { get; private set; }
+
+    public ChannelReader<JsonRpcMessage> MessageReader => _messageChannel.Reader;
+
+    /// <inheritdoc/>
+    public Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default)
+    {
+        if (ActiveTransport is null)
+        {
+            return InitializeAsync(message, cancellationToken);
+        }
+
+        return ActiveTransport.SendMessageAsync(message, cancellationToken);
+    }
+
+    private async Task InitializeAsync(JsonRpcMessage message, CancellationToken cancellationToken)
+    {
+        // Try StreamableHttp first
+        var streamableHttpTransport = new StreamableHttpClientSessionTransport(_name, _options, _httpClient, _messageChannel, _loggerFactory);
+
+        try
+        {
+            LogAttemptingStreamableHttp(_name);
+            using var response = await streamableHttpTransport.SendHttpRequestAsync(message, cancellationToken).ConfigureAwait(false);
+
+            // If the status code is not success, fall back to SSE
+            if (!response.IsSuccessStatusCode)
+            {
+                LogStreamableHttpFailed(_name, response.StatusCode);
+
+                await streamableHttpTransport.DisposeAsync().ConfigureAwait(false);
+                await InitializeSseTransportAsync(message, cancellationToken).ConfigureAwait(false);
+                return;
+            }
+
+            LogUsingStreamableHttp(_name);
+            ActiveTransport = streamableHttpTransport;
+        }
+        catch
+        {
+            // If nothing threw inside the try block, we've either set streamableHttpTransport as the
+            // ActiveTransport, or else we will have disposed it in the !IsSuccessStatusCode if statement.
+            await streamableHttpTransport.DisposeAsync().ConfigureAwait(false);
+            throw;
+        }
+    }
+
+    private async Task InitializeSseTransportAsync(JsonRpcMessage message, CancellationToken cancellationToken)
+    {
+        var sseTransport = new SseClientSessionTransport(_name, _options, _httpClient, _messageChannel, _loggerFactory);
+
+        try
+        {
+            LogAttemptingSSE(_name);
+            await sseTransport.ConnectAsync(cancellationToken).ConfigureAwait(false);
+            await sseTransport.SendMessageAsync(message, cancellationToken).ConfigureAwait(false);
+
+            LogUsingSSE(_name);
+            ActiveTransport = sseTransport;
+        }
+        catch
+        {
+            await sseTransport.DisposeAsync().ConfigureAwait(false);
+            throw;
+        }
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        try
+        {
+            if (ActiveTransport is not null)
+            {
+                await ActiveTransport.DisposeAsync().ConfigureAwait(false);
+            }
+        }
+        finally
+        {
+            // In the majority of cases, either the Streamable HTTP transport or SSE transport has completed the channel by now.
+            // However, this may not be the case if HttpClient throws during the initial request due to misconfiguration.
+            _messageChannel.Writer.TryComplete();
+        }
+    }
+
+    [LoggerMessage(Level = LogLevel.Debug, Message = "{EndpointName} attempting to connect using Streamable HTTP transport.")]
+    private partial void LogAttemptingStreamableHttp(string endpointName);
+
+    [LoggerMessage(Level = LogLevel.Information, Message = "{EndpointName} streamable HTTP transport failed with status code {StatusCode}, falling back to SSE transport.")]
+    private partial void LogStreamableHttpFailed(string endpointName, HttpStatusCode statusCode);
+
+    [LoggerMessage(Level = LogLevel.Information, Message = "{EndpointName} using Streamable HTTP transport.")]
+    private partial void LogUsingStreamableHttp(string endpointName);
+
+    [LoggerMessage(Level = LogLevel.Debug, Message = "{EndpointName} attempting to connect using SSE transport.")]
+    private partial void LogAttemptingSSE(string endpointName);
+
+    [LoggerMessage(Level = LogLevel.Information, Message = "{EndpointName} using SSE transport.")]
+    private partial void LogUsingSSE(string endpointName);
+}

src/ModelContextProtocol/Client/HttpTransportMode.cs

@@ -0,0 +1,23 @@
+namespace ModelContextProtocol.Client;
+
+/// <summary>
+/// Specifies the transport mode for HTTP client connections.
+/// </summary>
+public enum HttpTransportMode
+{
+    /// <summary>
+    /// Automatically detect the appropriate transport by trying Streamable HTTP first, then falling back to SSE if that fails.
+    /// This is the recommended mode for maximum compatibility.
+    /// </summary>
+    AutoDetect,
+
+    /// <summary>
+    /// Use only the Streamable HTTP transport.
+    /// </summary>
+    StreamableHttp,
+
+    /// <summary>
+    /// Use only the HTTP with SSE transport.
+    /// </summary>
+    Sse
+}

src/ModelContextProtocol/Client/SseClientSessionTransport.cs

@@ -6,6 +6,7 @@
 using System.Net.ServerSentEvents;
 using System.Text;
 using System.Text.Json;
+using System.Threading.Channels;
 
 namespace ModelContextProtocol.Client;
 
@@ -24,15 +25,16 @@ internal sealed partial class SseClientSessionTransport : TransportBase
     private readonly TaskCompletionSource<bool> _connectionEstablished;
 
     /// <summary>
-    /// SSE transport for client endpoints. Unlike stdio it does not launch a process, but connects to an existing server.
+    /// SSE transport for a single session. Unlike stdio it does not launch a process, but connects to an existing server.
     /// The HTTP server can be local or remote, and must support the SSE protocol.
     /// </summary>
-    /// <param name="transportOptions">Configuration options for the transport.</param>
-    /// <param name="httpClient">The HTTP client instance used for requests.</param>
-    /// <param name="loggerFactory">Logger factory for creating loggers.</param>
-    /// <param name="endpointName">The endpoint name used for logging purposes.</param>
-    public SseClientSessionTransport(SseClientTransportOptions transportOptions, HttpClient httpClient, ILoggerFactory? loggerFactory, string endpointName)
-        : base(endpointName, loggerFactory)
+    public SseClientSessionTransport(
+        string endpointName,
+        SseClientTransportOptions transportOptions,
+        HttpClient httpClient,
+        Channel<JsonRpcMessage>? messageChannel,
+        ILoggerFactory? loggerFactory)
+        : base(endpointName, messageChannel, loggerFactory)
     {
         Throw.IfNull(transportOptions);
         Throw.IfNull(httpClient);

src/ModelContextProtocol/Client/SseClientTransport.cs

@@ -4,11 +4,11 @@
 namespace ModelContextProtocol.Client;
 
 /// <summary>
-/// Provides an <see cref="IClientTransport"/> over HTTP using the Server-Sent Events (SSE) protocol.
+/// Provides an <see cref="IClientTransport"/> over HTTP using the Server-Sent Events (SSE) or Streamable HTTP protocol.
 /// </summary>
 /// <remarks>
-/// This transport connects to an MCP server over HTTP using SSE,
-/// allowing for real-time server-to-client communication with a standard HTTP request.
+/// This transport connects to an MCP server over HTTP using SSE or Streamable HTTP,
+/// allowing for real-time server-to-client communication with a standard HTTP requests.
 /// Unlike the <see cref="StdioClientTransport"/>, this transport connects to an existing server
 /// rather than launching a new process.
 /// </remarks>
@@ -57,12 +57,22 @@ public SseClientTransport(SseClientTransportOptions transportOptions, HttpClient
     /// <inheritdoc />
     public async Task<ITransport> ConnectAsync(CancellationToken cancellationToken = default)
     {
-        if (_options.UseStreamableHttp)
+        switch (_options.TransportMode)
         {
-            return new StreamableHttpClientSessionTransport(_options, _httpClient, _loggerFactory, Name);
+            case HttpTransportMode.AutoDetect:
+                return new AutoDetectingClientSessionTransport(_options, _httpClient, _loggerFactory, Name);
+            case HttpTransportMode.StreamableHttp:
+                return new StreamableHttpClientSessionTransport(Name, _options, _httpClient, messageChannel: null, _loggerFactory);
+            case HttpTransportMode.Sse:
+                return await ConnectSseTransportAsync(cancellationToken).ConfigureAwait(false);
+            default:
+                throw new InvalidOperationException($"Unsupported transport mode: {_options.TransportMode}");
         }
+    }
 
-        var sessionTransport = new SseClientSessionTransport(_options, _httpClient, _loggerFactory, Name);
+    private async Task<ITransport> ConnectSseTransportAsync(CancellationToken cancellationToken)
+    {
+        var sessionTransport = new SseClientSessionTransport(Name, _options, _httpClient, messageChannel: null, _loggerFactory);
 
         try
         {

src/ModelContextProtocol/Client/SseClientTransportOptions.cs

@@ -31,11 +31,20 @@ public required Uri Endpoint
     }
 
     /// <summary>
-    /// Gets or sets a value indicating whether to use "Streamable HTTP" for the transport rather than "HTTP with SSE". Defaults to false.
+    /// Gets or sets the transport mode to use for the connection. Defaults to <see cref="HttpTransportMode.AutoDetect"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When set to <see cref="HttpTransportMode.AutoDetect"/> (the default), the client will first attempt to use
+    /// Streamable HTTP transport and automatically fall back to SSE transport if the server doesn't support it.
+    /// This provides the best compatibility and matches the behavior of VS Code.
+    /// </para>
+    /// <para>
     /// <see href="https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http">Streamable HTTP transport specification</see>.
     /// <see href="https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse">HTTP with SSE transport specification</see>.
-    /// </summary>
-    public bool UseStreamableHttp { get; init; }
+    /// </para>
+    /// </remarks>
+    public HttpTransportMode TransportMode { get; init; } = HttpTransportMode.AutoDetect;
 
     /// <summary>
     /// Gets a transport identifier used for logging purposes.

src/ModelContextProtocol/Client/StreamableHttpClientSessionTransport.cs

@@ -4,6 +4,8 @@
 using System.Net.ServerSentEvents;
 using System.Text.Json;
 using ModelContextProtocol.Protocol;
+using System.Threading.Channels;
+
 #if NET
 using System.Net.Http.Json;
 #else
@@ -28,8 +30,13 @@ internal sealed partial class StreamableHttpClientSessionTransport : TransportBa
     private string? _mcpSessionId;
     private Task? _getReceiveTask;
 
-    public StreamableHttpClientSessionTransport(SseClientTransportOptions transportOptions, HttpClient httpClient, ILoggerFactory? loggerFactory, string endpointName)
-        : base(endpointName, loggerFactory)
+    public StreamableHttpClientSessionTransport(
+        string endpointName,
+        SseClientTransportOptions transportOptions,
+        HttpClient httpClient,
+        Channel<JsonRpcMessage>? messageChannel,
+        ILoggerFactory? loggerFactory)
+        : base(endpointName, messageChannel, loggerFactory)
     {
         Throw.IfNull(transportOptions);
         Throw.IfNull(httpClient);
@@ -46,9 +53,15 @@ public StreamableHttpClientSessionTransport(SseClientTransportOptions transportO
     }
 
     /// <inheritdoc/>
-    public override async Task SendMessageAsync(
-        JsonRpcMessage message,
-        CancellationToken cancellationToken = default)
+    public override async Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default)
+    {
+        // Immediately dispose the response. SendHttpRequestAsync only returns the response so the auto transport can look at it.
+        using var response = await SendHttpRequestAsync(message, cancellationToken).ConfigureAwait(false);
+        response.EnsureSuccessStatusCode();
+    }
+
+    // This is used by the auto transport so it can fall back and try SSE given a non-200 response without catching an exception.
+    internal async Task<HttpResponseMessage> SendHttpRequestAsync(JsonRpcMessage message, CancellationToken cancellationToken)
     {
         using var sendCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, _connectionCts.Token);
         cancellationToken = sendCts.Token;
@@ -73,9 +86,14 @@ public override async Task SendMessageAsync(
         };
 
         CopyAdditionalHeaders(httpRequestMessage.Headers, _options.AdditionalHeaders, _mcpSessionId);
-        using var response = await _httpClient.SendAsync(httpRequestMessage, HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
+
+        var response = await _httpClient.SendAsync(httpRequestMessage, HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
 
-        response.EnsureSuccessStatusCode();
+        // We'll let the caller decide whether to throw or fall back given an unsuccessful response.
+        if (!response.IsSuccessStatusCode)
+        {
+            return response;
+        }
 
         var rpcRequest = message as JsonRpcRequest;
         JsonRpcMessage? rpcResponseCandidate = null;
@@ -93,7 +111,7 @@ public override async Task SendMessageAsync(
 
         if (rpcRequest is null)
         {
-            return;
+            return response;
         }
 
         if (rpcResponseCandidate is not JsonRpcMessageWithId messageWithId || messageWithId.Id != rpcRequest.Id)
@@ -111,6 +129,8 @@ public override async Task SendMessageAsync(
 
             _getReceiveTask = ReceiveUnsolicitedMessagesAsync();
         }
+
+        return response;
     }
 
     public override async ValueTask DisposeAsync()
@@ -136,7 +156,12 @@ public override async ValueTask DisposeAsync()
         }
         finally
         {
-            SetDisconnected();
+            // 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();
+            }
         }
     }
 
@@ -215,6 +240,7 @@ private void LogJsonException(JsonException ex, string data)
         }
     }
 
+
     internal static void CopyAdditionalHeaders(HttpRequestHeaders headers, Dictionary<string, string>? additionalHeaders, string? sessionId = null)
     {
         if (sessionId is not null)

src/ModelContextProtocol/Protocol/TransportBase.cs

@@ -36,12 +36,20 @@ public abstract partial class TransportBase : ITransport
     /// Initializes a new instance of the <see cref="TransportBase"/> class.
     /// </summary>
     protected TransportBase(string name, ILoggerFactory? loggerFactory)
+        : this(name, null, loggerFactory)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TransportBase"/> class with a specified channel to back <see cref="MessageReader"/>.
+    /// </summary>
+    internal TransportBase(string name, Channel<JsonRpcMessage>? messageChannel, ILoggerFactory? loggerFactory)
     {
         Name = name;
         _logger = loggerFactory?.CreateLogger(GetType()) ?? NullLogger.Instance;
 
-        // Unbounded channel to prevent blocking on writes
-        _messageChannel = Channel.CreateUnbounded<JsonRpcMessage>(new UnboundedChannelOptions
+        // Unbounded channel to prevent blocking on writes. Ensure AutoDetectingClientSessionTransport matches this.
+        _messageChannel = messageChannel ?? Channel.CreateUnbounded<JsonRpcMessage>(new UnboundedChannelOptions
         {
             SingleReader = true,
             SingleWriter = false,