Add middleware and authz support for server-side handlers

[halter73]

MCP Server Handler Filters

For each handler type in the MCP Server, there are corresponding AddXXXFilter methods in McpServerBuilderExtensions.cs that allow you to add filters to the handler pipeline. The filters are stored in McpServerOptions.Filters and applied during server configuration.

Available Filter Methods

The following filter methods are available:

• AddListResourceTemplatesFilter - Filter for list resource templates handlers
• AddListToolsFilter - Filter for list tools handlers
• AddCallToolFilter - Filter for call tool handlers
• AddListPromptsFilter - Filter for list prompts handlers
• AddGetPromptFilter - Filter for get prompt handlers
• AddListResourcesFilter - Filter for list resources handlers
• AddReadResourceFilter - Filter for read resource handlers
• AddCompleteFilter - Filter for completion handlers
• AddSubscribeToResourcesFilter - Filter for resource subscription handlers
• AddUnsubscribeFromResourcesFilter - Filter for resource unsubscription handlers
• AddSetLoggingLevelFilter - Filter for logging level handlers

Usage

Filters are functions that take a handler and return a new handler, allowing you to wrap the original handler with additional functionality:

services.AddMcpServer()
    .WithListToolsHandler(async (context, cancellationToken) =>
    {
        // Your base handler logic
        return new ListToolsResult { Tools = GetTools() };
    })
    .AddListToolsFilter(next => async (context, cancellationToken) =>
    {
        // Pre-processing logic
        Console.WriteLine("Before handler execution");

        var result = await next(context, cancellationToken);

        // Post-processing logic
        Console.WriteLine("After handler execution");
        return result;
    });

Filter Execution Order

services.AddMcpServer()
    .WithListToolsHandler(baseHandler)
    .AddListToolsFilter(filter1)  // Executes first (outermost)
    .AddListToolsFilter(filter2)  // Executes second
    .AddListToolsFilter(filter3); // Executes third (closest to handler)

Execution flow: filter1 -> filter2 -> filter3 -> baseHandler -> filter3 -> filter2 -> filter1

[Authorize] attribute support

When using the ASP.NET Core integration (ModelContextProtocol.AspNetCore), authorization filters are automatically configured by WithHttpTransport() that support [Authorize] and [AllowAnonymous] attributes on MCP server tools, prompts, and resources. Some of the attributes the MCP server automatically respects after this change include:

• [Authorize] - Requires authentication for access
• [Authorize(Roles = "RoleName")] - Requires specific roles
• [Authorize(Policy = "PolicyName")] - Requires specific authorization policies
• [AllowAnonymous] - Explicitly allows anonymous access (overrides [Authorize])

Tool Authorization

Tools can be decorated with authorization attributes to control access:

[McpServerToolType]
public class WeatherTools
{
    [McpServerTool, Description("Gets public weather data")]
    public static string GetWeather(string location)
    {
        return $"Weather for {location}: Sunny, 25°C";
    }

    [McpServerTool, Description("Gets detailed weather forecast")]
    [Authorize] // Requires authentication
    public static string GetDetailedForecast(string location)
    {
        return $"Detailed forecast for {location}: ...";
    }

    [McpServerTool, Description("Manages weather alerts")]
    [Authorize(Roles = "Admin")] // Requires Admin role
    public static string ManageWeatherAlerts(string alertType)
    {
        return $"Managing alert: {alertType}";
    }
}

Class-Level Authorization

You can apply authorization at the class level, which affects all tools in the class:

[McpServerToolType]
[Authorize] // All tools require authentication
public class RestrictedTools
{
    [McpServerTool, Description("Restricted tool accessible to authenticated users")]
    public static string RestrictedOperation()
    {
        return "Restricted operation completed";
    }

    [McpServerTool, Description("Public tool accessible to anonymous users")]
    [AllowAnonymous] // Overrides class-level [Authorize]
    public static string PublicOperation()
    {
        return "Public operation completed";
    }
}

How Authorization Filters Work

The authorization filters work differently for list operations versus individual operations:

List Operations (ListTools, ListPrompts, ListResources)

For list operations, the filters automatically remove unauthorized items from the results. Users only see tools, prompts, or resources they have permission to access.

