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

[mikekistler]

Summary

Add built-in server-side support for incremental scope consent (SEP-835) so that MCP servers can use [Authorize] on tools, prompts, and resources without calling AddAuthorizationFilters(), and the SDK automatically returns HTTP 403 with proper WWW-Authenticate headers to trigger client re-authentication.

The SDK already has full client-side support via ClientOAuthProvider, which handles 403 insufficient_scope challenges. This issue covers the missing server-side half.

Motivation

Currently, servers that want per-primitive authorization must call AddAuthorizationFilters(), which:

• Hides [Authorize]-decorated primitives from list results
• Returns JSON-RPC errors (within HTTP 200) for unauthorized invocations

Neither behavior works for incremental scope consent, which requires:

1. Primitives to be visible in listings so clients can discover them
2. Unauthorized invocations to return HTTP 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="...", resource_metadata="..." so the client can re-authenticate with broader scopes

Proposed Design

Usage Pattern

// Server setup — note: NO call to AddAuthorizationFilters()
builder.Services.AddMcpServer()
    .WithHttpTransport()
    .WithTools<MyTools>();

// Tool with scope requirement
[McpServerToolType]
public class MyTools
{
    [McpServerTool, Description("Reads a file")]
    [Authorize(Roles = "read_files")]
    public static async Task<string> ReadFile(string path, CancellationToken ct)
    {
        // ...
    }
}

How It Works

1. Server decorates primitives with [Authorize(Roles = "scope_name")] but does NOT call AddAuthorizationFilters()
2. AddAuthorizationFilters() is unchanged — servers that use it get the existing hide/block behavior
3. Primitives with [Authorize] are visible in listings (since the listing filter is not registered)
4. On invocation (tools/call, prompts/get, resources/read), a new pre-flight check in StreamableHttpHandler evaluates authorization before SSE streaming begins
5. If unauthorized → HTTP 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="scope_name", resource_metadata="..."
6. The client's ClientOAuthProvider handles the 403 → re-auth with new scope → retry

Why Pre-flight?

The auth check must happen before InitializeSseResponse because SSE response headers are committed (HTTP 200) before the MCP filter pipeline runs. Once headers are committed, the status code cannot be changed to 403.

HandlePostRequestAsync (current):
  InitializeSseResponse(context)              // Sets Content-Type: text/event-stream
  └─ session.Transport.HandlePostRequestAsync
       └─ responseStream.FlushAsync()         // ← COMMITS HEADERS AS 200
          MessageWriter.WriteAsync(message)   // Queues for session processing
          // Auth filter runs here — too late for HTTP 403

The pre-flight check inserts before InitializeSseResponse:

HandlePostRequestAsync (proposed):
  parse message, get session
  TryHandleInsufficientScopeAsync(...)        // NEW — can still write HTTP 403
  InitializeSseResponse(context)              // Only reached if auth passed
  session.Transport.HandlePostRequestAsync(...)

Implementation Plan

1. Relax Check filters in AuthorizationFilterSetup

The PostConfigure method registers "Check" filters that throw InvalidOperationException if auth metadata exists but AddAuthorizationFilters() wasn't called. These must be updated to allow the incremental consent path (HTTP transport handles auth at the HTTP level instead).

File: src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs

2. Pre-flight authorization in StreamableHttpHandler

Add TryHandleInsufficientScopeAsync in HandlePostRequestAsync:

1. Skip if AddAuthorizationFilters was called (let it handle auth its way)
2. For tools/call, prompts/get, resources/read requests: parse target name, look up primitive
3. Check IAuthorizeData metadata, evaluate IAuthorizationService
4. If unauthorized: extract scope from IAuthorizeData.Roles, write HTTP 403 with WWW-Authenticate header and JSON-RPC error body

File: src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

3. Tests

• [Authorize] primitives visible in listings without AddAuthorizationFilters
• Invocation returns HTTP 403 with proper WWW-Authenticate headers
• Authenticated user with sufficient claims can invoke successfully
• AddAuthorizationFilters behavior is unchanged

File: tests/ModelContextProtocol.AspNetCore.Tests/IncrementalConsentTests.cs (new)

4. Documentation

• XML doc comments on new/modified APIs
• Usage guide documenting the [Authorize(Roles = "scope")] pattern

Key Advantages

• No new types or attributes — reuses standard [Authorize(Roles = "...")]
• No breaking changes — AddAuthorizationFilters is untouched
• Clean separation — AddAuthorizationFilters = hide/block model; omitting it = incremental consent model
• WithHttpTransport() auto-registers — no extra API calls needed
• Works with existing client — ClientOAuthProvider already handles 403 insufficient_scope

Related

• SEP-835: SEP-835: Update authorization spec with default scopes definition modelcontextprotocol#835
• Original issue: SEP-835: Enhance authorization flows with incremental scope consent via WWW-Authenticate (SEP-835) #907 (closed — covered client-side; this covers server-side)
• Client-side implementation: ClientOAuthProvider.ShouldRetryWithNewAccessToken handles 403 insufficient_scope