add express mcp server example

Author: patrickkang

README.md

@@ -22,6 +22,7 @@ The following examples can be found in the examples directory:
 - [Fastify API Example](./examples/example-fastify-api/README.md)
 - [NestJS API Example](./examples/example-nestjs-api/README.md)
 - [Express Web App Example](./examples/example-express-web/README.md)
+- [Express MCP Server Example](./examples/example-express-mcp/README.md)
 
 Before running the examples, you need to install the dependencies for the monorepo and build all the packages.
 

examples/example-express-mcp/.env.example

@@ -0,0 +1,4 @@
+AUTH0_DOMAIN=
+AUTH0_AUDIENCE=
+PORT=3001
+MCP_SERVER_URL=http://localhost:3001

examples/example-express-mcp/README.md

@@ -0,0 +1,43 @@
+# Example Express MCP Server with Auth0 Integration
+
+This is a practical example of securing a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs) server
+with Auth0 using the Express framework.
+
+## Install dependencies
+
+Install the dependencies using npm:
+
+```bash
+npm install
+```
+
+## Configuration
+
+Rename `.env.example` to `.env` and configure the domain and audience:
+
+```ts
+AUTH0_DOMAIN=
+AUTH0_AUDIENCE=
+```
+
+With the configuration in place, the example can be started by running:
+
+```bash
+npm run start
+```
+
+## Testing
+
+Use an MCP client like [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to test your server interactively:
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+The server will start up and the UI will be accessible at http://localhost:6274.
+
+In the MCP Inspector, select `Streamable HTTP` as the `Transport Type` and enter `http://localhost:3001/mcp` as the URL.
+
+## Auth0 Tenant Setup
+
+TODO

examples/example-express-mcp/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "example-express-mcp",
+  "version": "0.1.0-beta.1",
+  "description": "Express MCP Server Example — Example implementation of an MCP server using Express.js with Auth0",
+  "type": "module",
+  "scripts": {
+    "start": "tsx src/index.ts --project tsconfig.json"
+  },
+  "dependencies": {
+    "@auth0/auth0-api-js": "*",
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.1",
+    "express": "^5.1.0",
+    "jose": "^6.0.12",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  }
+}

examples/example-express-mcp/src/auth.ts

@@ -0,0 +1,89 @@
+/**
+ * Auth0 authentication configuration for Express MCP server.
+ */
+
+import { type RequestHandler, type Router } from "express";
+import { AUTH0_DOMAIN, AUDIENCE, MCP_SERVER_URL } from "./config.js";
+import { AccessTokenClaims, Auth } from "./types.js";
+import { SCOPES_SUPPORTED } from "./tools.js";
+import { ApiClient, VerifyAccessTokenError } from "@auth0/auth0-api-js";
+import {
+  getOAuthProtectedResourceMetadataUrl,
+  mcpAuthMetadataRouter,
+} from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { discoverAuthorizationServerMetadata } from "@modelcontextprotocol/sdk/client/auth.js";
+import { InvalidTokenError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+
+/**
+ * Returns a router that includes MCP authorization metadata endpoints.
+ */
+export async function authMetadataRouter(): Promise<Router> {
+  const oauthMetadata = await discoverAuthorizationServerMetadata(
+    new URL(`https://${AUTH0_DOMAIN}`)
+  );
+
+  if (!oauthMetadata) {
+    throw new Error(`Failed to fetch OAuth metadata from ${AUTH0_DOMAIN}`);
+  }
+
+  return mcpAuthMetadataRouter({
+    resourceServerUrl: new URL(MCP_SERVER_URL),
+    scopesSupported: SCOPES_SUPPORTED,
+    oauthMetadata,
+  });
+}
+
+/**
+ * Returns a middleware that verifies the access token and extracts user information.
+ */
+export function authMiddleware(): RequestHandler {
+  const apiClient = new ApiClient({
+    domain: AUTH0_DOMAIN,
+    audience: AUDIENCE,
+  });
+
+  const verify = async (token: string): Promise<Auth> => {
+    try {
+      const decoded = (await apiClient.verifyAccessToken({
+        accessToken: token,
+      })) as AccessTokenClaims;
+
+      const clientId = decoded.client_id ?? decoded.azp;
+      if (!clientId) {
+        throw new Error(
+          "Token is missing required client identification (client_id or azp claim)."
+        );
+      }
+
+      return {
+        token,
+        clientId,
+        scopes:
+          typeof decoded.scope === "string"
+            ? decoded.scope.split(" ").filter(Boolean)
+            : [],
+        ...(decoded.exp && { expiresAt: decoded.exp }),
+        extra: {
+          sub: decoded.sub,
+          ...(decoded.client_id && { client_id: decoded.client_id }),
+          ...(decoded.azp && { azp: decoded.azp }),
+          ...(decoded.name && { name: decoded.name }),
+          ...(decoded.email && { email: decoded.email }),
+        },
+      };
+    } catch (error) {
+      if (error instanceof VerifyAccessTokenError) {
+        throw new InvalidTokenError(error.message);
+      }
+      throw error;
+    }
+  };
+
+  return requireBearerAuth({
+    resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(
+      new URL(MCP_SERVER_URL)
+    ),
+    verifier: { verifyAccessToken: verify },
+  });
+}

examples/example-express-mcp/src/config.ts

@@ -0,0 +1,12 @@
+import "dotenv/config";
+
+export const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN as string;
+export const PORT = parseInt(process.env.PORT ?? "3000", 10);
+export const MCP_SERVER_URL =
+  process.env.MCP_SERVER_URL ?? `http://localhost:${PORT}`;
+export const AUDIENCE = process.env.AUTH0_AUDIENCE ?? MCP_SERVER_URL;
+
+// Validate required environment variables
+if (!AUTH0_DOMAIN) {
+  throw new Error("AUTH0_DOMAIN environment variable is required");
+}

examples/example-express-mcp/src/index.ts

@@ -0,0 +1,18 @@
+import { PORT } from "./config.js";
+import { createMcpServer, createExpressApp } from "./server.js";
+
+async function main() {
+  try {
+    const mcpServer = createMcpServer();
+    const app = await createExpressApp(mcpServer);
+
+    app.listen(PORT, () => {
+      console.log(`Example Express MCP Server listening on port ${PORT}`);
+    });
+  } catch (error) {
+    console.error("Failed to start server:", error);
+    process.exit(1);
+  }
+}
+
+main();

examples/example-express-mcp/src/server.ts

@@ -0,0 +1,77 @@
+/**
+ * Express app with Auth0-based authentication and MCP transport.
+ */
+
+import express, { type Request, type Response } from "express";
+import cors from "cors";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { allowedMethods } from "@modelcontextprotocol/sdk/server/auth/middleware/allowedMethods.js";
+import { tools } from "./tools.js";
+import { authMetadataRouter, authMiddleware } from "./auth.js";
+
+/**
+ * Set up MCP server and register tools.
+ */
+export function createMcpServer(): McpServer {
+  const server = new McpServer({
+    name: "Example Express MCP Server",
+    version: "1.0.0",
+  });
+
+  for (const tool of tools) {
+    server.registerTool(tool.name, tool.config, tool.handler);
+  }
+
+  return server;
+}
+
+/**
+ * Create Express app with CORS, Auth0, and MCP handling.
+ */
+export async function createExpressApp(
+  mcpServer: McpServer
+): Promise<express.Application> {
+  const app = express();
+
+  // Enable CORS
+  app.use(
+    cors({
+      origin: "http://localhost:6274", // MCP Inspector; adjust as needed for production
+      exposedHeaders: ["Mcp-Session-Id"],
+      allowedHeaders: ["Content-Type", "mcp-session-id"],
+    })
+  );
+
+  app.use(express.json());
+
+  // Add metadata routes
+  app.use(await authMetadataRouter());
+
+  // Add auth middleware
+  app.use(authMiddleware());
+
+  // Handle MCP requests
+  app
+    .route("/mcp")
+    .post(async (req: Request, res: Response) => {
+      try {
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+        });
+        await mcpServer.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+        res.on("close", () => transport.close());
+      } catch (error) {
+        console.error("MCP request failed:", error);
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null,
+        });
+      }
+    })
+    .all(allowedMethods(["POST"]));
+
+  return app;
+}

