npm i @hivetrail/mcpaccess-auth0-expressmcp-auth0-express is an Express middleware that validates JWT tokens and applies access restrictions and filtering based on user permissions.
To create the middleware, we use the createMcpAccessMiddleware function, passing an object with the required configuration. The object includes the following properties:
An example of creating and using the MCP Access Auth0 Express middleware using minimal configuration:
import express from "express";
import {
createMcpAccessMiddleware
} from "@hivetrail/mcpaccess-auth0-express";
//create the configuration object
const mcpAccessConfig = {
serverId: "mcp",
mcpPath: "/mcp",
jwtOptions: {
issuerBaseURL: process.env.AUTH0_ISSUER_URL,
audience: process.env.AUTH0_AUDIENCE
},
};
//create the Auth0 Express middleware
const mcpAuthMiddleware = createMcpAccessMiddleware(mcpAccessConfig);
const app = express();
app.use(express.json());
//set CORS settings as needed
app.use(
cors({
origin: "*", // Allow all origins - adjust as needed for production
exposedHeaders: ["Mcp-Session-Id"],
})
);
//activate the middleware
app.use(mcpAuthMiddleware);
//... the rest of the MCP server codeThe JWT token configuration object contains the settings used to validate the JWT token sent to the MCP server. To validate the token, we use Auth0 express-oauth2-jwt-bearer to create a middleware that inspects the token based on the configuration information.
The JWT token configuration object is based on the AuthOptions type from Auth0 express-oauth2-jwt-bearer, with two required properties:
These properties will be used for:
You can add additional optional properties to the JWT token configuration object as described in the express-oauth2-jwt-bearer documentation:
configuration example:
import type {JwtConfig} from '@hivetrail/mcpaccess-auth0-express';
const jwtTokenConfig: JwtConfig = {
issuerBaseURL: process.env.AUTH0_ISSUER_URL,
audience: process.env.AUTH0_AUDIENCE,
tokenSigningAlg: "RS256",
};In addition to validating the JWT token, we can also verify the information supplied in the JWT token in real-time directly:
We use the Auth0 client to connect to the Auth0 services, query and validate the information from the client and JWT token, and specify which elements to verify by setting the appropriate flags.
The Auth0 management object consists of the following properties:
configuration example:
import type {Auth0ManagementConfig} from '@hivetrail/mcpaccess-auth0-express';
const auth0ManagementConfig: Auth0ManagementConfig = {
client: {
domain: process.env.AUTH0_DOMAIN,
clientId: process.env.AUTH0_CLIENT_ID,
clientSecret: process.env.AUTH0_CLIENT_SECRET,
},
verifyUser: true,
verifyClient: true,
verifyPermissions: true,
};You can pass a logger function (e.g., winston, pino) to receive logging information. The logging configuration consists of the following properties:
configuration example:
const loggerConfig: loggerConfig = {
logger: logger,
logPrefix: "MyMCP: ",
logConsoleFallback: false
};By default, the package expects permissions to follow a syntax starting with the MCP server ID, followed by path items separated by a colon (:), or asterisk (*) for any value:
server_id:pathItem[0]:pathItem[1]
for example:
myMcpServer:tools:list
myMcpServer:resources:read:*
You can customize the structure of the permission string in two ways:
//using the custom function below as the permissionBuilderFn:
function customPermissionBuilder(pathItems:string[]){
return pathItems.join("-");
}
//will create the following permission strings:
// tools-list
// resources-read-*We’ll bring all the objects we’ve created above together to create our MCP auth middleware:
import {
createMcpAccessMiddleware,
type McpAuthOptions,
type Auth0ManagementConfig,
type loggerConfig,
type JwtConfig,
} from "@hivetrail/mcpaccess-auth0-express";
export const jwtAuthOptions: McpAuthOptions = {
serverId: "mcp",
mcpPath: "/mcp",
jwtOptions: jwtTokenConfig,
useOutboundFilter: true,
loggerOptions: loggerConfig,
auth0ManagementOptions: auth0ManagementConfig
};
export const mcpAuthMiddleware = createMcpAccessMiddleware(jwtAuthOptions);Then we can use the middleware in our main Express code:
import express, { NextFunction, Request, Response } from "express";
import { mcpAuthMiddleware } from "@services/auth.service";
const app = express();
app.use(express.json());
app.use(
cors({
origin: "*",
exposedHeaders: ["Mcp-Session-Id"],
})
);
app.use(mcpAuthMiddleware);import {
createMcpAccessMiddleware,
type McpAuthOptions,
type Auth0ManagementConfig,
type loggerConfig,
type JwtConfig,
} from "@hivetrail/mcpaccess-auth0-express";
const jwtTokenConfig: JwtConfig = {
issuerBaseURL: process.env.AUTH0_ISSUER_URL,
audience: process.env.AUTH0_AUDIENCE,
tokenSigningAlg: "RS256",
};
const loggerConfig: loggerConfig = {
logger: logger,
};
const auth0ManagementConfig: Auth0ManagementConfig = {
client: {
domain: process.env.AUTH0_DOMAIN || "",
clientId: process.env.AUTH0_CLIENT_ID || "",
clientSecret: process.env.AUTH0_CLIENT_SECRET || "",
},
verifyUser: true,
verifyClient: true,
verifyPermissions: true,
};
export const jwtAuthOptions: McpAuthOptions = {
serverId: "mcp",
mcpPath: "/mcp",
jwtOptions: jwtTokenConfig,
useOutboundFilter: true,
loggerOptions: loggerConfig,
auth0ManagementOptions: auth0ManagementConfig,
};
export const mcpAuthMiddleware = createMcpAccessMiddleware(jwtAuthOptions);Then use the middleware in the main Express configuration:
import express from "express";
import { mcpAuthMiddleware } from "@services/auth.service";
const app = express();
app.use(express.json());
app.use(
cors({
origin: "*", // Allow all origins - adjust as needed for production
exposedHeaders: ["Mcp-Session-Id"],
})
);
app.use(mcpAuthMiddleware);