{"id":16850,"library":"mcp-auth","title":"MCP Auth Node.js SDK","description":"The `mcp-auth` library provides plug-and-play authentication and authorization solutions specifically for Model Context Protocol (MCP) servers in Node.js environments. It implements the OAuth 2.1 and OpenID Connect standards as required by the MCP specification, aiming to simplify the integration of MCP servers with compliant identity providers. Currently at version 0.2.0, the project is under active development with frequent releases (e.g., from v0.1.0 to v0.2.0 in a short period), indicating continuous feature additions and refinements. Key differentiators include its strict adherence to MCP authorization requirements, a focus on reducing boilerplate for OAuth/OIDC implementation, and direct support for `express` applications, providing a streamlined developer experience for securing MCP resources. It is provider-agnostic and offers tools for checking provider compliance.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/mcp-auth/js","tags":["javascript","modelcontextprotocol","mcp","oauth","openid","connect","oidc","typescript"],"install":[{"cmd":"npm install mcp-auth","lang":"bash","label":"npm"},{"cmd":"yarn add mcp-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcp-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for integrating the library's middleware with an Express application, specifically for methods like `app.use(mcpAuth.bearerAuth(...))`.","package":"express","optional":false}],"imports":[{"note":"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.","wrong":"const MCPAuth = require('mcp-auth');","symbol":"MCPAuth","correct":"import { MCPAuth } from 'mcp-auth';"},{"note":"This utility for OIDC server metadata discovery is a named export from the main package entry point, simplifying module resolution.","wrong":"import fetchServerConfig from 'mcp-auth/dist/util/config';","symbol":"fetchServerConfig","correct":"import { fetchServerConfig } from 'mcp-auth';"},{"note":"`bearerAuth` is a method of an `MCPAuth` instance, not a standalone function. It's designed to be used as Express middleware.","wrong":"app.use(bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));","symbol":"bearerAuth","correct":"app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));"}],"quickstart":{"code":"import express from 'express';\nimport { MCPAuth, fetchServerConfig } from 'mcp-auth';\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; // Assuming @modelcontextprotocol/sdk is installed\n\nconst initializeMcpAuth = async () => {\n  const server = new McpServer({ name: 'my-mcp-server', version: '1.0.0' });\n  \n  // Replace with your actual auth server URL, e.g., 'https://your-oidc-provider.com/realms/master'\n  // For local testing, ensure your OIDC provider is running and accessible.\n  const authServerUrl = process.env.AUTH_SERVER_URL ?? 'https://example.com/auth';\n  \n  const mcpAuth = new MCPAuth({\n    server: await fetchServerConfig(authServerUrl, { type: 'oidc' }),\n  });\n\n  const app = express();\n  app.use(express.json()); // Required for parsing JSON request bodies\n\n  // Apply bearer token authentication middleware\n  app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));\n\n  // Define an MCP tool that utilizes authInfo\n  server.tool('whoami', ({ authInfo }) => {\n    // authInfo contains decoded token claims, e.g., authInfo.sub, authInfo.email\n    console.log('Auth Info:', authInfo);\n    return { content: [{ type: 'text', text: `You are ${authInfo?.sub || 'an unknown user'}` }] };\n  });\n\n  // Example route to serve the MCP server, assuming @modelcontextprotocol/sdk/express is used\n  // You would typically integrate 'server' with an actual MCP Express handler.\n  app.post('/mcp', (req, res) => {\n    // This is a placeholder. In a real app, you'd integrate `server` via an MCP Express handler.\n    // e.g., from '@modelcontextprotocol/sdk/express' or 'express-mcp-handler'\n    res.status(200).json({ message: 'MCP endpoint hit, authInfo available in tools' });\n  });\n\n  const PORT = process.env.PORT || 3000;\n  app.listen(PORT, () => {\n    console.log(`MCP Auth server running on http://localhost:${PORT}`);\n  });\n};\n\ninitializeMcpAuth().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.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.","message":"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.","severity":"gotcha","affected_versions":"<0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `await fetchServerConfig(...)` completes successfully and `MCPAuth` is instantiated before its methods are used. Check `authServerUrl` and network connectivity to the OIDC provider.","cause":"The `mcpAuth` instance was not properly initialized, or `fetchServerConfig` failed, resulting in `mcpAuth` being `undefined` when `bearerAuth` is called.","error":"TypeError: Cannot read properties of undefined (reading 'bearerAuth')"},{"fix":"Run `npm install express@^5.0.1` or `yarn add express@^5.0.1` to install the compatible version of Express.","cause":"The `express` package, a required peer dependency, is not installed in the project's `node_modules`.","error":"Error: Peer dependency 'express' must be installed in your project."},{"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.","cause":"The URL provided to `fetchServerConfig` is incorrect, inaccessible, or the OIDC discovery endpoint is malformed or unresponsive.","error":"OIDC Provider Error: Invalid configuration URL or discovery failed for 'your-auth-server-url'."},{"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.","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.","error":"HTTP 401 Unauthorized - Invalid or missing Bearer token."}],"ecosystem":"npm","meta_description":null}