Individual Operations (CallTool, GetPrompt, ReadResource)

For individual operations, the filters return authorization errors when access is denied:

• Tools: Returns a CallToolResult with IsError = true and an error message
• Prompts: Throws an McpException with "Access forbidden" message
• Resources: Throws an McpException with "Access forbidden" message

Setup Requirements

To use authorization features, you must configure authentication and authorization in your ASP.NET Core application:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication("Bearer")
    .AddJwtBearer(options => { /* JWT configuration */ })
    .AddMcp(options => { /* Resource metadata configuration */ });
builder.Services.AddAuthorization();

builder.Services.AddMcpServer()
    .WithHttpTransport()
    .WithTools<WeatherTools>()
    .AddCallToolFilter(next => async (context, cancellationToken) =>
    {
        // Custom call tool logic
        return await next(context, cancellationToken);
    });

var app = builder.Build();
app.MapMcp();
app.Run();

Custom Authorization Filters

You can also create custom authorization filters using the filter methods:

.AddCallToolFilter(next => async (context, cancellationToken) =>
{
    // Custom authorization logic
    if (context.User?.Identity?.IsAuthenticated != true)
    {
        return new CallToolResult
        {
            Content = [new TextContent { Text = "Custom: Authentication required" }],
            IsError = true
        };
    }

    return await next(context, cancellationToken);
});

RequestContext

Within filters, you have access to:

• context.User - The current user's ClaimsPrincipal
• context.Services - The request's service provider for resolving authorization services
• context.MatchedPrimitive - The matched tool/prompt/resource with its metadata including authorization attributes

[pksorensen]

