McpPrimitiveFilters 1.0.0

McpPrimitiveFilters

Pluggable filtering for MCP server tools, resources, and prompts. Attach one or more strategies to decide which primitives each authenticated (or anonymous) client can see and invoke.

Comes with two built-in strategies: appsettings allowlists (for local/dev control) and OAuth scope claims (for enterprise authorization). You can add your own by extending McpPrimitiveFilteringStrategy.

How to use

Add the package and register

using Microsoft.Extensions.DependencyInjection;

builder.Services.AddMcpPrimitiveFilters();

This registers IHttpContextAccessor, three per-primitive configurators, and both built-in strategies (AppSettings + OAuth).

With options

builder.Services.AddMcpPrimitiveFilters(options =>
{
    // Use only OAuth scopes — disable appsettings allowlist
    options.UseBuiltinAppSettingsFilteringStrategy = false;

    // Make prompts publicly visible (no filtering)
    options.FilterPrompts = false;
});

AppSettings allowlist

Configure which primitives are exposed via appsettings.json:

{
  "McpFiltering": {
    "Allowed": {
      "tools": ["GetRandomNumber", "Echo"],
      "resources": ["Server Info"],
      "prompts": null          // null = allow all prompts
    }
  }
}

An empty array means nothing is allowed. Omitting the key or setting it to null means everything is allowed.

OAuth scope claims

When using OAuth, the strategy maps scope claims to primitives:

If the client is not authenticated, the OAuth strategy passes through all names — it only filters when a principal is present.

Complete OAuth example

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(/* your config */);
builder.Services.AddAuthorization();

builder.Services.AddMcpPrimitiveFilters(options =>
{
    options.UseBuiltinAppSettingsFilteringStrategy = false;
});

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

A client presenting a token with scope: mcp.tool.Echo mcp.tool.Status will only see and be able to call Echo and Status. Any other tool call returns an error with the message "Tool 'X' is not authorized.".

Writing a custom strategy

Extend McpPrimitiveFilteringStrategy and override the methods for the primitive types you want to filter. The base class defaults to passing everything through, so you only override what you need.

public sealed class TimeBasedFilteringStrategy : McpPrimitiveFilteringStrategy
{
    protected override IEnumerable<string> FilterTools(IEnumerable<string> names)
    {
        if (DateTime.Now.Hour is >= 9 and < 17)
            return names;
        return names.Where(n => !n.StartsWith("Admin", StringComparison.OrdinalIgnoreCase));
    }
}

If your strategy needs request context, inject IHttpContextAccessor:

public sealed class RoleBasedFilteringStrategy : McpPrimitiveFilteringStrategy
{
    private readonly IHttpContextAccessor _http;

    public RoleBasedFilteringStrategy(IHttpContextAccessor http) => _http = http;

    protected override IEnumerable<string> FilterTools(IEnumerable<string> names)
    {
        var user = _http.HttpContext?.User;
        if (user?.IsInRole("Admin") == true) return names;
        return names.Where(n => !n.StartsWith("Admin"));
    }
}

Register it alongside the built-in strategies:

builder.Services.AddMcpPrimitiveFilters();
builder.Services.AddSingleton<McpPrimitiveFilteringStrategy, TimeBasedFilteringStrategy>();

All McpPrimitiveFilteringStrategy registrations run in registration order as a pipeline — each strategy receives the output of the previous one, narrowing the allowlist. If any strategy returns an empty list, downstream strategies are skipped. Built-in strategies are registered via TryAddEnumerable, so they coexist with your custom ones. Use the options to disable built-ins you don't need.

Logging

All strategy decisions are logged via ILogger under the category McpPrimitiveFilters:

Telemetry

The library emits OpenTelemetry-compatible signals using System.Diagnostics.ActivitySource and Meter. No additional NuGet packages are required — any OpenTelemetry collector (OTLP exporter, Jaeger, Zipkin, etc.) that instruments ActivitySource will pick up these signals automatically.

Source

Traces

Every filter operation creates an Activity span. The operation name reflects the action:

• filter tools list — filtering the tool list
• check tool call — checking whether a tool call is allowed
• filter resources list — filtering resources or resource templates
• check resource read — checking whether a resource read is allowed
• filter prompts list — filtering the prompt list
• check prompt get — checking whether a prompt get is allowed

Each span carries the following tags:

Metrics

All metrics include mcp.primitive.type and mcp.filter.operation tags.

License

MPL-2.0 — see the LICENSE file at the repository root.

About this project

This is a project for me to learn more about the MCP server SDK, as well as the capabilities of MCP in .NET. I try hard to make it production-ready, but it should be taken AS IS — if you find bugs or have ideas, please open an issue and I'll do my best to address them.

If you have feedback about the structure, the approach, or anything else, I'd love to hear it. This is my first public repo and I'm still learning.