Add built-in server-side support for incremental scope consent (SEP-835)

Agent-Logs-Url: https://github.com/modelcontextprotocol/csharp-sdk/sessions/5671ae62-779a-42f5-b84c-77d470131732

Co-authored-by: mikekistler <85643503+mikekistler@users.noreply.github.com>

Author: Copilot

src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs

@@ -30,15 +30,6 @@ public void Configure(McpServerOptions options)
 
     public void PostConfigure(string? name, McpServerOptions options)
     {
-        CheckListToolsFilter(options);
-        CheckCallToolFilter(options);
-
-        CheckListResourcesFilter(options);
-        CheckListResourceTemplatesFilter(options);
-        CheckReadResourceFilter(options);
-
-        CheckListPromptsFilter(options);
-        CheckGetPromptFilter(options);
     }
 
     private void ConfigureListToolsFilter(McpServerOptions options)
@@ -59,26 +50,6 @@ await FilterAuthorizedItemsAsync(
         });
     }
 
-    private static void CheckListToolsFilter(McpServerOptions options)
-    {
-        options.Filters.Request.ListToolsFilters.Add(next =>
-        {
-            var toolCollection = options.ToolCollection;
-            return async (context, cancellationToken) =>
-            {
-                var result = await next(context, cancellationToken);
-
-                if (HasAuthorizationMetadata(result.Tools.Select(tool => toolCollection is not null && toolCollection.TryGetPrimitive(tool.Name, out var serverTool) ? serverTool : null))
-                    && !context.Items.ContainsKey(AuthorizationFilterInvokedKey))
-                {
-                    throw new InvalidOperationException("Authorization filter was not invoked for tools/list operation, but authorization metadata was found on the tools. Ensure that AddAuthorizationFilters() is called on the IMcpServerBuilder to configure authorization filters.");
-                }
-
-                return result;
-            };
-        });
-    }
-
     private void ConfigureCallToolFilter(McpServerOptions options)
     {
         options.Filters.Request.CallToolFilters.Add(next => async (context, cancellationToken) =>
@@ -95,20 +66,6 @@ private void ConfigureCallToolFilter(McpServerOptions options)
         });
     }
 
-    private static void CheckCallToolFilter(McpServerOptions options)
-    {
-        options.Filters.Request.CallToolFilters.Add(next => async (context, cancellationToken) =>
-        {
-            if (HasAuthorizationMetadata(context.MatchedPrimitive)
-                && !context.Items.ContainsKey(AuthorizationFilterInvokedKey))
-            {
-                throw new InvalidOperationException("Authorization filter was not invoked for tools/call operation, but authorization metadata was found on the tool. Ensure that AddAuthorizationFilters() is called on the IMcpServerBuilder to configure authorization filters.");
-            }
-
-            return await next(context, cancellationToken);
-        });
-    }
-
     private void ConfigureListResourcesFilter(McpServerOptions options)
     {
         options.Filters.Request.ListResourcesFilters.Add(next =>
@@ -127,26 +84,6 @@ await FilterAuthorizedItemsAsync(
         });
     }
 
-    private static void CheckListResourcesFilter(McpServerOptions options)
-    {
-        options.Filters.Request.ListResourcesFilters.Add(next =>
-        {
-            var resourceCollection = options.ResourceCollection;
-            return async (context, cancellationToken) =>
-            {
-                var result = await next(context, cancellationToken);
-
-                if (HasAuthorizationMetadata(result.Resources.Select(resource => resourceCollection is not null && resourceCollection.TryGetPrimitive(resource.Uri, out var serverResource) ? serverResource : null))
-                    && !context.Items.ContainsKey(AuthorizationFilterInvokedKey))
-                {
-                    throw new InvalidOperationException("Authorization filter was not invoked for resources/list operation, but authorization metadata was found on the resources. Ensure that AddAuthorizationFilters() is called on the IMcpServerBuilder to configure authorization filters.");
-                }
-
-                return result;
-            };
-        });
-    }
-
     private void ConfigureListResourceTemplatesFilter(McpServerOptions options)
     {
         options.Filters.Request.ListResourceTemplatesFilters.Add(next =>
@@ -165,26 +102,6 @@ await FilterAuthorizedItemsAsync(
         });
     }
 
