Merge branch 'main' into paulc/sep-2575-pr3002-alignment

Author: tarekgh

docs/list-of-diagnostics.md

@@ -45,4 +45,4 @@ When APIs are marked as obsolete, a diagnostic is emitted to warn users that the
 | `MCP9004` | In place | <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.EnableLegacySse> opts into the legacy SSE transport which has no built-in HTTP-level backpressure. Use Streamable HTTP instead. See [Stateless — Legacy SSE transport](xref:stateless#legacy-sse-transport) for details. |
 | `MCP9005` | In place | The Roots, Sampling, and Logging features are deprecated as of specification version 2026-07-28 and may be removed in a future version. See SEP-2577 for more information. |
 | `MCP9006` | In place | The stateful Streamable HTTP configuration knobs on <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions> — `EventStreamStore`, `SessionMigrationHandler`, `PerSessionExecutionContext`, `IdleTimeout`, and `MaxIdleSessionCount` — only apply when `Stateless = false`. Starting with the `2026-07-28` protocol revision, Streamable HTTP no longer supports sessions, and the SDK now defaults `Stateless` to `true`. These knobs remain available for back-compat with the legacy stateful Streamable HTTP transport but new code should target the stateless path. |
-| `MCP9007` | In place | `AuthorizationRedirectDelegate` and `ClientOAuthOptions.AuthorizationRedirectDelegate` are retained for source and binary compatibility but cannot provide the RFC 9207 authorization-response issuer. Use `ClientOAuthOptions.AuthorizationCallbackHandler` for issuer-aware authorization flows. |
+| `MCP9007` | In place | `AuthorizationRedirectDelegate` and `ClientOAuthOptions.AuthorizationRedirectDelegate` are retained for source and binary compatibility but cannot provide the authorization-response state or RFC 9207 issuer. State and issuer validation are skipped when these APIs are used. Use `ClientOAuthOptions.AuthorizationCallbackHandler` for response-bound, issuer-aware authorization flows. |

samples/ProtectedMcpClient/Program.cs

@@ -98,6 +98,7 @@
         var context = await listener.GetContextAsync();
         var query = HttpUtility.ParseQueryString(context.Request.Url?.Query ?? string.Empty);
         var code = query["code"];
+        var state = query["state"];
         var iss = query["iss"];
         var error = query["error"];
 
@@ -121,7 +122,7 @@
         }
 
         Console.WriteLine("Authorization code received successfully.");
