Merge branch 'main' into dependabot/nuget/Microsoft.Extensions.AI-10.6.0

Author: jozkee

docs/concepts/tasks/tasks.md

@@ -13,7 +13,7 @@ uid: tasks
 
 The Model Context Protocol (MCP) supports [task-based execution] for long-running operations. Tasks enable a "call-now, fetch-later" pattern where clients can initiate operations that may take significant time to complete, then poll for status and retrieve results when ready.
 
-[task-based execution]: https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks
+[task-based execution]: https://modelcontextprotocol.io/seps/1686-tasks
 
 ## Overview
 
@@ -601,4 +601,4 @@ While this file-based approach demonstrates the pattern, production systems shou
 - <xref:ModelContextProtocol.InMemoryMcpTaskStore>
 - <xref:ModelContextProtocol.Protocol.McpTask>
 - <xref:ModelContextProtocol.Protocol.McpTaskStatus>
-- [MCP Tasks Specification](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks)
+- [MCP Tasks Specification](https://modelcontextprotocol.io/seps/1686-tasks)

docs/concepts/tools/tools.md

@@ -340,3 +340,50 @@ Rules and constraints:
 - Values containing non-ASCII characters, control characters, or leading/trailing whitespace are Base64-encoded using the `=?base64?{value}?=` wrapper.
 - Header names must be case-insensitively unique within the tool's input schema.
 - Header validation is enforced only for protocol versions that support the HTTP Standardization feature (currently `DRAFT-2026-v1` and later).
+
+### Pre-loading tool definitions on the client
+
+By default, `Mcp-Param-*` headers are sent only for tools discovered via <xref:ModelContextProtocol.Client.McpClient.ListToolsAsync*>. If a client already has tool schema information (for example, from a previous session, hardcoded configuration, or an out-of-band source), it can pre-load those definitions so that headers are sent immediately—without a round trip to the server.
+
+```csharp
+// Build the tool definition with x-mcp-header annotations
+var tool = new Tool
+{
+    Name = "execute_sql",
+    InputSchema = JsonDocument.Parse("""
+        {
+            "type": "object",
+            "properties": {
+                "region": {
+                    "type": "string",
+                    "x-mcp-header": "Region"
+                },
+                "query": {
+                    "type": "string"
+                }
+            }
+        }
+        """).RootElement.Clone(),
+};
+
+// Pre-load the tool definition — no ListToolsAsync needed
+client.AddKnownTools([tool]);
+
+// This call now sends an Mcp-Param-Region header automatically
+var result = await client.CallToolAsync("execute_sql",
+    new Dictionary<string, object?> { ["region"] = "us-west-2", ["query"] = "SELECT 1" });
+```
+
+Known tools survive <xref:ModelContextProtocol.Client.McpClient.ListToolsAsync*> cache clears—they remain in the cache even when the server's tool list is refreshed. If the server returns a tool with the same name, the server's definition overwrites the cached one, but the tool keeps its known status.
+
+To remove known tools, use <xref:ModelContextProtocol.Client.McpClient.RemoveKnownTools*> for specific tools or <xref:ModelContextProtocol.Client.McpClient.ClearKnownTools*> to remove all:
+
+```csharp
+// Remove specific known tools by name
+client.RemoveKnownTools(["execute_sql"]);
+
+// Or remove all known tools at once
+client.ClearKnownTools();
+```
+
+All tools passed to <xref:ModelContextProtocol.Client.McpClient.AddKnownTools*> are validated for correct `x-mcp-header` annotations. If any tool in the batch fails validation, an <xref:System.ArgumentException> is thrown and no tools are added (all-or-nothing).

docs/list-of-diagnostics.md

@@ -23,7 +23,7 @@ If you use experimental APIs, you will get one of the diagnostics shown below. T
 
 | Diagnostic ID | Description |
 | :------------ | :---------- |
-| `MCPEXP001` | Experimental APIs for features in the MCP specification itself, including Tasks and Extensions. Tasks provide a mechanism for asynchronous long-running operations that can be polled for status and results (see [MCP Tasks specification](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks)). Extensions provide a framework for extending the Model Context Protocol while maintaining interoperability (see [SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)). |
+| `MCPEXP001` | Experimental APIs for features in the MCP specification itself, including Tasks and Extensions. Tasks provide a mechanism for asynchronous long-running operations that can be polled for status and results (see [MCP Tasks specification](https://modelcontextprotocol.io/seps/1686-tasks)). Extensions provide a framework for extending the Model Context Protocol while maintaining interoperability (see [SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)). |
 | `MCPEXP002` | Experimental SDK APIs unrelated to the MCP specification itself, including subclassing `McpClient`/`McpServer` (see [#1363](https://github.com/modelcontextprotocol/csharp-sdk/pull/1363)) and `RunSessionHandler`, which may be removed or change signatures in a future release (consider using `ConfigureSessionOptions` instead). |
 
 ## Obsolete APIs

src/Common/McpHttpHeaders.cs

@@ -75,4 +75,12 @@ internal static class McpHttpHeaders
     /// </summary>
     public static bool SupportsStandardHeaders(string? protocolVersion)
         => !string.IsNullOrEmpty(protocolVersion) && s_versionsWithStandardHeaders.Contains(protocolVersion!);
+
+    /// <summary>
+    /// Returns <see langword="true"/> if the negotiated protocol version reports unresolvable
+    /// resource URIs with the standard JSON-RPC <see cref="McpErrorCode.InvalidParams"/> (-32602)
+    /// rather than the legacy <see cref="McpErrorCode.ResourceNotFound"/> (-32002).
+    /// </summary>
+    internal static bool UseInvalidParamsForMissingResource(string? protocolVersion)
+        => string.Equals(protocolVersion, MinVersionForStandardHeaders, StringComparison.Ordinal);
 }

src/ModelContextProtocol.Core/Authentication/ClientOAuthOptions.cs

@@ -35,19 +35,40 @@ public sealed class ClientOAuthOptions
     public Uri? ClientMetadataDocumentUri { get; set; }
 
     /// <summary>
-    /// Gets or sets the OAuth scopes to request.
+    /// Gets or sets the OAuth scopes to request as a fallback.
     /// </summary>
     /// <remarks>
     /// <para>
-    /// When specified, these scopes will be used instead of the scopes advertised by the protected resource.
-    /// If not specified, the provider will use the scopes from the protected resource metadata.
+    /// These scopes are used only when the server does not provide scope information via the
+    /// WWW-Authenticate header or Protected Resource Metadata (<c>scopes_supported</c>). This
+    /// matches the MCP scope selection strategy: WWW-Authenticate scope → PRM scopes_supported →
+    /// client-configured scopes → omit scope parameter.
     /// </para>
     /// <para>
-    /// Common OAuth scopes include "openid", "profile", and "email".
+    /// To filter or customize scopes when the server <em>does</em> provide scope information,
+    /// use <see cref="ScopeSelector"/> instead.
     /// </para>
     /// </remarks>
     public IEnumerable<string>? Scopes { get; set; }
 
+    /// <summary>
+    /// Gets or sets a delegate that selects or filters the OAuth scopes to request.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When set, this delegate is called after the MCP scope selection strategy has determined the
+    /// candidate scopes (WWW-Authenticate → PRM <c>scopes_supported</c> → <see cref="Scopes"/> fallback)
+    /// and after <c>offline_access</c> has been automatically appended when advertised by the
+    /// authorization server. The return value replaces the candidate scopes in the authorization request.
+    /// </para>
+    /// <para>
+    /// Use this to request only a subset of the scopes offered by the server, or to append a custom
+    /// scope that is not advertised in the server metadata. Return <see langword="null"/> or an empty
+    /// enumerable to omit the <c>scope</c> parameter entirely.
+    /// </para>
+    /// </remarks>
+    public ScopeSelectorDelegate? ScopeSelector { get; set; }
+
     /// <summary>
     /// Gets or sets the authorization redirect delegate for handling the OAuth authorization flow.
     /// </summary>

src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs

@@ -28,6 +28,7 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
     private readonly Uri _serverUrl;
     private readonly Uri _redirectUri;
     private readonly string? _configuredScopes;
+    private readonly ScopeSelectorDelegate? _scopeSelector;
     private readonly IDictionary<string, string> _additionalAuthorizationParameters;
     private readonly Func<IReadOnlyList<Uri>, Uri?> _authServerSelector;
     private readonly AuthorizationRedirectDelegate _authorizationRedirectDelegate;
@@ -76,6 +77,7 @@ public ClientOAuthProvider(
         _clientSecret = options.ClientSecret;
         _redirectUri = options.RedirectUri ?? throw new ArgumentException("ClientOAuthOptions.RedirectUri must configured.", nameof(options));
         _configuredScopes = options.Scopes is null ? null : string.Join(" ", options.Scopes);
+        _scopeSelector = options.ScopeSelector;
         _additionalAuthorizationParameters = options.AdditionalAuthorizationParameters;
         _clientMetadataDocumentUri = options.ClientMetadataDocumentUri;
 
@@ -491,7 +493,7 @@ private Uri BuildAuthorizationUrl(
             queryParamsDictionary["resource"] = resourceUri;
         }
 
-        var scope = GetScopeParameter(protectedResourceMetadata);
+        var scope = ComputeEffectiveScope(protectedResourceMetadata, authServerMetadata);
         if (!string.IsNullOrEmpty(scope))
         {
             queryParamsDictionary["scope"] = scope!;
@@ -653,7 +655,7 @@ private async Task PerformDynamicClientRegistrationAsync(
             TokenEndpointAuthMethod = "client_secret_post",
             ClientName = _dcrClientName,
             ClientUri = _dcrClientUri?.ToString(),
-            Scope = GetScopeParameter(protectedResourceMetadata),
+            Scope = ComputeEffectiveScope(protectedResourceMetadata, authServerMetadata),
         };
 
         var requestBytes = JsonSerializer.SerializeToUtf8Bytes(registrationRequest, McpJsonUtilities.JsonContext.Default.DynamicClientRegistrationRequest);
@@ -712,6 +714,20 @@ private async Task PerformDynamicClientRegistrationAsync(
     private static string? GetResourceUri(ProtectedResourceMetadata protectedResourceMetadata)
         => protectedResourceMetadata.Resource;
 
+    private string? ComputeEffectiveScope(
+        ProtectedResourceMetadata protectedResourceMetadata,
+        AuthorizationServerMetadata authServerMetadata)
+    {
+        var scope = GetScopeParameter(protectedResourceMetadata);
+        scope = AugmentScopeWithOfflineAccess(scope, authServerMetadata);
+        if (_scopeSelector is not null)
+        {
+            var selected = _scopeSelector(scope?.Split(' '));
+            scope = selected is not null ? string.Join(" ", selected) : null;
+        }
+        return scope;
+    }
+
     private string? GetScopeParameter(ProtectedResourceMetadata protectedResourceMetadata)
     {
         if (!string.IsNullOrEmpty(protectedResourceMetadata.WwwAuthenticateScope))
@@ -726,6 +742,37 @@ private async Task PerformDynamicClientRegistrationAsync(
         return _configuredScopes;
     }
 
+    /// <summary>
+    /// Augments the scope parameter with <c>offline_access</c> if the authorization server advertises it in
+    /// <c>scopes_supported</c> and it is not already present. This signals to OIDC-flavored authorization servers
+    /// that the client desires a refresh token, per SEP-2207.
+    /// </summary>
+    private static string? AugmentScopeWithOfflineAccess(string? scope, AuthorizationServerMetadata authServerMetadata)
+    {
+        const string OfflineAccess = "offline_access";
+
+        if (authServerMetadata.ScopesSupported?.Contains(OfflineAccess) is not true)
+        {
+            return scope;
+        }
+
+        if (scope is null)
+        {
+            return OfflineAccess;
+        }
+
+        // Check if offline_access is already in the scope string (space-separated tokens).
+        foreach (var token in scope.Split(' '))
+        {
+            if (token == OfflineAccess)
+            {
+                return scope;
+            }
+        }
+
+        return scope + " " + OfflineAccess;
+    }
+
     /// <summary>
     /// Verifies that the resource URI in the metadata exactly matches the original request URL as required by the RFC.
     /// Per RFC: The resource value must be identical to the URL that the client used to make the request to the resource server.

src/ModelContextProtocol.Core/Authentication/ScopeSelectorDelegate.cs

@@ -0,0 +1,37 @@
+
+namespace ModelContextProtocol.Authentication;
+
+/// <summary>
+/// Represents a method that selects or filters the OAuth scopes to request during authorization.
+/// </summary>
+/// <param name="scope">
+/// The scopes determined by the MCP scope selection strategy (WWW-Authenticate header scope →
+/// <c>scopes_supported</c> from Protected Resource Metadata → <see cref="ClientOAuthOptions.Scopes"/>
+/// fallback), with <c>offline_access</c> appended when advertised by the authorization server. May be
+/// <see langword="null"/> if the server provided no scope information and no fallback scopes are configured.
+/// </param>
+/// <returns>
+/// The scopes to include in the authorization and Dynamic Client Registration requests. Return
+/// <see langword="null"/> or an empty enumerable to omit the <c>scope</c> parameter entirely.
+/// </returns>
+/// <remarks>
+/// <para>
+/// Use this delegate to filter or customize the proposed scopes before the authorization request is made.
+/// Common scenarios include:
+/// </para>
+/// <list type="bullet">
+/// <item><description>Requesting only a subset of the scopes offered by the server.</description></item>
+/// <item><description>Appending a custom scope not advertised in the server metadata.</description></item>
+/// </list>
+/// <para>
+/// The MCP specification defines the following scope selection priority (highest to lowest):
+/// WWW-Authenticate header scope → PRM <c>scopes_supported</c> → omit scope parameter. The
+/// <paramref name="scope"/> parameter already reflects this priority. The delegate runs after
+/// <c>offline_access</c> has been auto-appended, so it can also remove that scope if desired.
+/// </para>
+/// <para>
+/// The resolved scope is applied consistently to both the authorization URL and the Dynamic Client
+/// Registration (DCR) request, so the registered client scope matches what is actually requested.
+/// </para>
+/// </remarks>
+public delegate IEnumerable<string>? ScopeSelectorDelegate(IReadOnlyCollection<string>? scope);

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -70,4 +70,84 @@ protected McpClient()
     /// </para>
     /// </remarks>
     public abstract Task<ClientCompletionDetails> Completion { get; }
+
+    /// <summary>
+    /// Registers one or more tool definitions in the client's tool cache, enabling the transport
+    /// to send <c>Mcp-Param-*</c> headers for those tools without requiring a prior <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/> call.
+    /// </summary>
+    /// <param name="tools">The tool definitions to register.</param>
+    /// <remarks>
+    /// <para>
+    /// This method allows callers who already have tool schema information (e.g., from a previous session,
+    /// hardcoded configuration, or an out-of-band source) to provide it directly to the client. Once registered,
+    /// any <see cref="McpClient.CallToolAsync(string, IReadOnlyDictionary{string, object?}?, IProgress{ProgressNotificationValue}?, RequestOptions?, CancellationToken)"/>
+    /// call for a registered tool will automatically include <c>Mcp-Param-*</c> HTTP headers based on
+    /// the tool's <c>x-mcp-header</c> schema annotations, exactly as if the tool had been discovered
+    /// via <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>.
+    /// </para>
+    /// <para>
+    /// <b>Cache interaction behavior:</b>
+    /// <list type="bullet">
+    ///   <item>Registered tools are added to the same internal tool cache used by <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>.</item>
+    ///   <item>Calling <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/> after <see cref="AddKnownTools"/> preserves
+    ///     manually registered tools — only server-discovered tools are cleared and repopulated.</item>
+    ///   <item>If the server returns a tool with the same name as a manually registered tool, the server's
+    ///     definition overwrites the registered one in the cache, but the tool retains its known status
+    ///     and will survive subsequent cache clears. This registration is sticky for the lifetime of the
+    ///     <see cref="McpClient"/>; use <see cref="RemoveKnownTools"/> or <see cref="ClearKnownTools"/> to
+    ///     explicitly drop known tools that are no longer needed.</item>
+    ///   <item>Tools can be registered at any time — before or after <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>,
+    ///     and across multiple calls.</item>
+    ///   <item>Re-registering a tool with the same name overwrites the previous definition in the cache (last write wins).</item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// Tools with invalid <c>x-mcp-header</c> annotations cause an <see cref="ArgumentException"/> to be thrown.
+    /// No tools are added to the cache if any tool in the batch fails validation (all-or-nothing).
+    /// </para>
+    /// </remarks>
+    /// <exception cref="ArgumentNullException"><paramref name="tools"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException">One or more tools have invalid <c>x-mcp-header</c> annotations.</exception>
+    public virtual void AddKnownTools(IEnumerable<Tool> tools)
+    {
+        Throw.IfNull(tools);
+        throw new NotSupportedException($"{GetType().Name} does not support adding known tools.");
+    }
+
+    /// <summary>
+    /// Removes one or more previously registered tool definitions from the client's tool cache by name.
+    /// </summary>
+    /// <param name="toolNames">The names of the tools to remove.</param>
+    /// <remarks>
+    /// <para>
+    /// This removes the specified tools from both the known-tools set and the internal tool cache.
+    /// After removal, those tools will no longer survive <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>
+    /// cache clears, and <c>Mcp-Param-*</c> headers will no longer be sent for them unless the server
+    /// re-discovers them via <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/>.
+    /// </para>
+    /// <para>
+    /// Removing a tool name that was not previously added via <see cref="AddKnownTools"/> is a no-op.
+    /// </para>
+    /// </remarks>
+    /// <exception cref="ArgumentNullException"><paramref name="toolNames"/> is <see langword="null"/>.</exception>
+    public virtual void RemoveKnownTools(IEnumerable<string> toolNames)
+    {
+        Throw.IfNull(toolNames);
+        throw new NotSupportedException($"{GetType().Name} does not support removing known tools.");
+    }
+
+    /// <summary>
+    /// Removes all previously registered tool definitions from the client's tool cache.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This clears all tools that were added via <see cref="AddKnownTools"/> from both the known-tools
+    /// set and the internal tool cache. Server-discovered tools that are not also known tools are not affected
+    /// and will remain in the cache until the next <see cref="McpClient.ListToolsAsync(RequestOptions?, CancellationToken)"/> call.
+    /// </para>
+    /// </remarks>
+    public virtual void ClearKnownTools()
+    {
+        throw new NotSupportedException($"{GetType().Name} does not support clearing known tools.");
+    }
 }