Registry / auth-security / mcp-auth

mcp-auth

JSON →
library0.2.0jsnpmunverified

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.

npm install mcp-auth
INSTALL
IMPORT
SIG · MCP-AUTH
M
mcp-auth
auth-securityjavascriptv0.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MCPAuth
import { MCPAuth } from 'mcp-auth';
const MCPAuth = require('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
import { fetchServerConfig } from 'mcp-auth';
import fetchServerConfig from 'mcp-auth/dist/util/config';
This utility for OIDC server metadata discovery is a named export from the main package entry point, simplifying module resolution.
bearerAuth
app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));
app.use(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.

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);
Debug
Known issues
breakingAs 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.
affects: <1.0.0
gotchaThe 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`.
affects: >=0.1.0
gotchaPrior 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.
affects: <0.2.0
gotchaThe 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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'bearerAuth')
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.
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'.
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.
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.
Upgrade
Version history
0.2.0latest on npm
Audit
Dependencies
expressrequiredPeer dependency required for integrating the library's middleware with an Express application, specifically for methods like `app.use(mcpAuth.bearerAuth(...))`.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources
mcp-auth — npm install mcp-auth · libregistry