Authio.Mcp.AspNetCore 0.5.0

Authio.Mcp.AspNetCore

Protect an ASP.NET Core MCP server with Authio.

The MCP server is an OAuth 2.1 resource server; Authio is its authorization server. This package is the MCP layer on top of Authio.AspNetCore, which does the token work:

• Token validation (from Authio.AspNetCore) — JWT bearer: signature with the client's access token algorithm (AccessTokenSignedResponseAlg; left out, the realm's asymmetric keys, never HS*), issuer, audience (your resource identifier), expiry and token type (header typ at+jwt, RFC 9068; ID and refresh tokens are refused). Nested JWE encrypted to your client is decrypted with its key, within the alg and enc the client is registered for. Introspection (RFC 7662), when asked for, checks every token with Authio (ActiveCheck), or reads opaque tokens entirely from Authio (IntrospectionOnly).
• The caller (from Authio.AspNetCore) — HttpContext.GetAuthioUser(): whether a person, a client, a consumer or an account credential is calling, roles, permissions, scopes, resource access, organization, how the person signed in (acr/amr), delegation and impersonation.
• Protected resource metadata (RFC 9728) — always published, so every 401 carries resource_metadata, as the MCP authorization specification requires.
• Authorization per tool — put [AuthioScope], [AuthioRole], [AuthioPermission], [AuthioCallerKind], [AuthioOrganization], [AuthioClient] or a step-up attribute on a tool. A tools/call the caller may not make is answered at the HTTP layer, before the tool runs: 403 with insufficient_scope and the missing scope (the MCP scope challenge), 403 for a role, permission or caller kind, or 401 with acr_values/max_age and resource_metadata for a step-up (RFC 9470). tools/list only lists the tools the caller may call.
• Browser MCP clients — a CORS policy for the MCP Inspector and the like.

Connected accounts (trading the caller's token for the provider token of an account they connected) and the server's own client authentication (its TokenEndpointAuthMethod: client_secret_basic, client_secret_post, private_key_jwt or none) come from Authio.Client, registered for you.

Configure it the way the resource server and its client are registered in Authio. The package assumes nothing the Authio console configures: each setting is an option, and a setting left out is off, as in NextAuth — no scope required, no introspection, nothing decrypted. What stays fixed is what the MCP authorization specification requires (see What the MCP specification fixes).

Targets .NET 8 and .NET 10, with the official C# MCP SDK (ModelContextProtocol.AspNetCore).

Install

dotnet add package Authio.Mcp.AspNetCore

It brings Authio.AspNetCore, Authio.Client and ModelContextProtocol.AspNetCore with it.

Register the server in Authio

In the Authio console, in your realm:

1. Create a resource server whose identifier is the public URL of your MCP endpoint, e.g. https://mcp.example.com/mcp, with a scope such as mcp:tools, and list the MCP clients that call you under Authorized clients.
2. Create a confidential client for the MCP server itself and set it as the resource server's introspection client — Authio reports a token addressed to the resource server as active only to that client. Its id goes in ClientId; its Token endpoint auth method goes in TokenEndpointAuthMethod, with a secret (ClientSecret) or, for private_key_jwt, the private key (register its public key on the client's Security step).
3. For connected accounts, give that client the token exchange grant, add a connection provider (e.g. alias github) and allow the MCP clients to use it.

Configure

Every setting is read from Authio:Mcp, under the names every Authio library shares (conformance/options.md). Keep secrets in user-secrets or environment variables (Authio__Mcp__ClientSecret).

{
  "Authio": {
    "Mcp": {
      "Authority": "https://auth.example.com",
      "Realm": "demo",
      "Resource": "https://mcp.example.com/mcp",
      "ClientId": "mcp-server",
      "TokenEndpointAuthMethod": "Basic",
      "ClientSecret": "<secret>",
      "RequiredScopes": [ "mcp:tools" ],
      "Introspection": "ActiveCheck",
      "ResourceName": "My MCP server"
    }
  }
}