-    private static void CheckListResourceTemplatesFilter(McpServerOptions options)
-    {
-        options.Filters.Request.ListResourceTemplatesFilters.Add(next =>
-        {
-            var resourceCollection = options.ResourceCollection;
-            return async (context, cancellationToken) =>
-            {
-                var result = await next(context, cancellationToken);
-
-                if (HasAuthorizationMetadata(result.ResourceTemplates.Select(resourceTemplate => resourceCollection is not null && resourceCollection.TryGetPrimitive(resourceTemplate.UriTemplate, out var serverResource) ? serverResource : null))
-                    && !context.Items.ContainsKey(AuthorizationFilterInvokedKey))
-                {
-                    throw new InvalidOperationException("Authorization filter was not invoked for resources/templates/list operation, but authorization metadata was found on the resource templates. Ensure that AddAuthorizationFilters() is called on the IMcpServerBuilder to configure authorization filters.");
-                }
-
-                return result;
-            };
-        });
-    }
-
     private void ConfigureReadResourceFilter(McpServerOptions options)
     {
         options.Filters.Request.ReadResourceFilters.Add(next => async (context, cancellationToken) =>
@@ -201,20 +118,6 @@ private void ConfigureReadResourceFilter(McpServerOptions options)
         });
     }
 
-    private static void CheckReadResourceFilter(McpServerOptions options)
-    {
-        options.Filters.Request.ReadResourceFilters.Add(next => async (context, cancellationToken) =>
-        {
-            if (HasAuthorizationMetadata(context.MatchedPrimitive)
-                && !context.Items.ContainsKey(AuthorizationFilterInvokedKey))
-            {
-                throw new InvalidOperationException("Authorization filter was not invoked for resources/read operation, but authorization metadata was found on the resource. Ensure that AddAuthorizationFilters() is called on the IMcpServerBuilder to configure authorization filters.");
-            }
-
-            return await next(context, cancellationToken);
-        });
-    }
-
     private void ConfigureListPromptsFilter(McpServerOptions options)
     {
         options.Filters.Request.ListPromptsFilters.Add(next =>
@@ -233,26 +136,6 @@ await FilterAuthorizedItemsAsync(
         });
     }
 
-    private static void CheckListPromptsFilter(McpServerOptions options)
-    {
-        options.Filters.Request.ListPromptsFilters.Add(next =>
-        {
-            var promptCollection = options.PromptCollection;
-            return async (context, cancellationToken) =>
-            {
-                var result = await next(context, cancellationToken);
-
-                if (HasAuthorizationMetadata(result.Prompts.Select(prompt => promptCollection is not null && promptCollection.TryGetPrimitive(prompt.Name, out var serverPrompt) ? serverPrompt : null))
-                    && !context.Items.ContainsKey(AuthorizationFilterInvokedKey))
-                {
-                    throw new InvalidOperationException("Authorization filter was not invoked for prompts/list operation, but authorization metadata was found on the prompts. Ensure that AddAuthorizationFilters() is called on the IMcpServerBuilder to configure authorization filters.");
-                }
-
-                return result;
-            };
-        });
-    }
-
     private void ConfigureGetPromptFilter(McpServerOptions options)
     {
         options.Filters.Request.GetPromptFilters.Add(next => async (context, cancellationToken) =>
@@ -269,20 +152,6 @@ private void ConfigureGetPromptFilter(McpServerOptions options)
         });
     }
 