examples/example-express-mcp/src/tools.ts

@@ -0,0 +1,96 @@
+/**
+ * MCP tools with scope-based authorization.
+ */
+
+import { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z, ZodRawShape } from "zod";
+import { Auth } from "./types.js";
+
+export const SCOPES_SUPPORTED = ["tool:whoami", "tool:greet"];
+
+/**
+ * Wraps a tool handler with scope validation.
+ * This function ensures that the tool can only be executed if the user has the required OAuth scopes.
+ */
+export function requireScopes<T extends ZodRawShape>(
+  requiredScopes: readonly string[],
+  handler: ToolCallback<T>
+): ToolCallback<T> {
+  return (async (args, context) => {
+    if (!context.authInfo) {
+      throw new Error(
+        "Authentication information is required to execute this tool."
+      );
+    }
+    const userScopes = context.authInfo.scopes;
+    const hasScopes = requiredScopes.every((scope) =>
+      userScopes.includes(scope)
+    );
+
+    if (!hasScopes) {
+      throw new Error(`Missing required scopes: ${requiredScopes.join(", ")}`);
+    }
+
+    return handler(args, context);
+  }) as ToolCallback<T>;
+}
+
+const greetToolInputSchema = {
+  name: z
+    .string()
+    .optional()
+    .describe("The name to greet (defaults to 'World')"),
+} as const;
+
+/**
+ * Tool definitions
+ */
+export const tools = [
+  {
+    name: "greet",
+    config: {
+      title: "Greet Tool",
+      description: "Greets a user",
+      inputSchema: greetToolInputSchema,
+      annotations: { readOnlyHint: false },
+    },
+    handler: requireScopes<typeof greetToolInputSchema>(
+      ["tool:greet"],
+      async (payload, context) => {
+        const { name } = payload;
+        const authInfo = context.authInfo as Auth;
+        const userId = authInfo.extra?.sub;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Hello, ${name}! You are authenticated as: ${userId}`,
+            },
+          ],
+        };
+      }
+    ),
+  },
+  {
+    name: "whoami",
+    config: {
+      title: "Whoami Tool",
+      description: "Greets a user",
+      annotations: { readOnlyHint: false },
+    },
+    handler: requireScopes(["tool:greet"], async (payload, context) => {
+      const name = payload.name ?? "World";
+      const authInfo = context.authInfo as Auth;
+      const userId = authInfo?.extra?.sub;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Hello, ${name}! You are authenticated as: ${userId}`,
+          },
+        ],
+      };
+    }),
+  },
+];