-        return new AuthorizationResult { Code = code, Iss = iss };
+        return new AuthorizationResult { Code = code, State = state, Iss = iss };
     }
     catch (Exception ex)
     {

src/ModelContextProtocol.Core/Authentication/AuthorizationResult.cs

@@ -1,11 +1,16 @@
 namespace ModelContextProtocol.Authentication;
 
 /// <summary>
-/// Represents the result of an OAuth authorization redirect, containing the authorization code
-/// and optionally the issuer identifier from the authorization response.
+/// Represents the result of an OAuth authorization redirect, containing the authorization code,
+/// state, and optionally the issuer identifier from the authorization response.
 /// </summary>
 /// <remarks>
 /// <para>
+/// The <see cref="State"/> property must be populated from the <c>state</c> query parameter in the
+/// redirect URI. The SDK validates it against the value sent in the authorization request to bind
+/// the response to the initiating transaction and mitigate cross-site request forgery attacks.
+/// </para>
+/// <para>
 /// The <see cref="Iss"/> property should be populated from the <c>iss</c> query parameter in the
 /// redirect URI when present, as specified by
 /// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>.
@@ -20,6 +25,16 @@ public sealed class AuthorizationResult
     /// </summary>
     public string? Code { get; init; }
 
+    /// <summary>
+    /// Gets the state value returned in the authorization response.
+    /// </summary>
+    /// <remarks>
+    /// Implementations of <see cref="ClientOAuthOptions.AuthorizationCallbackHandler"/> must populate this
+    /// property from the <c>state</c> query parameter of the redirect URI callback. The SDK requires an
+    /// exact match with the state sent in the authorization request before exchanging the authorization code.
+    /// </remarks>
+    public string? State { get; init; }
+
     /// <summary>
     /// Gets the issuer identifier returned in the authorization response per
     /// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>.

src/ModelContextProtocol.Core/Authentication/ClientOAuthOptions.cs

@@ -80,8 +80,10 @@ public sealed class ClientOAuthOptions
     /// </para>
     /// <para>
     /// Custom implementations might open a browser, start an HTTP listener, or use other mechanisms to capture
-    /// the authorization response. They should return both the <c>code</c> and <c>iss</c> query parameters
-    /// from the redirect URI callback. This enables the SDK to validate the <c>iss</c> parameter per
+    /// the authorization response. They must return the <c>code</c> and <c>state</c> query parameters,
+    /// and should return the <c>iss</c> query parameter when present, from the redirect URI callback.
+    /// The SDK requires an exact state match before exchanging the code. Returning <c>iss</c> enables
+    /// the SDK to validate the parameter per
     /// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>, which mitigates
     /// mix-up attacks.
     /// </para>
@@ -96,9 +98,10 @@ public sealed class ClientOAuthOptions
     /// </summary>
     /// <remarks>
     /// <para>
-    /// This delegate returns only the authorization code and cannot provide the <c>iss</c> parameter from
-    /// the authorization response. Consequently, RFC 9207 issuer validation is skipped when this delegate
-    /// is used. Use <see cref="AuthorizationCallbackHandler"/> for issuer-aware authorization flows.
+    /// This delegate returns only the authorization code and cannot provide the <c>state</c> or <c>iss</c>
+    /// parameter from the authorization response. Consequently, state and RFC 9207 issuer validation are
+    /// skipped when this delegate is used. Use <see cref="AuthorizationCallbackHandler"/> for response-bound,
+    /// issuer-aware authorization flows.
     /// </para>
     /// <para>
     /// This property cannot be configured together with <see cref="AuthorizationCallbackHandler"/>.
@@ -139,8 +142,9 @@ public sealed class ClientOAuthOptions
     /// </summary>
     /// <remarks>
     /// <para>
-    /// Parameters specified cannot override or append to any automatically set parameters like the "redirect_uri",
-    /// which should instead be configured via <see cref="RedirectUri"/>.
+    /// Parameters specified cannot override or append to any automatically set parameters like
+    /// <c>redirect_uri</c> or <c>state</c>. The redirect URI should instead be configured via
+    /// <see cref="RedirectUri"/>, while state is generated uniquely for each authorization transaction.
     /// </para>
     /// </remarks>
     public IDictionary<string, string> AdditionalAuthorizationParameters { get; set; } = new Dictionary<string, string>();

src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs

@@ -32,6 +32,7 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
     private readonly IDictionary<string, string> _additionalAuthorizationParameters;
     private readonly Func<IReadOnlyList<Uri>, Uri?> _authServerSelector;
     private readonly Func<AuthorizationCallbackContext, CancellationToken, Task<AuthorizationResult?>> _authorizationCallbackHandler;
+    private readonly bool _validateAuthorizationResponseState;
     private readonly bool _validateAuthorizationResponseIssuer;
     private readonly Uri? _clientMetadataDocumentUri;
 
@@ -120,6 +121,7 @@ public ClientOAuthProvider(
         if (options.AuthorizationCallbackHandler is not null)
         {
             _authorizationCallbackHandler = options.AuthorizationCallbackHandler;
+            _validateAuthorizationResponseState = true;
             _validateAuthorizationResponseIssuer = true;
         }
         else if (authorizationRedirectDelegate is not null)
@@ -131,11 +133,13 @@ public ClientOAuthProvider(
                     context.RedirectUri,
                     cancellationToken).ConfigureAwait(false),
             };
+            _validateAuthorizationResponseState = false;
             _validateAuthorizationResponseIssuer = false;
         }
         else
         {
             _authorizationCallbackHandler = DefaultAuthorizationUrlHandler;
+            _validateAuthorizationResponseState = true;
             _validateAuthorizationResponseIssuer = true;
         }
 