A missing or invalid setting stops the application at start-up with the setting named. In code, the settings are AuthioOptions (realm and client), AuthioJwtBearerOptions named AuthioJwtBearerDefaults.AuthenticationScheme (validation and metadata) and AuthioMcpOptions (required scopes):

builder.Services.AddAuthentication().AddAuthioMcp(options => options.RequiredScopes = ["mcp:tools"]);
builder.Services.Configure<AuthioOptions>(options =>
{
    options.TokenEndpointAuthMethod = AuthioTokenEndpointAuthMethod.PrivateKeyJwt;
    options.ClientSigningCredentials = credentialsFromVault;
});
builder.Services.Configure<AuthioJwtBearerOptions>(AuthioJwtBearerDefaults.AuthenticationScheme, options =>
    options.Introspection = AuthioIntrospectionMode.IntrospectionOnly);

AddAuthioMcp(IConfiguration) reads another section instead of Authio:Mcp.

What the MCP specification fixes

Three things are not settings, because the MCP authorization specification requires them rather than any client or resource server setting in Authio:

Use with the official C# MCP SDK

using Authio.AspNetCore.Extensions;
using Authio.Mcp.AspNetCore.Defaults;
using Authio.Mcp.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddAuthioMcp();
builder.Services.AddCors(cors => cors.AddAuthioMcpPolicy());
builder.Services.AddHttpContextAccessor();
builder.Services
    .AddMcpServer()
    .WithHttpTransport(transport => transport.Stateless = true)
    .AddAuthorizationFilters()
    .WithToolsFromAssembly();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapAuthioProtectedResourceMetadata().RequireCors(AuthioMcpDefaults.CorsPolicy);
app.MapMcp("/mcp")
    .RequireAuthioMcp()
    .RequireCors(AuthioMcpDefaults.CorsPolicy);

app.Run();

• AddAuthioMcp() registers Authio.AspNetCore's bearer scheme (AuthioJwtBearerDefaults.AuthenticationScheme), the Authio client, the Authio policy provider and result handler (AddAuthioAuthorization), and the AuthioMcpDefaults.Policy policy (RequiredScopes; with none, any authenticated caller).
• MapAuthioProtectedResourceMetadata() (from Authio.AspNetCore) serves the metadata at /.well-known/oauth-protected-resource{path of Resource} — /.well-known/oauth-protected-resource/mcp here.
• RequireAuthioMcp() requires AuthioMcpDefaults.Policy on the MCP endpoint and authorizes each tools/call against its tool. AddAuthorizationFilters() (from the MCP SDK) filters tools/list with the same attributes.

{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": [ "https://auth.example.com/realms/demo" ],
  "bearer_methods_supported": [ "header" ],
  "scopes_supported": [ "mcp:tools" ],
  "resource_name": "My MCP server"
}

Authorization per tool

using System.ComponentModel;
using Authio.AspNetCore.Attributes;
using Authio.AspNetCore.Enums;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class FileTools
{
    [McpServerTool(Name = "write_file")]
    [Description("Writes a file.")]
    [AuthioScope("files:write")]                       // 403 insufficient_scope, scope="files:write"
    public static string Write(string path, string content) => "…";

    [McpServerTool(Name = "purge")]
    [Description("Purges the bucket.")]
    [AuthioRole("admin")]                              // 403
    [AuthioRecentAuthentication(300)]                  // 401 insufficient_user_authentication, max_age=300
    public static string Purge() => "…";

    [McpServerTool(Name = "sync")]
    [Description("Runs the nightly sync.")]
    [AuthioCallerKind(AuthioCallerKind.Client)]        // machines only
    public static string Sync() => "…";
}

[AuthioPermission("invoice", "write")], [AuthioOrganization], [AuthioClient("…")], [AuthioAuthenticationLevel(2)], [AuthioAuthenticationMethod("hwk")] and [Authorize(Policy = "…")] work the same way. For the whole endpoint, chain the requirement after RequireAuthioMcp():

app.MapMcp("/mcp").RequireAuthioMcp().RequireAuthioAuthenticationLevel(2, TimeSpan.FromHours(1));