-    private static void CheckGetPromptFilter(McpServerOptions options)
-    {
-        options.Filters.Request.GetPromptFilters.Add(next => async (context, cancellationToken) =>
-        {
-            if (HasAuthorizationMetadata(context.MatchedPrimitive)
-                && !context.Items.ContainsKey(AuthorizationFilterInvokedKey))
-            {
-                throw new InvalidOperationException("Authorization filter was not invoked for prompts/get operation, but authorization metadata was found on the prompt. Ensure that AddAuthorizationFilters() is called on the IMcpServerBuilder to configure authorization filters.");
-            }
-
-            return await next(context, cancellationToken);
-        });
-    }
-
     /// <summary>
     /// Filters a collection of items based on authorization policies in their metadata.
     /// For list operations where we need to filter results by authorization.
@@ -338,7 +207,7 @@ private async ValueTask<AuthorizationResult> GetAuthorizationResultAsync(
     /// <param name="policyProvider">The authorization policy provider.</param>
     /// <param name="endpointMetadata">The endpoint metadata collection.</param>
     /// <returns>The combined authorization policy, or null if no authorization is required.</returns>
-    private static async ValueTask<AuthorizationPolicy?> CombineAsync(IAuthorizationPolicyProvider policyProvider, IReadOnlyList<object> endpointMetadata)
+    internal static async ValueTask<AuthorizationPolicy?> CombineAsync(IAuthorizationPolicyProvider policyProvider, IReadOnlyList<object> endpointMetadata)
     {
         // https://github.com/dotnet/aspnetcore/issues/63365 tracks adding this as public API to AuthorizationPolicy itself.
         // Copied from https://github.com/dotnet/aspnetcore/blob/9f2977bf9cfb539820983bda3bedf81c8cda9f20/src/Security/Authorization/Policy/src/AuthorizationMiddleware.cs#L116-L138
@@ -374,7 +243,7 @@ private async ValueTask<AuthorizationResult> GetAuthorizationResultAsync(
             : AuthorizationPolicy.Combine(policy, reqPolicyBuilder.Build());
     }
 
-    private static bool HasAuthorizationMetadata([NotNullWhen(true)] IMcpServerPrimitive? primitive)
+    internal static bool HasAuthorizationMetadata([NotNullWhen(true)] IMcpServerPrimitive? primitive)
     {
         // If no primitive was found for this request or there is IAllowAnonymous metadata anywhere on the class or method,
         // the request should go through as normal.
@@ -385,7 +254,4 @@ private static bool HasAuthorizationMetadata([NotNullWhen(true)] IMcpServerPrimi
 
         return primitive.Metadata.Any(static m => m is IAuthorizeData or AuthorizationPolicy or IAuthorizationRequirementData);
     }
-
-    private static bool HasAuthorizationMetadata(IEnumerable<IMcpServerPrimitive?> primitives)
-        => primitives.Any(HasAuthorizationMetadata);
-}
+}

src/ModelContextProtocol.AspNetCore/HttpMcpServerBuilderExtensions.cs

@@ -64,6 +64,10 @@ public static IMcpServerBuilder AddAuthorizationFilters(this IMcpServerBuilder b
         // Allow the authorization filters to get added multiple times in case other middleware changes the matched primitive.
         builder.Services.AddTransient<IConfigureOptions<McpServerOptions>, AuthorizationFilterSetup>();
 
+        // Signal to the HTTP transport that authorization filters are handling access control,
+        // so the pre-flight incremental scope consent check (SEP-835) should be skipped.
+        builder.Services.Configure<HttpServerTransportOptions>(static o => o.AuthorizationFiltersRegistered = true);
+
         return builder;
     }
 

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

@@ -188,4 +188,13 @@ public class HttpServerTransportOptions
     /// Gets or sets the time provider that's used for testing the <see cref="IdleTimeout"/>.
     /// </summary>
     public TimeProvider TimeProvider { get; set; } = TimeProvider.System;
+
+    /// <summary>
+    /// Gets a value indicating whether authorization filters have been registered via
+    /// <c>AddAuthorizationFilters</c>.
+    /// When <see langword="true"/>, the MCP filter pipeline handles authorization (hiding unauthorized primitives and returning MCP errors).
+    /// When <see langword="false"/> (the default), the HTTP transport performs a pre-flight authorization check that returns
+    /// HTTP 403 with <c>WWW-Authenticate: Bearer error="insufficient_scope"</c> for incremental scope consent (SEP-835).
+    /// </summary>
+    internal bool AuthorizationFiltersRegistered { get; set; }
 }

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -1,6 +1,8 @@
-using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Http.Features;
 using Microsoft.AspNetCore.WebUtilities;
