MCP Auth Node.js SDK

Common errors

• TypeError: Cannot read properties of undefined (reading 'bearerAuth')

  cause The `mcpAuth` instance was not properly initialized, or `fetchServerConfig` failed, resulting in `mcpAuth` being `undefined` when `bearerAuth` is called.
  fix Ensure `await fetchServerConfig(...)` completes successfully and `MCPAuth` is instantiated before its methods are used. Check `authServerUrl` and network connectivity to the OIDC provider.

• Error: Peer dependency 'express' must be installed in your project.

  cause The `express` package, a required peer dependency, is not installed in the project's `node_modules`.
  fix Run `npm install express@^5.0.1` or `yarn add express@^5.0.1` to install the compatible version of Express.

• OIDC Provider Error: Invalid configuration URL or discovery failed for 'your-auth-server-url'.

  cause The URL provided to `fetchServerConfig` is incorrect, inaccessible, or the OIDC discovery endpoint is malformed or unresponsive.
  fix Verify that `AUTH_SERVER_URL` points to a valid and accessible OIDC provider's base URL. Check network connectivity and the OIDC provider's `.well-known/openid-configuration` endpoint.

• HTTP 401 Unauthorized - Invalid or missing Bearer token.

  cause A request to a protected endpoint was made without a valid OAuth 2.1 Bearer token in the `Authorization` header, or the token provided was invalid, expired, or not signed by the configured OIDC provider.
  fix Ensure the client sends a valid `Authorization: Bearer <token>` header with an access token obtained from the configured OIDC provider. Verify the token's validity, expiry, and issuer.

Warnings

• breaking As a pre-1.0 release (currently 0.2.0), the API of `mcp-auth` is subject to frequent changes without strict adherence to semantic versioning. Developers should expect potential breaking changes in minor or patch releases until a stable 1.0 version is reached.
  Fix: Regularly consult the project's GitHub changelog and README for the latest API documentation and migration guides. Pin dependencies to exact versions to prevent unexpected breakages.
• gotcha The library has a peer dependency on `express` version `^5.0.1`. Failing to install `express` in your project will lead to runtime errors when the `mcp-auth` middleware attempts to integrate.
  Fix: Ensure `express` is installed as a direct dependency in your project: `npm install express@^5.0.1` or `yarn add express@^5.0.1`.
• gotcha Prior to v0.2.0, remote JWK Set instances were not cached, potentially leading to redundant JWKS requests and performance overhead in high-traffic scenarios. This was addressed in v0.2.0.
  Fix: Upgrade to `mcp-auth` version 0.2.0 or newer to benefit from caching of remote JWK Sets, improving performance and reducing external network calls. No code changes are generally required, but ensure your OIDC provider's JWKS endpoint is robust.
• gotcha The library explicitly requires Node.js versions `^20.19.0 || ^22.0.0 || ^23.0.0 || ^24.0.0`. Running on unsupported Node.js versions may lead to unexpected behavior or crashes.
  Fix: Ensure your project's Node.js environment matches the specified engine requirements. Use a Node.js version manager like `nvm` to switch to a compatible version.

Install

• npm install mcp-auth npm
• yarn add mcp-auth yarn
• pnpm add mcp-auth pnpm

Imports

• MCPAuth
  wrong:

  const MCPAuth = require('mcp-auth');

  correct:

  import { MCPAuth } from 'mcp-auth';

  The library primarily uses ES modules. While CommonJS might technically work via transpilation or specific Node.js settings, direct ESM import is the intended and recommended approach for modern Node.js applications.
• fetchServerConfig
  wrong:

  import fetchServerConfig from 'mcp-auth/dist/util/config';

  correct:

  import { fetchServerConfig } from 'mcp-auth';

  This utility for OIDC server metadata discovery is a named export from the main package entry point, simplifying module resolution.
• bearerAuth
  wrong:

  app.use(bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));

  correct:

  app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));

  `bearerAuth` is a method of an `MCPAuth` instance, not a standalone function. It's designed to be used as Express middleware.

Quickstart

This quickstart demonstrates how to initialize `mcp-auth` with an OIDC provider, apply bearer token authentication to an Express application, and access authenticated user information within an MCP server tool definition. It highlights the `MCPAuth` class, `fetchServerConfig` utility, and middleware integration.

import express from 'express';
import { MCPAuth, fetchServerConfig } from 'mcp-auth';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; // Assuming @modelcontextprotocol/sdk is installed

const initializeMcpAuth = async () => {
  const server = new McpServer({ name: 'my-mcp-server', version: '1.0.0' });
  
  // Replace with your actual auth server URL, e.g., 'https://your-oidc-provider.com/realms/master'
  // For local testing, ensure your OIDC provider is running and accessible.
  const authServerUrl = process.env.AUTH_SERVER_URL ?? 'https://example.com/auth';
  
  const mcpAuth = new MCPAuth({
    server: await fetchServerConfig(authServerUrl, { type: 'oidc' }),
  });

  const app = express();
  app.use(express.json()); // Required for parsing JSON request bodies

  // Apply bearer token authentication middleware
  app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));

  // Define an MCP tool that utilizes authInfo
  server.tool('whoami', ({ authInfo }) => {
    // authInfo contains decoded token claims, e.g., authInfo.sub, authInfo.email
    console.log('Auth Info:', authInfo);
    return { content: [{ type: 'text', text: `You are ${authInfo?.sub || 'an unknown user'}` }] };
  });

  // Example route to serve the MCP server, assuming @modelcontextprotocol/sdk/express is used
  // You would typically integrate 'server' with an actual MCP Express handler.
  app.post('/mcp', (req, res) => {
    // This is a placeholder. In a real app, you'd integrate `server` via an MCP Express handler.
    // e.g., from '@modelcontextprotocol/sdk/express' or 'express-mcp-handler'
    res.status(200).json({ message: 'MCP endpoint hit, authInfo available in tools' });
  });

  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`MCP Auth server running on http://localhost:${PORT}`);
  });
};

initializeMcpAuth().catch(console.error);