A tool registered only for one session (ConfigureSessionOptions) is not known to RequireAuthioMcp(); the MCP SDK's filter still refuses it, with a JSON-RPC error.

A tool that reads the caller and uses a connected account

using System.ComponentModel;
using Authio.AspNetCore.Extensions;
using Authio.Client.Clients;
using Authio.Client.Models;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class GitHubTools
{
    [McpServerTool(Name = "github_account", ReadOnly = true)]
    [Description("Shows which GitHub account the caller connected through Authio.")]
    public static async Task<string> GitHubAccount(
        IHttpContextAccessor accessor,
        IAuthioTokenClient tokens,
        [Description("Which connected account to use, when there are several.")] string? connectionId = null,
        CancellationToken cancellationToken = default)
    {
        var context = accessor.HttpContext!;
        var user = context.GetAuthioUser()!;                // kind, subject, client, scopes, roles, org, acr/amr, act
        var subjectToken = context.GetAuthioAccessToken()!; // the verified Authio access token

        var result = await tokens.ExchangeForConnectionAsync(subjectToken, "github", connectionId, cancellationToken);

        return result switch
        {
            AuthioConnectionGranted granted => $"{user.Subject} is {granted.ExternalAccount?.Login} on GitHub.",
            AuthioConnectionRequired required => $"Connect your GitHub account first: {required.ConnectUri}",
            AuthioConnectionSelectionRequired selection =>
                "Pick one: " + string.Join(", ", selection.Connections.Select(c => $"{c.Id} ({c.ExternalLogin})")),
            AuthioConnectionRefused refused => $"Authio refused ({refused.Error}, {refused.ErrorCode}): {refused.ErrorDescription}",
            _ => "Unexpected result."
        };
    }
}

Return each refusal to the model as text the person can act on.

A runnable version lives in samples/Authio.Mcp.Sample, with one settings file per client authentication method; its README walks through the Authio console, running it, and connecting the MCP Inspector or Claude Code.

Challenges

The table is conformance/challenges.json of authio-node, which ChallengeConformanceTests runs through the MCP endpoint; every 401, the step-up one included, names resource_metadata (RFC 9728 §5.1). The 401 for a missing or invalid token also names RequiredScopes as scope, separated by spaces (left out when none is required), so the MCP client asks for them rather than for every scope of scopes_supported. When introspection fails the token is not at fault, so the answer is 500 or 503 with no challenge: an MCP client told invalid_token would sign in again in a loop. The cause is logged.

Browser-based MCP clients (MCP Inspector)

A browser client reads the metadata cross-origin and must read WWW-Authenticate from the 401. Register the CORS policy, call app.UseCors() before app.UseAuthentication(), and add .RequireCors(AuthioMcpDefaults.CorsPolicy) to both the metadata and the MCP endpoint. The policy allows any origin (bearer tokens travel in a header, not in cookies), the MCP headers (Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID), and exposes WWW-Authenticate and Mcp-Session-Id.

API

From Authio.AspNetCore and Authio.Client: MapAuthioProtectedResourceMetadata(), GetAuthioUser(), GetAuthioAccessToken(), GetAuthioResourceAccess(), the [Authio…] attributes and RequireAuthio… conventions, IAuthioTokenClient.ExchangeForConnectionAsync, IAuthioIntrospectionClient. Every call to Authio goes through the named HttpClient AuthioDefaults.HttpClientName ("Authio").

Upgrading

• From 0.3: ClientAuthentication is now TokenEndpointAuthMethod (Authio.Client's AuthioTokenEndpointAuthMethod) and ValidAlgorithms is AccessTokenSignedResponseAlg; RequiredScopes and Introspection are off when left out, so a server that relied on mcp:tools and ActiveCheck sets them; AuthioMcpDefaults.Scope is gone. See CHANGELOG.md.

Conformance

conformance/ holds the vectors every Authio library runs, copied from authio-node (see conformance/SOURCE). The tests run callers.json, the access tokens of tokens.json (signed and JWE) and resource-access.json through the MCP endpoint; conformance/PENDING lists what does not apply here, with the reason.

License

MIT