Send MCP-Protocol-Version header with transport messages

Author: stephentoub

src/ModelContextProtocol.Core/Client/AutoDetectingClientSessionTransport.cs

@@ -18,6 +18,7 @@ internal sealed partial class AutoDetectingClientSessionTransport : ITransport
     private readonly ILogger _logger;
     private readonly string _name;
     private readonly Channel<JsonRpcMessage> _messageChannel;
+    private string? _protocolVersion;
 
     public AutoDetectingClientSessionTransport(SseClientTransportOptions transportOptions, HttpClient httpClient, ILoggerFactory? loggerFactory, string endpointName)
     {
@@ -43,6 +44,20 @@ public AutoDetectingClientSessionTransport(SseClientTransportOptions transportOp
     /// </summary>
     internal ITransport? ActiveTransport { get; private set; }
 
+    /// <inheritdoc />
+    public string? ProtocolVersion
+    {
+        get => ActiveTransport?.ProtocolVersion ?? _protocolVersion;
+        set
+        {
+            _protocolVersion = value;
+            if (ActiveTransport is { } transport)
+            {
+                transport.ProtocolVersion = value;
+            }
+        }
+    }
+
     public ChannelReader<JsonRpcMessage> MessageReader => _messageChannel.Reader;
 
     /// <inheritdoc/>
@@ -70,6 +85,10 @@ private async Task InitializeAsync(JsonRpcMessage message, CancellationToken can
             {
                 LogUsingStreamableHttp(_name);
                 ActiveTransport = streamableHttpTransport;
+                if (_protocolVersion is { } protocolVersion)
+                {
+                    ActiveTransport.ProtocolVersion = protocolVersion;
+                }
             }
             else
             {

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -118,6 +118,7 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
             // Connect transport
             _sessionTransport = await _clientTransport.ConnectAsync(cancellationToken).ConfigureAwait(false);
             InitializeSession(_sessionTransport);
+
             // We don't want the ConnectAsync token to cancel the session after we've successfully connected.
             // The base class handles cleaning up the session in DisposeAsync without our help.
             StartSession(_sessionTransport, fullSessionCancellationToken: CancellationToken.None);
@@ -164,6 +165,8 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
                     throw new McpException($"Server protocol version mismatch. Expected {requestProtocol}, got {initializeResponse.ProtocolVersion}");
                 }
 
+                _sessionTransport.ProtocolVersion = initializeResponse.ProtocolVersion;
+
                 // Send initialized notification
                 await SendMessageAsync(
                     new JsonRpcNotification { Method = NotificationMethods.InitializedNotification },

src/ModelContextProtocol.Core/Client/SseClientSessionTransport.cs

@@ -91,7 +91,7 @@ public override async Task SendMessageAsync(
         {
             Content = content,
         };
-        StreamableHttpClientSessionTransport.CopyAdditionalHeaders(httpRequestMessage.Headers, _options.AdditionalHeaders);
+        StreamableHttpClientSessionTransport.CopyAdditionalHeaders(httpRequestMessage.Headers, _options.AdditionalHeaders, protocolVersion: ProtocolVersion);
         var response = await _httpClient.SendAsync(httpRequestMessage, cancellationToken).ConfigureAwait(false);
 
         if (!response.IsSuccessStatusCode)
@@ -152,7 +152,7 @@ private async Task ReceiveMessagesAsync(CancellationToken cancellationToken)
         {
             using var request = new HttpRequestMessage(HttpMethod.Get, _sseEndpoint);
             request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("text/event-stream"));
-            StreamableHttpClientSessionTransport.CopyAdditionalHeaders(request.Headers, _options.AdditionalHeaders);
+            StreamableHttpClientSessionTransport.CopyAdditionalHeaders(request.Headers, _options.AdditionalHeaders, protocolVersion: ProtocolVersion);
 
             using var response = await _httpClient.SendAsync(
                 request,

src/ModelContextProtocol.Core/Client/StreamableHttpClientSessionTransport.cs

@@ -85,7 +85,7 @@ internal async Task<HttpResponseMessage> SendHttpRequestAsync(JsonRpcMessage mes
             },
         };
 
-        CopyAdditionalHeaders(httpRequestMessage.Headers, _options.AdditionalHeaders, _mcpSessionId);
+        CopyAdditionalHeaders(httpRequestMessage.Headers, _options.AdditionalHeaders, _mcpSessionId, ProtocolVersion);
 
         var response = await _httpClient.SendAsync(httpRequestMessage, HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
 
@@ -170,7 +170,7 @@ private async Task ReceiveUnsolicitedMessagesAsync()
         // Send a GET request to handle any unsolicited messages not sent over a POST response.
         using var request = new HttpRequestMessage(HttpMethod.Get, _options.Endpoint);
         request.Headers.Accept.Add(s_textEventStreamMediaType);
-        CopyAdditionalHeaders(request.Headers, _options.AdditionalHeaders, _mcpSessionId);
+        CopyAdditionalHeaders(request.Headers, _options.AdditionalHeaders, _mcpSessionId, ProtocolVersion);
 
         using var response = await _httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, _connectionCts.Token).ConfigureAwait(false);
 
@@ -245,23 +245,30 @@ private void LogJsonException(JsonException ex, string data)
         }
     }
 
-    internal static void CopyAdditionalHeaders(HttpRequestHeaders headers, Dictionary<string, string>? additionalHeaders, string? sessionId = null)
+    internal static void CopyAdditionalHeaders(
+        HttpRequestHeaders headers, 
+        Dictionary<string, string>? additionalHeaders, 
+        string? sessionId = null,
+        string? protocolVersion = null)
     {
         if (sessionId is not null)
         {
             headers.Add("mcp-session-id", sessionId);
         }
 
-        if (additionalHeaders is null)
+        if (protocolVersion is not null)
         {
-            return;
+            headers.Add("MCP-Protocol-Version", protocolVersion);
         }
 
-        foreach (var header in additionalHeaders)
+        if (additionalHeaders is not null)
         {
-            if (!headers.TryAddWithoutValidation(header.Key, header.Value))
+            foreach (var header in additionalHeaders)
             {
-                throw new InvalidOperationException($"Failed to add header '{header.Key}' with value '{header.Value}' from {nameof(SseClientTransportOptions.AdditionalHeaders)}.");
+                if (!headers.TryAddWithoutValidation(header.Key, header.Value))
+                {
+                    throw new InvalidOperationException($"Failed to add header '{header.Key}' with value '{header.Value}' from {nameof(SseClientTransportOptions.AdditionalHeaders)}.");
+                }
             }
         }
     }

src/ModelContextProtocol.Core/Protocol/ITransport.cs

@@ -60,4 +60,12 @@ public interface ITransport : IAsyncDisposable
     /// </para>
     /// </remarks>
     Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default);
+
+    /// <summary>Gets or sets the protocol version that's in use.</summary>
+    /// <remarks>
+    /// Setting the protocol version does not change the protocol version actively employed by the transport.
+    /// It provides that information to the transport for situations where the transport needs to be able to
+    /// propagate the version information, for example as part of HTTP headers or for logging and diagnostic purposes.
+    /// </remarks>
+    string? ProtocolVersion { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/TransportBase.cs

@@ -59,6 +59,9 @@ internal TransportBase(string name, Channel<JsonRpcMessage>? messageChannel, ILo
     /// <summary>Gets the logger used by this transport.</summary>
     private protected ILogger Logger => _logger;
 
+    /// <inheritdoc />
+    public string? ProtocolVersion { get; set; }
+
     /// <summary>
     /// Gets the name that identifies this transport endpoint in logs.
     /// </summary>

src/ModelContextProtocol.Core/Server/SseResponseStreamTransport.cs

@@ -34,6 +34,9 @@ public sealed class SseResponseStreamTransport(Stream sseResponseStream, string?
 
     private bool _isConnected;
 
+    /// <inheritdoc />
+    public string? ProtocolVersion { get; set; }
+
     /// <summary>
     /// Starts the transport and writes the JSON-RPC messages sent via <see cref="SendMessageAsync"/>
     /// to the SSE response stream until cancellation is requested or the transport is disposed.

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

@@ -18,6 +18,9 @@ internal sealed class StreamableHttpPostTransport(StreamableHttpServerTransport
 
     public ChannelReader<JsonRpcMessage> MessageReader => throw new NotSupportedException("JsonRpcMessage.RelatedTransport should only be used for sending messages.");
 
+    /// <inheritdoc />
+    public string? ProtocolVersion { get; set; }
+
     /// <returns>
     /// True, if data was written to the respond body.
     /// False, if nothing was written because the request body did not contain any <see cref="JsonRpcRequest"/> messages to respond to.

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

@@ -35,6 +35,9 @@ public sealed class StreamableHttpServerTransport : ITransport
     private readonly CancellationTokenSource _disposeCts = new();
 
     private int _getRequestStarted;
+    
+    /// <inheritdoc />
+    public string? ProtocolVersion { get; set; }
 
     /// <summary>
     /// Configures whether the transport should be in stateless mode that does not require all requests for a given session

tests/Common/Utils/TestServerTransport.cs

@@ -10,6 +10,8 @@ public class TestServerTransport : ITransport
 
     public bool IsConnected { get; set; }
 
+    public string? ProtocolVersion { get; set; }
+
     public ChannelReader<JsonRpcMessage> MessageReader => _messageChannel;
 
     public List<JsonRpcMessage> SentMessages { get; } = [];