Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Add middleware and authz support for server-side handlers #733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 8 commits into from
Sep 10, 2025
Merged

Add middleware and authz support for server-side handlers #733

merged 8 commits into from
Sep 10, 2025
+2,871 −435

Conversation

halter73
Copy link
Contributor

@halter73 halter73 commented Aug 26, 2025 •
edited
Loading

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

@halter73 halter73 force-pushed the halter73/middleware branch from 43deac5 to 58dc73a Compare August 26, 2025 15:28
@halter73
Fix failing Windows build
76f7297 
- filters.md cleanup
@halter73 halter73 mentioned this pull request Aug 26, 2025
Closed
9 tasks
@pksorensen
Copy link

@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
PederHP reviewed Aug 26, 2025
View reviewed changes
@PederHP
Copy link
Collaborator

PederHP commented Aug 26, 2025

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
Copy link
Contributor Author

halter73 commented Aug 26, 2025 •
edited
Loading

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.

DavidParks8
DavidParks8 suggested changes Aug 26, 2025
View reviewed changes
stephentoub
stephentoub reviewed Sep 6, 2025
View reviewed changes
stephentoub
stephentoub reviewed Sep 10, 2025
View reviewed changes
This was referenced Sep 10, 2025
Open
Open
Open
Open
@halter73
Address PR feedback
d3186fd 
- Update filters.md to use DI and logging
- Update filters.md  Mention that uncaught McpExceptions get turned into JSON-RPC errors
- Added newlines to McpServer between blocks
- Remove TODO from AuthorizationFilterSetup now that an issue has been filed
@halter73
Copy link
Contributor Author

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

stephentoub
stephentoub reviewed Sep 10, 2025
View reviewed changes
stephentoub
stephentoub reviewed Sep 10, 2025
View reviewed changes
@halter73 halter73 merged commit d344c65 into main Sep 10, 2025
11 checks passed
@halter73 halter73 deleted the halter73/middleware branch September 10, 2025 17:07
JouckJack referenced this pull request Sep 11, 2025
@mikekistler
Update copyright in LICENSE file and add THIRD-PARTY-NOTICES.txt (#9)
d23e065
@msioen
Copy link

msioen commented Sep 15, 2025

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
Copy link

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?

@stephentoub stephentoub mentioned this pull request Sep 23, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@stephentoub stephentoub stephentoub approved these changes

@eiriktsarpalis eiriktsarpalis Awaiting requested review from eiriktsarpalis

@mikekistler mikekistler Awaiting requested review from mikekistler

@PederHP PederHP Awaiting requested review from PederHP

@DavidParks8 DavidParks8 Awaiting requested review from DavidParks8

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@halter73 @pksorensen @PederHP @msioen @ProRedCat @stephentoub @DavidParks8