+using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
@@ -41,6 +43,9 @@ internal sealed class StreamableHttpHandler(
 
     private static readonly JsonTypeInfo<JsonRpcMessage> s_messageTypeInfo = GetRequiredJsonTypeInfo<JsonRpcMessage>();
     private static readonly JsonTypeInfo<JsonRpcError> s_errorTypeInfo = GetRequiredJsonTypeInfo<JsonRpcError>();
+    private static readonly JsonTypeInfo<CallToolRequestParams> s_callToolParamsTypeInfo = GetRequiredJsonTypeInfo<CallToolRequestParams>();
+    private static readonly JsonTypeInfo<GetPromptRequestParams> s_getPromptParamsTypeInfo = GetRequiredJsonTypeInfo<GetPromptRequestParams>();
+    private static readonly JsonTypeInfo<ReadResourceRequestParams> s_readResourceParamsTypeInfo = GetRequiredJsonTypeInfo<ReadResourceRequestParams>();
 
     private static bool AllowNewSessionForNonInitializeRequests { get; } =
         AppContext.TryGetSwitch("ModelContextProtocol.AspNetCore.AllowNewSessionForNonInitializeRequests", out var enabled) && enabled;
@@ -87,6 +92,11 @@ await WriteJsonRpcErrorAsync(context,
 
         await using var _ = await session.AcquireReferenceAsync(context.RequestAborted);
 
+        if (await TryHandleInsufficientScopeAsync(context, session, message))
+        {
+            return;
+        }
+
         InitializeSseResponse(context);
         var wroteResponse = await session.Transport.HandlePostRequestAsync(message, context.Response.Body, context.RequestAborted);
         if (!wroteResponse)
@@ -463,6 +473,127 @@ private static Task WriteJsonRpcErrorAsync(HttpContext context, string errorMess
         return Results.Json(jsonRpcError, s_errorTypeInfo, statusCode: statusCode).ExecuteAsync(context);
     }
 
+    /// <summary>
+    /// Performs a pre-flight authorization check for invocation requests (tools/call, prompts/get, resources/read)
+    /// when <see cref="HttpMcpServerBuilderExtensions.AddAuthorizationFilters"/> has not been called.
+    /// If the request targets a primitive with <see cref="Microsoft.AspNetCore.Authorization.AuthorizeAttribute"/>
+    /// metadata and the caller is not authorized, writes an HTTP 403 response with a
+    /// <c>WWW-Authenticate: Bearer error="insufficient_scope"</c> header to trigger incremental scope consent (SEP-835).
+    /// </summary>
+    /// <returns><see langword="true"/> if a 403 response was written and request processing should stop; otherwise <see langword="false"/>.</returns>
+    private async ValueTask<bool> TryHandleInsufficientScopeAsync(HttpContext context, StreamableHttpSession session, JsonRpcMessage message)
+    {
+        // Only applicable when AddAuthorizationFilters has NOT been called.
+        // If it was called, the MCP filter pipeline handles authorization (hiding + MCP errors).
+        if (httpServerTransportOptions.Value.AuthorizationFiltersRegistered)
+        {
+            return false;
+        }
+
+        // Only handle invocation requests that target a specific primitive.
+        if (message is not JsonRpcRequest request)
+        {
+            return false;
+        }
+
+        var serverOptions = session.Server.ServerOptions;
+        IMcpServerPrimitive? primitive = null;
+
+        switch (request.Method)
+        {
+            case RequestMethods.ToolsCall:
+            {
+                var toolParams = request.Params is { } p ? System.Text.Json.JsonSerializer.Deserialize(p, s_callToolParamsTypeInfo) : null;
+                if (toolParams?.Name is { } toolName && serverOptions.ToolCollection is { } tools
+                    && tools.TryGetPrimitive(toolName, out var tool))
+                {
+                    primitive = tool;
+                }
+                break;
+            }
+            case RequestMethods.PromptsGet:
+            {
+                var promptParams = request.Params is { } p ? System.Text.Json.JsonSerializer.Deserialize(p, s_getPromptParamsTypeInfo) : null;
+                if (promptParams?.Name is { } promptName && serverOptions.PromptCollection is { } prompts
+                    && prompts.TryGetPrimitive(promptName, out var prompt))
+                {
+                    primitive = prompt;
+                }
+                break;
+            }
+            case RequestMethods.ResourcesRead:
+            {
+                var resourceParams = request.Params is { } p ? System.Text.Json.JsonSerializer.Deserialize(p, s_readResourceParamsTypeInfo) : null;
+                if (resourceParams?.Uri is { } resourceUri && serverOptions.ResourceCollection is { } resources)
+                {
+                    // First try an exact match, then fall back to URI template matching.
+                    if (resources.TryGetPrimitive(resourceUri, out var resource) && !resource.IsTemplated)
+                    {
+                        primitive = resource;
+                    }
+                    else
+                    {
+                        foreach (var resourceTemplate in resources)
+                        {
+                            if (resourceTemplate.IsMatch(resourceUri))
+                            {
+                                primitive = resourceTemplate;
+                                break;
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+            default:
+                return false;
+        }
+
+        if (!AuthorizationFilterSetup.HasAuthorizationMetadata(primitive))
+        {
+            return false;
+        }
+
+        // Evaluate the authorization policy for this primitive.
+        var policyProvider = context.RequestServices.GetService<IAuthorizationPolicyProvider>();
+        if (policyProvider is null)
+        {
+            // No authorization infrastructure configured; skip the pre-flight check.
+            return false;
+        }
+
+        var policy = await AuthorizationFilterSetup.CombineAsync(policyProvider, primitive.Metadata);
+        if (policy is null)
+        {
+            return false;
+        }
+
+        var authService = context.RequestServices.GetRequiredService<IAuthorizationService>();
+        var authResult = await authService.AuthorizeAsync(context.User ?? new ClaimsPrincipal(new ClaimsIdentity()), context, policy);
+        if (authResult.Succeeded)
+        {
+            return false;
+        }
+
+        // Authorization failed. Build a WWW-Authenticate header with error="insufficient_scope".
+        // Extract the scope from IAuthorizeData.Roles (the standard pattern for incremental scope consent).
+        var scope = primitive.Metadata
+            .OfType<IAuthorizeData>()
+            .Select(static a => a.Roles)
+            .FirstOrDefault(static r => !string.IsNullOrEmpty(r));
+
+        // Build the resource_metadata URL using the default well-known path for this endpoint.
+        var resourceMetadataUri = $"{context.Request.Scheme}://{context.Request.Host}{context.Request.PathBase}/.well-known/oauth-protected-resource{context.Request.Path}";
+
+        var wwwAuthenticate = string.IsNullOrEmpty(scope)
+            ? $"Bearer error=\"insufficient_scope\", resource_metadata=\"{resourceMetadataUri}\""
+            : $"Bearer error=\"insufficient_scope\", scope=\"{scope}\", resource_metadata=\"{resourceMetadataUri}\"";
+
+        context.Response.Headers[HeaderNames.WWWAuthenticate] = wwwAuthenticate;
+        await WriteJsonRpcErrorAsync(context, "Forbidden: Insufficient scope.", StatusCodes.Status403Forbidden, (int)McpErrorCode.InvalidRequest);
+        return true;
+    }
+
     internal static void InitializeSseResponse(HttpContext context)
     {
         context.Response.Headers.ContentType = "text/event-stream";