@@ -155,11 +159,11 @@ public ClientOAuthProvider(
     private static Uri? DefaultAuthServerSelector(IReadOnlyList<Uri> availableServers) => availableServers.FirstOrDefault();
 
     /// <summary>
-    /// Default authorization URL handler that displays the URL to the user for manual input.
+    /// Default authorization URL handler that displays the URL to the user and parses the resulting redirect URL.
     /// </summary>
     /// <param name="context">The context containing the authorization and redirect URIs.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
-    /// <returns>The authorization result entered by the user, or null if none was provided.</returns>
+    /// <returns>The authorization result parsed from the redirect URL.</returns>
     private static Task<AuthorizationResult?> DefaultAuthorizationUrlHandler(
         AuthorizationCallbackContext context,
         CancellationToken cancellationToken)
@@ -179,6 +183,7 @@ public ClientOAuthProvider(
         return Task.FromResult<AuthorizationResult?>(new()
         {
             Code = queryParams["code"],
+            State = queryParams["state"],
             Iss = queryParams["iss"],
         });
     }
@@ -687,10 +692,11 @@ private async Task<string> InitiateAuthorizationCodeFlowAsync(
         AuthorizationServerMetadata authServerMetadata,
         CancellationToken cancellationToken)
     {
-        var codeVerifier = GenerateCodeVerifier();
+        var codeVerifier = GenerateRandomBase64UrlValue();
         var codeChallenge = GenerateCodeChallenge(codeVerifier);
+        var state = GenerateRandomBase64UrlValue();
 
-        var authUrl = BuildAuthorizationUrl(protectedResourceMetadata, authServerMetadata, codeChallenge);
+        var authUrl = BuildAuthorizationUrl(protectedResourceMetadata, authServerMetadata, codeChallenge, state);
 
         var authResult = await _authorizationCallbackHandler(
             new AuthorizationCallbackContext
@@ -700,9 +706,19 @@ private async Task<string> InitiateAuthorizationCodeFlowAsync(
             },
             cancellationToken).ConfigureAwait(false);
 
-        if (authResult is null || string.IsNullOrEmpty(authResult.Code))
+        if (authResult is null)
         {
-            ThrowFailedToHandleUnauthorizedResponse($"The {nameof(ClientOAuthOptions.AuthorizationCallbackHandler)} returned a null or empty authorization code.");
+            ThrowFailedToHandleUnauthorizedResponse($"The {nameof(ClientOAuthOptions.AuthorizationCallbackHandler)} returned a null authorization result.");
+        }
+
+        if (_validateAuthorizationResponseState)
+        {
+            ValidateStateResponse(authResult!.State, state);
+        }
+
+        if (string.IsNullOrEmpty(authResult.Code))
+        {
+            ThrowFailedToHandleUnauthorizedResponse("The authorization callback returned a null or empty authorization code.");
         }
 
         if (_validateAuthorizationResponseIssuer)
@@ -721,7 +737,8 @@ private async Task<string> InitiateAuthorizationCodeFlowAsync(
     private Uri BuildAuthorizationUrl(
         ProtectedResourceMetadata protectedResourceMetadata,
         AuthorizationServerMetadata authServerMetadata,
-        string codeChallenge)
+        string codeChallenge,
+        string state)
     {
         var resourceUri = GetResourceUri(protectedResourceMetadata);
 
@@ -732,6 +749,7 @@ private Uri BuildAuthorizationUrl(
             ["response_type"] = "code",
             ["code_challenge"] = codeChallenge,
             ["code_challenge_method"] = "S256",
+            ["state"] = state,
         };
 
         if (resourceUri is not null)
@@ -1107,6 +1125,26 @@ private bool ChallengeIntroducesNewScopes(ProtectedResourceMetadata protectedRes
         return scope + " " + OfflineAccess;
     }
 
+    /// <summary>
+    /// Validates that an authorization response is bound to the transaction that initiated it.
+    /// </summary>
+    /// <param name="state">The state returned in the authorization response.</param>
+    /// <param name="expectedState">The state sent in the authorization request.</param>
+    private static void ValidateStateResponse(string? state, string expectedState)
+    {
+        if (string.IsNullOrEmpty(state))
+        {
+            ThrowFailedToHandleUnauthorizedResponse(
+                "The authorization response did not include the required state parameter.");
+        }
+
+        if (!string.Equals(state, expectedState, StringComparison.Ordinal))
+        {
+            ThrowFailedToHandleUnauthorizedResponse(
+                "The authorization response state did not match the state sent in the authorization request.");
+        }
+    }
+
     /// <summary>
     /// Validates the <c>iss</c> parameter from an authorization response per
     /// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>.
@@ -1378,7 +1416,7 @@ private async Task<ProtectedResourceMetadata> ExtractProtectedResourceMetadata(H
         yield return (new Uri($"{hostBase}{ProtectedResourceMetadataWellKnownPath}"), new Uri(hostBase));
     }
 
-    private static string GenerateCodeVerifier()
+    private static string GenerateRandomBase64UrlValue()
     {
 #if NET9_0_OR_GREATER
         Span<byte> bytes = stackalloc byte[32];

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -668,7 +668,10 @@ private void ConfigureInitialize(McpServerOptions options)
                     Instructions = options.ServerInstructions,
                     ServerInfo = options.ServerInfo ?? DefaultImplementation,
                     Capabilities = ServerCapabilities ?? new(),
-                    ResultType = "complete",
+
+                    // resultType is a 2026-07-28 result field. The initialize handshake is only available on
+                    // 2025-11-25 and earlier revisions (2026-07-28+ negotiate via server/discover and throw
+                    // above), so InitializeResult must never carry resultType (issue #1721).
                 };
             },
             McpJsonUtilities.JsonContext.Default.InitializeRequestParams,
@@ -1693,8 +1696,12 @@ private void ConfigureLogging(McpServerOptions options)
                     return InvokeHandlerAsync(setLoggingLevelHandler, request!, jsonRpcRequest, cancellationToken);
                 }
 
-                // Otherwise, consider it handled.
-                return new ValueTask<EmptyResult>(EmptyResult.Instance);
+                // Otherwise, consider it handled. logging/setLevel is a legacy (<= 2025-11-25) method
+                // (2026-07-28+ is rejected above), so the response must not carry the 2026-07-28 resultType
+                // field. Return a fresh EmptyResult rather than the shared EmptyResult.Instance, which is
+                // pre-stamped with resultType="complete" for the 2026-07-28-only subscriptions/listen path
+                // (issue #1721).
+                return new ValueTask<EmptyResult>(new EmptyResult());
             },
             McpJsonUtilities.JsonContext.Default.SetLevelRequestParams,
             McpJsonUtilities.JsonContext.Default.EmptyResult);
