Skip to main content

Class: MCPAuth

The main class for the mcp-auth library. It acts as a factory and registry for creating authentication policies for your protected resources.

It is initialized with your server configurations and provides a bearerAuth method to generate Express middleware for token-based authentication.

Example​

Usage in resource server mode​

This is the recommended approach for new applications.

Use this when you want metadata to be fetched on-demand. This is especially useful for edge runtimes like Cloudflare Workers where top-level async fetch is not allowed.

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const resourceIdentifier = 'https://api.example.com/notes';

const mcpAuth = new MCPAuth({
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        // Just pass issuer and type - metadata will be fetched on first request
        authorizationServers: [{ issuer: 'https://auth.logto.io/oidc', type: 'oidc' }],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

Option 2: Resolved config (pre-fetched metadata)​

Use this when you want to fetch and validate metadata at startup time.

import express from 'express';
import { MCPAuth, fetchServerConfig } from 'mcp-auth';

const app = express();
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

const mcpAuth = new MCPAuth({
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        authorizationServers: [authServerConfig],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

Using the middleware​

// Mount the router to handle Protected Resource Metadata
app.use(mcpAuth.protectedResourceMetadataRouter());

// Protect an API endpoint for the configured resource
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier, // Specify which resource this endpoint belongs to
    audience: resourceIdentifier, // Optionally, validate the 'aud' claim
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

Legacy Usage in authorization server mode (Deprecated)​

This approach is supported for backward compatibility.

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth = new MCPAuth({
  // Discovery config - metadata fetched on-demand
  server: { issuer: 'https://auth.logto.io/oidc', type: 'oidc' },
});

// Mount the router to handle legacy Authorization Server Metadata
app.use(mcpAuth.delegatedRouter());

// Protect an endpoint using the default policy
app.get(
  '/mcp',
  mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    // Handle the MCP request here
  },
);

Constructors​

Constructor​

new MCPAuth(config: MCPAuthConfig): MCPAuth;

Creates an instance of MCPAuth. It validates the entire configuration upfront to fail fast on errors.

Parameters​

config​

MCPAuthConfig

The authentication configuration.

Returns​

MCPAuth

Properties​

config​

readonly config: MCPAuthConfig;

The authentication configuration.

Methods​

bearerAuth()​

Call Signature​

bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">): RequestHandler;

Creates a Bearer auth handler (Express middleware) that verifies the access token in the Authorization header of the request.

Parameters​
verifyAccessToken​

VerifyAccessTokenFunction

A function that verifies the access token. It should accept the access token as a string and return a promise (or a value) that resolves to the verification result.

See

VerifyAccessTokenFunction for the type definition of the verifyAccessToken function.

config?​

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">

Optional configuration for the Bearer auth handler.

See

BearerAuthConfig for the available configuration options (excluding verifyAccessToken and issuer).

Returns​

RequestHandler

An Express middleware function that verifies the access token and adds the verification result to the request object (req.auth).

See​

handleBearerAuth for the implementation details and the extended types of the req.auth (AuthInfo) object.

Call Signature​

bearerAuth(mode: "jwt", config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig): RequestHandler;

Creates a Bearer auth handler (Express middleware) that verifies the access token in the Authorization header of the request using a predefined mode of verification.

In the 'jwt' mode, the handler will create a JWT verification function using the JWK Set from the authorization server's JWKS URI.

Parameters​
mode​

"jwt"

The mode of verification for the access token. Currently, only 'jwt' is supported.

See

VerifyAccessTokenMode for the available modes.

config?​

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig

Optional configuration for the Bearer auth handler, including JWT verification options and remote JWK set options.

See

  • VerifyJwtConfig for the available configuration options for JWT verification.
  • BearerAuthConfig for the available configuration options (excluding verifyAccessToken and issuer).
Returns​

RequestHandler

An Express middleware function that verifies the access token and adds the verification result to the request object (req.auth).

See​

handleBearerAuth for the implementation details and the extended types of the req.auth (AuthInfo) object.

Throws​

if the JWKS URI is not provided in the server metadata when using the 'jwt' mode.

delegatedRouter()​

delegatedRouter(): Router;

Creates a delegated router for serving legacy OAuth 2.0 Authorization Server Metadata endpoint (/.well-known/oauth-authorization-server) with the metadata provided to the instance.

Returns​

Router

A router that serves the OAuth 2.0 Authorization Server Metadata endpoint with the metadata provided to the instance.

Deprecated​

Use protectedResourceMetadataRouter instead.

Example​

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth: MCPAuth; // Assume this is initialized
app.use(mcpAuth.delegatedRouter());

Throws​

If called in resource server mode.

protectedResourceMetadataRouter()​

protectedResourceMetadataRouter(): Router;

Creates a router that serves the OAuth 2.0 Protected Resource Metadata endpoint for all configured resources.

This router automatically creates the correct .well-known endpoints for each resource identifier provided in your configuration.

Returns​

Router

A router that serves the OAuth 2.0 Protected Resource Metadata endpoint.

Throws​

If called in authorization server mode.

Example​

import express from 'express';
import { MCPAuth } from 'mcp-auth';

// Assuming mcpAuth is initialized with one or more `protectedResources` configs
const mcpAuth: MCPAuth;
const app = express();

// This will serve metadata at `/.well-known/oauth-protected-resource/...`
// based on your resource identifiers.
app.use(mcpAuth.protectedResourceMetadataRouter());