How to add OAuth authentication to an MCP server

1// Stdio transport — NO auth needed
2import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3const transport = new StdioServerTransport();
4await server.connect(transport);
5
6// HTTP transport — auth IS needed
7// Clients connect over the network and must authenticate

1// TypeScript — Express route for OAuth metadata
2import express from "express";
3
4const app = express();
5const SERVER_URL = "https://mcp.example.com";
6
7app.get("/.well-known/oauth-authorization-server", (req, res) => {
8  res.json({
9    issuer: SERVER_URL,
10    authorization_endpoint: `${SERVER_URL}/oauth/authorize`,
11    token_endpoint: `${SERVER_URL}/oauth/token`,
12    registration_endpoint: `${SERVER_URL}/oauth/register`,
13    response_types_supported: ["code"],
14    grant_types_supported: ["authorization_code", "refresh_token"],
15    token_endpoint_auth_methods_supported: ["none"],
16    code_challenge_methods_supported: ["S256"],
17  });
18});

1// TypeScript — simplified auth endpoints
2import crypto from "crypto";
3
4const authCodes = new Map<string, { clientId: string; codeChallenge: string; userId: string; expiresAt: number }>();
5const accessTokens = new Map<string, { clientId: string; userId: string; expiresAt: number }>();
6
7// Authorization endpoint
8app.get("/oauth/authorize", (req, res) => {
9  const { client_id, redirect_uri, code_challenge, code_challenge_method, state } = req.query;
10
11  if (code_challenge_method !== "S256") {
12    return res.status(400).json({ error: "S256 code challenge required" });
13  }
14
15  // In production: show consent page, authenticate user
16  // For simplicity, auto-approve:
17  const code = crypto.randomUUID();
18  authCodes.set(code, {
19    clientId: client_id as string,
20    codeChallenge: code_challenge as string,
21    userId: "user-1",
22    expiresAt: Date.now() + 600_000, // 10 minutes
23  });
24
25  const redirectUrl = new URL(redirect_uri as string);
26  redirectUrl.searchParams.set("code", code);
27  if (state) redirectUrl.searchParams.set("state", state as string);
28  res.redirect(redirectUrl.toString());
29});
30
31// Token endpoint
32app.post("/oauth/token", express.urlencoded({ extended: false }), (req, res) => {
33  const { grant_type, code, code_verifier } = req.body;
34
35  if (grant_type !== "authorization_code") {
36    return res.status(400).json({ error: "unsupported_grant_type" });
37  }
38
39  const authCode = authCodes.get(code);
40  if (!authCode || authCode.expiresAt < Date.now()) {
41    return res.status(400).json({ error: "invalid_grant" });
42  }
43
44  // Verify PKCE code challenge
45  const hash = crypto.createHash("sha256").update(code_verifier).digest("base64url");
46  if (hash !== authCode.codeChallenge) {
47    return res.status(400).json({ error: "invalid_grant" });
48  }
49
50  authCodes.delete(code);
51  const accessToken = crypto.randomUUID();
52  accessTokens.set(accessToken, {
53    clientId: authCode.clientId,
54    userId: authCode.userId,
55    expiresAt: Date.now() + 3600_000, // 1 hour
56  });
57
58  res.json({
59    access_token: accessToken,
60    token_type: "Bearer",
61    expires_in: 3600,
62  });
63});

1// TypeScript — auth middleware
2function authMiddleware(req: express.Request, res: express.Response, next: express.NextFunction) {
3  const authHeader = req.headers.authorization;
4  if (!authHeader?.startsWith("Bearer ")) {
5    return res.status(401).json({ error: "Bearer token required" });
6  }
7
8  const token = authHeader.slice(7);
9  const tokenData = accessTokens.get(token);
10
11  if (!tokenData || tokenData.expiresAt < Date.now()) {
12    accessTokens.delete(token);
13    return res.status(401).json({ error: "Token expired or invalid" });
14  }
15
16  // Attach user context for tool handlers
17  (req as any).userId = tokenData.userId;
18  next();
19}
20
21// Apply to MCP endpoint
22app.post("/mcp", authMiddleware, (req, res) => {
23  // Process MCP JSON-RPC request with authenticated user context
24});

1// claude_desktop_config.json
2{
3  "mcpServers": {
4    "my-remote-server": {
5      "url": "https://mcp.example.com/mcp"
6    }
7  }
8}
9
10// The client will:
11// 1. Fetch /.well-known/oauth-authorization-server
12// 2. Generate PKCE code_verifier and code_challenge
13// 3. Open browser to authorization_endpoint
14// 4. Exchange auth code for access token at token_endpoint
15// 5. Include Bearer token in all subsequent MCP requests