@halter73 Looks fine, basic idea is the same. Like the pipeline building / middleware concept. Had to think a bit if having filters on the option class is the right choice ( i think that typical aspnet core patterns is to have it registered with DI directly and resolving IEnumerable<IFilter...> however i have no knowledge that otherwise indicate if thats better/worse or more correct way to do it.

From user perspectiv i think the examples given is clean and understanable. This would be a fine way to do so.

Should also be possible to do my sample from #703 adding all kind of filterings ontop using this approach.

So to me the thing i would consider is if developers would like to be able to just do services.AddMCPFilter() and have it implement an interface, where thats not directly possibel right now as its handlers being added to the filter array on the options.

But for me this works and solve the usecase i was going for.

[PederHP]

I really like the way the filters are done from a developer experience perspective. Easy to use and highly customizable. Only thing is that it's not really limited to filtering - you can freely modify, act, and/or add in the middleware. So I'm not sure the name should be "filter". Developers will figure it out soon enough if it is, but I think there's an argument for picking a name that reflects that this can be used for anything really.

But this is a great improvement in terms of convenient handler flexibility.

[halter73]

Had to think a bit if having filters on the option class is the right choice ( i think that typical aspnet core patterns is to have it registered with DI directly and resolving IEnumerable<IFilter...> however i have no knowledge that otherwise indicate if thats better/worse or more correct way to do it.

The nice thing about options is this can be reconfigured per-session in a ConfigureSessionOptions callback as @PederHP demonstrates in #724 while the set of services is typically static within an application. Using options to define the filter pipeline also allows you to resolve services to help you configure exactly which services you want to add in which order. If we relied on resolving IEnumerable<IFilter...> from DI, you would have to determine which filters to register in which order before you build the IServiceProvider. And filters don't usually need resolved by other services, so there's not a huge benefit to making them easily injectible.

This is why the middleware pipelines in ASP.NET Core is typically on some sort of builder or options type rather than registered directly as services. For example, the main middleware pipeline is typically stored in ApplicationBuilder._components, Endpoint filters are stored in EndpointBuilder._filterFactories, SignalR Hub filters are stored in HubOptions.HubFilters, and Kestrel connection middleware is stored in ListenOptions._middleware.

[halter73]

I updated this PR to respond to your feedback @stephentoub. I filed follow up issues for some of it.

[msioen]

I'm not sure if this is the correct location to ask this but I feel that I'm missing something. With this implementation it doesn't seem possible to expose/list the tools a user doesn't have access to since the auth filter is required.

In my usecase I would like all tools to be listed. But when a tool which needs authorization gets used the unauthorized flow / authorization flow kicks in. With this implementation I don't think that's ever going to happen since the tool is 'hidden' from being used in the first place.

=> is there a way to influence/adapt how this authorization filter works?

[ProRedCat]

I'd like to repeat @msioen sentiments as well on exposing/listing tools the user doesn't have access to. On other MCP servers such as GitHub, if you are authorized you are allowed to see all tools - though you'll be prevented from using tools if you invoke them with missing permissions.

From what I can tell the MCP specification doesn't have any hard rules on this behaviour, though there is mention that the way it was designed was that listing could be dynamic.

Additionally, I've been using the latest main branch specifically for the [Authorize] attribute support added here, but I noticed that this hasn't yet made it into a published NuGet package. It's been about a month since the last release, and I'm keen to use this feature in a production environment without relying on a local build.

Is there an estimated timeline for when a new NuGet package will be released?

[PederHP]

I'd like to repeat @msioen sentiments as well on exposing/listing tools the user doesn't have access to. On other MCP servers such as GitHub, if you are authorized you are allowed to see all tools - though you'll be prevented from using tools if you invoke them with missing permissions.

From what I can tell the MCP specification doesn't have any hard rules on this behaviour, though there is mention that the way it was designed was that listing could be dynamic.

Why would you ever want to give the model tools that you know it cannot call? I can see if it was to trigger step-up authorization, but that's not something supported by the spec yet.

Tools are generally a model-directed capability. The user may be able to see them in many clients, but they are invoked by the model, not the user, and giving the model tools it cannot call it wasteful in tokens and may confuse models.

You can use dynamic listing still by doing the auth manually instead of with the attribute - through the session instead of in middleware. Also it is worth noting that client host support for tool list change notifications is not very strong - many clients will not pick it up and will simply cache the tools it got on the initial list call - or will do a tools/list call on every conversation turn.

[wim-gdwi]

I support @PederHP here in the statement that it is best to avoid providing tools to an LLM, and this for more reasons that the tokens alone. In Gpt 5 model, we noticed that the reasoning tends to use tools you wouldn't even expect it to call given a certain prompt, but it "just does". Giving it more tools, especially those it can't call anyway, will only make it worse.

The implementation as it is now does however lead to one problem, for which I do not know the solution to be honest so maybe somebody has an idea? Thing is that most clients trigger the authentication flow ( the "login popup") based on an authentication error where the MCP library challenges the client. However, if you connect now and call the list tools function, it just returns an empty list all the time because the attributes just filter the list, and an empty list is also a list. So the client assumes all went well, there are simply no tools.

Using the MapMcp().RequireAuthentication() solves this issue because then authentication is defacto required and triggered, but, then you cannot use te concept of anonymous functions anymore. I understand this cannot be solved and the solution is that the authentication must be done manually in the client before connecting.... but most tools do not support that and are only reactive to the challenge request. That is an issue where making a server that combines both anonymous and protected functions hard.

[msioen]

I misunderstood the original spec when I asked this question, in the meantime it's indeed clear to me that currently for MCP it's all or nothing with regards to authorization.
In the end we ended up creating two servers instead, one for public use and one with authorization on it.
Maybe in the future the spec will update or an auth feature similar to elicitation could come in but for now using two separate MCP servers it is.

[ProRedCat]

Thanks for the perspectives. My original thinking came from what other MCP servers like GitHub and Figma do, where they expose the full capability surface and just block calls when the user isn’t authorized. There are workflow-style cases where it may useful for a model to understand all available actions up front but this isn't the most common case.

But with how MCP clients currently behave, surfacing tools the model can’t invoke ends up creating more noise than value. Some MCP clients do provide options to disable specific tools, but not all support this so it isn't really an argument either. Given the specification has no opinion either way I’m happy with the current implementation, I personally didn't have a usecase for my comment as it was more of an observation of other MCP servers.

On the topic of [AllowAnonymous] I have used the MapMcp().RequireAuthentication() approach to issue a challenge, though I don't have any public tools to use alongside it. However, I don't see this as an issue of this implementation as this feels like undefined behaviour of the MCP specification. From how I see it if we want to have an OAuth challenge AND show any tools (regardless of public or not), with the current specification that is not possible as we can't list tools without a session - and to get a session a challenge would be sent.