@@ -1765,7 +1772,11 @@ private void SetHandler<TParams, TResult>(
             handler = async (request, cancellationToken) =>
             {
                 var result = await innerHandler(request, cancellationToken).ConfigureAwait(false);
-                if (result is ICacheableResult cacheable)
+
+                // ttlMs and cacheScope are 2026-07-28 result fields; only stamp them when the request
+                // was negotiated under that revision or later. Earlier revisions (e.g. 2025-11-25) reject
+                // these as unrecognized keys (issue #1721).
+                if (result is ICacheableResult cacheable && IsJuly2026OrLaterProtocolRequest(request.JsonRpcRequest))
                 {
                     cacheable.TimeToLive ??= TimeSpan.Zero;
                     cacheable.CacheScope ??= CacheScope.Private;
@@ -1781,7 +1792,12 @@ private void SetHandler<TParams, TResult>(
             handler = async (request, cancellationToken) =>
             {
                 var result = await innerHandler(request, cancellationToken).ConfigureAwait(false);
-                if (result is Result protocolResult && protocolResult.ResultType is null)
+
+                // resultType is a 2026-07-28 result field; only stamp it when the request was negotiated
+                // under that revision or later. Earlier revisions (e.g. 2025-11-25) reject it as an
+                // unrecognized key (issue #1721).
+                if (result is Result protocolResult && protocolResult.ResultType is null &&
+                    IsJuly2026OrLaterProtocolRequest(request.JsonRpcRequest))
                 {
                     protocolResult.ResultType = "complete";
                 }
@@ -1808,7 +1824,12 @@ private void SetWithAlternateHandler<TParams, TResult>(
         handler = async (request, cancellationToken) =>
         {
             var result = await innerHandler(request, cancellationToken).ConfigureAwait(false);
-            if (!result.IsAlternate && result.Result is { ResultType: null } immediateResult)
+
+            // resultType is a 2026-07-28 result field; only stamp it when the request was negotiated
+            // under that revision or later. Earlier revisions (e.g. 2025-11-25) reject it as an
+            // unrecognized key (issue #1721).
+            if (!result.IsAlternate && result.Result is { ResultType: null } immediateResult &&
+                IsJuly2026OrLaterProtocolRequest(request.JsonRpcRequest))
             {
                 immediateResult.ResultType = "complete";
             }

src/ModelContextProtocol.Extensions.Tasks/Server/McpTaskExecutionMode.cs

@@ -0,0 +1,16 @@
+namespace ModelContextProtocol.Extensions.Tasks;
+
+/// <summary>
+/// Specifies how a tool call participates in the MCP Tasks extension.
+/// </summary>
+public enum McpTaskExecutionMode
+{
+    /// <summary>The tool always executes synchronously.</summary>
+    Synchronous,
+
+    /// <summary>The tool executes as a task when the client declares the Tasks extension.</summary>
+    Optional,
+
+    /// <summary>The tool requires the client to declare the Tasks extension.</summary>
+    Required,
+}