How to add OAuth 2.1 auth to a remote MCP server

mcp-remote-auth-example/
  package.json
  tsconfig.json
  src/
    config.ts      # canonical URI + trusted issuer
    auth.ts        # the resource-server guard (the code you own)
    issuer.ts      # dev-only authorization server (delete in prod)
    server.ts      # the remote MCP server over Streamable HTTP
    verify.ts      # npm run demo: the one-command wire trace
    auth.test.ts   # six guard tests (npm test)

{
  "name": "mcp-remote-auth-example",
  "version": "1.0.0",
  "private": true,
  "description": "A minimal remote (Streamable HTTP) MCP server that acts as an OAuth 2.1 resource server: PRM discovery (RFC 9728), audience-bound token validation (RFC 8707), and a 401 + WWW-Authenticate discovery entry point. Companion repo for the mcporbit tutorial.",
  "type": "module",
  "engines": {
    "node": ">=20"
  },
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "tsx src/server.ts",
    "demo": "tsx src/verify.ts",
    "test": "tsx --test src/*.test.ts",
    "prepare": "npm run build"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "1.29.0",
    "express": "5.1.0",
    "jose": "6.1.0",
    "zod": "3.25.76"
  },
  "devDependencies": {
    "@types/express": "5.0.3",
    "@types/node": "22.20.1",
    "tsx": "4.23.1",
    "typescript": "5.9.3"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": false,
    "sourceMap": false
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
}

// Central config for the demo. In production these come from env / your IdP.
// RESOURCE is your MCP server's canonical URI, the audience every token must be bound to (RFC 8707).
// ISSUER is the OAuth 2.1 authorization server you delegate identity to (your IdP).
// In this repo the issuer is a tiny local dev AS so the whole flow runs in one command;
// in production you delete src/issuer.ts and point ISSUER at Auth0/Okta/Keycloak/WorkOS/Entra.

const PORT = Number(process.env.PORT ?? 8080);

export const config = {
  port: PORT,
  // Canonical resource URI of THIS MCP server. Tokens must carry this in `aud`.
  resource: process.env.MCP_RESOURCE ?? `http://localhost:${PORT}/mcp`,
  // The authorization server we trust to mint tokens.
  issuer: process.env.OAUTH_ISSUER ?? `http://localhost:${PORT}`,
  // Scope this resource server expects.
  scope: "mcp:tools",
};

// The OAuth 2.1 resource-server guard. This is the code you actually own on a
// remote MCP server: reject unauthenticated requests with a discoverable 401,
// and validate every token's signature, issuer, expiry, AND audience.
//
// The audience check (RFC 8707) is the one everyone skips. Without it, any valid
// token from the same authorization server works against your server, the
// confused-deputy hole. With it, a token minted for another resource is rejected.

import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
import type { Request, Response, NextFunction } from "express";
import { config } from "./config.js";

// Path of this resource server's Protected Resource Metadata document (RFC 9728).
export const PRM_PATH = "/.well-known/oauth-protected-resource";

/** RFC 9728 Protected Resource Metadata, how clients discover the AS + scopes. */
export function protectedResourceMetadata() {
  return {
    resource: config.resource,
    authorization_servers: [config.issuer],
    scopes_supported: [config.scope],
    bearer_methods_supported: ["header"],
  };
}

// Verify signatures against the authorization server's published JWKS.
// (The dev issuer serves this at /jwks; a real IdP serves it from its metadata.)
const JWKS = createRemoteJWKSet(new URL(`${config.issuer}/jwks`));

function challenge(res: Response, error?: string, description?: string) {
  // The WWW-Authenticate header points clients at our PRM document. This is the
  // discovery entry point: a spec-compliant client reads it and starts the flow.
  const prmUrl = `${config.issuer}${PRM_PATH}`;
  const parts = [
    `Bearer resource_metadata="${prmUrl}"`,
  ];
  if (error) parts.push(`error="${error}"`);
  if (description) parts.push(`error_description="${description}"`);
  res.setHeader("WWW-Authenticate", parts.join(", "));
  res.status(401).json({ error: error ?? "unauthorized", error_description: description });
}

/** Express middleware: enforce a valid, audience-bound bearer token. */
export async function requireAuth(req: Request, res: Response, next: NextFunction) {
  const header = req.headers.authorization;
  if (!header || !header.toLowerCase().startsWith("bearer ")) {
    return challenge(res, "invalid_request", "missing bearer token");
  }
  const token = header.slice(7).trim();
  try {
    await jwtVerify(token, JWKS, {
      issuer: config.issuer,
      audience: config.resource, // <-- RFC 8707: token MUST be bound to us
    });
    return next();
  } catch (err) {
    if (err instanceof joseErrors.JWTClaimValidationFailed && err.claim === "aud") {
      // Signed and unexpired, but minted for a DIFFERENT resource. Reject it.
      return challenge(res, "invalid_token", "token audience does not match this server");
    }
    if (err instanceof joseErrors.JWTExpired) {
      return challenge(res, "invalid_token", "token expired");
    }
    return challenge(res, "invalid_token", "token validation failed");
  }
}

// A tiny dev-only OAuth 2.1 authorization server.
//
// IMPORTANT: this exists ONLY so the tutorial runs end-to-end in one command.
// In production you DELETE this file and delegate to a real IdP (Auth0, Okta,
// Keycloak, WorkOS, Entra). Your MCP server never needs to be an auth server -
// it only validates the tokens a real IdP issues. See the production note below.
//
// This dev issuer does the minimum to exercise the resource server:
//   - holds an RSA keypair
//   - exposes JWKS so the resource server can verify signatures (real crypto)
//   - mints audience-bound access tokens (RFC 8707: `aud` = the requested `resource`)

import { generateKeyPair, exportJWK, SignJWT, type JWK } from "jose";

const KID = "dev-key-1";
const ALG = "RS256";

let privateKey: CryptoKey;
let publicJwk: JWK;
let ready: Promise<void> | null = null;

async function init(): Promise<void> {
  if (ready) return ready;
  ready = (async () => {
    const { privateKey: priv, publicKey: pub } = await generateKeyPair(ALG);
    privateKey = priv;
    publicJwk = { ...(await exportJWK(pub)), kid: KID, alg: ALG, use: "sig" };
  })();
  return ready;
}

/** JWKS document the resource server fetches to verify token signatures. */
export async function jwks(): Promise<{ keys: JWK[] }> {
  await init();
  return { keys: [publicJwk] };
}

/**
 * Mint an access token. `resource` becomes the token audience (RFC 8707).
 * A token whose `resource` differs from the MCP server's canonical URI will be
 * rejected by the resource server, that is the whole point of the audience check.
 */
export async function mintToken(opts: {
  issuer: string;
  resource: string;
  subject?: string;
  scope?: string;
  expiresInSeconds?: number;
}): Promise<string> {
  await init();
  const now = Math.floor(Date.now() / 1000);
  return new SignJWT({ scope: opts.scope ?? "mcp:tools" })
    .setProtectedHeader({ alg: ALG, kid: KID })
    .setIssuer(opts.issuer)
    .setSubject(opts.subject ?? "dev-user")
    .setAudience(opts.resource) // <-- RFC 8707 audience binding
    .setIssuedAt(now)
    .setExpirationTime(now + (opts.expiresInSeconds ?? 300))
    .sign(privateKey);
}

// The remote MCP server, over Streamable HTTP, behind an OAuth 2.1 resource-server guard.
//
//   GET  /.well-known/oauth-protected-resource  -> RFC 9728 discovery doc (public)
//   GET  /jwks                                  -> dev issuer's keys (a real IdP serves its own)
//   POST /mcp                                   -> the MCP endpoint, requireAuth-guarded
//   GET|DELETE /mcp                             -> session stream / teardown, also guarded
//
// The only auth code you own in production is src/auth.ts. Everything under /jwks
// and src/issuer.ts is the local dev stand-in for your real IdP.

import { randomUUID } from "node:crypto";
import express, { type Request, type Response } from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
import { config } from "./config.js";
import { PRM_PATH, protectedResourceMetadata, requireAuth } from "./auth.js";
import { jwks } from "./issuer.js";

function buildMcpServer(): McpServer {
  const server = new McpServer({ name: "mcp-remote-auth-example", version: "1.0.0" });
  // One trivial protected tool so `tools/list` and `tools/call` have something to return.
  server.tool(
    "whoami",
    "Returns a fixed identity string, proving the authenticated call reached the tool.",
    { note: z.string().optional().describe("optional echo note") },
    async ({ note }) => ({
      content: [
        {
          type: "text",
          text: `authenticated MCP call ok${note ? `, note: ${note}` : ""}`,
        },
      ],
    }),
  );
  return server;
}

export function createApp() {
  const app = express();
  app.use(express.json());

  // --- Public discovery endpoints ---
  app.get(PRM_PATH, (_req, res) => {
    res.json(protectedResourceMetadata());
  });
  app.get("/jwks", async (_req, res) => {
    res.json(await jwks());
  });

  // --- Guarded MCP endpoint (stateful Streamable HTTP sessions) ---
  const transports: Record<string, StreamableHTTPServerTransport> = {};

  app.post("/mcp", requireAuth, async (req: Request, res: Response) => {
    const sessionId = req.headers["mcp-session-id"] as string | undefined;
    let transport = sessionId ? transports[sessionId] : undefined;

    if (!transport && isInitializeRequest(req.body)) {
      transport = new StreamableHTTPServerTransport({
        sessionIdGenerator: () => randomUUID(),
        onsessioninitialized: (sid) => {
          transports[sid] = transport!;
        },
      });
      transport.onclose = () => {
        if (transport!.sessionId) delete transports[transport!.sessionId];
      };
      await buildMcpServer().connect(transport);
    } else if (!transport) {
      res.status(400).json({
        jsonrpc: "2.0",
        error: { code: -32000, message: "No valid session; send an initialize request first." },
        id: null,
      });
      return;
    }
    await transport.handleRequest(req, res, req.body);
  });

  const sessionStream = async (req: Request, res: Response) => {
    const sessionId = req.headers["mcp-session-id"] as string | undefined;
    const transport = sessionId ? transports[sessionId] : undefined;
    if (!transport) {
      res.status(400).send("Invalid or missing session id");
      return;
    }
    await transport.handleRequest(req, res);
  };
  app.get("/mcp", requireAuth, sessionStream);
  app.delete("/mcp", requireAuth, sessionStream);

  return app;
}

export function startServer(port = config.port) {
  const app = createApp();
  return new Promise<import("node:http").Server>((resolve) => {
    const httpServer = app.listen(port, () => resolve(httpServer));
  });
}

// Run directly: `npm run dev` / `npm start`
if (import.meta.url === `file://${process.argv[1]}`) {
  startServer().then(() => {
    console.log(`MCP resource server listening on ${config.resource}`);
    console.log(`PRM: ${config.issuer}${PRM_PATH}`);
  });
}

// One-command end-to-end proof (`npm run demo`).
// Boots the server, then walks the four wire behaviors the tutorial claims,
// printing the real request/response for each so you can see the auth layer work.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { startServer } from "./server.js";
import { mintToken } from "./issuer.js";
import { config } from "./config.js";
import { PRM_PATH } from "./auth.js";

const line = (s = "") => console.log(s);
const rule = (n: number, title: string) =>
  line(`\n=== ${n}. ${title} ===`);

async function main() {
  const server = await startServer();
  line(`# server up at ${config.resource}\n`);

  const MCP_JSON = { "Content-Type": "application/json", Accept: "application/json, text/event-stream" };
  const initBody = {
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: "2025-06-18",
      capabilities: {},
      clientInfo: { name: "wire-trace", version: "1.0.0" },
    },
  };

  // 1. Unauthenticated request -> 401 + WWW-Authenticate pointing at the PRM doc.
  rule(1, "Unauthenticated tools/list -> 401 + WWW-Authenticate");
  {
    const r = await fetch(config.resource, { method: "POST", headers: MCP_JSON, body: JSON.stringify(initBody) });
    line(`> POST /mcp   (no Authorization header)`);
    line(`< HTTP ${r.status}`);
    line(`< WWW-Authenticate: ${r.headers.get("www-authenticate")}`);
    line(`< body: ${await r.text()}`);
  }

  // 2. The client discovers the AS from the PRM document (RFC 9728).
  rule(2, "GET /.well-known/oauth-protected-resource -> RFC 9728 metadata");
  {
    const r = await fetch(`${config.issuer}${PRM_PATH}`);
    line(`> GET ${PRM_PATH}`);
    line(`< HTTP ${r.status}`);
    line(`< body: ${JSON.stringify(await r.json(), null, 2)}`);
  }

  // 3. A correctly audience-bound token (RFC 8707) authenticates and reaches the tools.
  rule(3, "Authorization Code + PKCE would mint this token; here the dev issuer mints it");
  const goodToken = await mintToken({ issuer: config.issuer, resource: config.resource });
  line(`> minted token with aud = ${config.resource}  (matches this server)`);
  {
    const transport = new StreamableHTTPClientTransport(new URL(config.resource), {
      requestInit: { headers: { Authorization: `Bearer ${goodToken}` } },
    });
    const client = new Client({ name: "wire-trace", version: "1.0.0" });
    await client.connect(transport);
    line(`< initialize + session established (HTTP 200)`);
    const tools = await client.listTools();
    line(`< tools/list -> [${tools.tools.map((t) => t.name).join(", ")}]`);
    const call = await client.callTool({ name: "whoami", arguments: { note: "audience ok" } });
    const text = (call.content as Array<{ type: string; text?: string }>)[0]?.text;
    line(`< tools/call whoami -> "${text}"`);
    await client.close();
  }

  // 4. A token minted for a DIFFERENT resource is rejected (the RFC 8707 audience check).
  rule(4, "Wrong-audience token -> 401 invalid_token (the money shot)");
  const wrongToken = await mintToken({ issuer: config.issuer, resource: "https://some-other-mcp.example/mcp" });
  {
    const r = await fetch(config.resource, {
      method: "POST",
      headers: { ...MCP_JSON, Authorization: `Bearer ${wrongToken}` },
      body: JSON.stringify(initBody),
    });
    line(`> POST /mcp   Authorization: Bearer <token aud=https://some-other-mcp.example/mcp>`);
    line(`< HTTP ${r.status}`);
    line(`< WWW-Authenticate: ${r.headers.get("www-authenticate")}`);
    line(`< body: ${await r.text()}`);
  }

  line(`\n# all four behaviors verified`);
  server.close();
}

main().then(
  () => process.exit(0),
  (err) => {
    console.error(err);
    process.exit(1);
  },
);

// Guard tests for the four wire behaviors. Run with `npm test`.
import { test, before, after } from "node:test";
import assert from "node:assert/strict";
import type { Server } from "node:http";
import { startServer } from "./server.js";
import { mintToken } from "./issuer.js";
import { config } from "./config.js";
import { PRM_PATH } from "./auth.js";

const MCP_JSON = {
  "Content-Type": "application/json",
  Accept: "application/json, text/event-stream",
};
const initBody = JSON.stringify({
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "t", version: "1" } },
});

let server: Server;
before(async () => {
  server = await startServer();
});
after(() => server.close());

test("unauthenticated request is rejected with 401 + WWW-Authenticate -> PRM", async () => {
  const r = await fetch(config.resource, { method: "POST", headers: MCP_JSON, body: initBody });
  assert.equal(r.status, 401);
  const wa = r.headers.get("www-authenticate") ?? "";
  assert.match(wa, /^Bearer /);
  assert.ok(wa.includes(`resource_metadata="${config.issuer}${PRM_PATH}"`), "points at PRM doc");
});

test("PRM document is a valid RFC 9728 shape", async () => {
  const r = await fetch(`${config.issuer}${PRM_PATH}`);
  assert.equal(r.status, 200);
  const doc = (await r.json()) as Record<string, unknown>;
  assert.equal(doc.resource, config.resource);
  assert.deepEqual(doc.authorization_servers, [config.issuer]);
  assert.ok(Array.isArray(doc.scopes_supported));
});

test("a correctly audience-bound token is accepted", async () => {
  const token = await mintToken({ issuer: config.issuer, resource: config.resource });
  const r = await fetch(config.resource, {
    method: "POST",
    headers: { ...MCP_JSON, Authorization: `Bearer ${token}` },
    body: initBody,
  });
  assert.equal(r.status, 200);
});

test("a wrong-audience token is rejected with invalid_token (RFC 8707)", async () => {
  const token = await mintToken({ issuer: config.issuer, resource: "https://other.example/mcp" });
  const r = await fetch(config.resource, {
    method: "POST",
    headers: { ...MCP_JSON, Authorization: `Bearer ${token}` },
    body: initBody,
  });
  assert.equal(r.status, 401);
  assert.match(r.headers.get("www-authenticate") ?? "", /error="invalid_token"/);
});

test("an expired token is rejected", async () => {
  const token = await mintToken({ issuer: config.issuer, resource: config.resource, expiresInSeconds: -10 });
  const r = await fetch(config.resource, {
    method: "POST",
    headers: { ...MCP_JSON, Authorization: `Bearer ${token}` },
    body: initBody,
  });
  assert.equal(r.status, 401);
});

test("a malformed bearer token is rejected", async () => {
  const r = await fetch(config.resource, {
    method: "POST",
    headers: { ...MCP_JSON, Authorization: "Bearer not-a-jwt" },
    body: initBody,
  });
  assert.equal(r.status, 401);
});

npm install
npm run demo

# and the guard tests
npm test

> POST /mcp   (no Authorization header)
< HTTP 401
< WWW-Authenticate: Bearer resource_metadata="http://localhost:8080/.well-known/oauth-protected-resource", error="invalid_request", error_description="missing bearer token"

> GET /.well-known/oauth-protected-resource
< HTTP 200
{
  "resource": "http://localhost:8080/mcp",
  "authorization_servers": ["http://localhost:8080"],
  "scopes_supported": ["mcp:tools"],
  "bearer_methods_supported": ["header"]
}

> minted token with aud = http://localhost:8080/mcp  (matches this server)
< initialize + session established (HTTP 200)
< tools/list -> [whoami]
< tools/call whoami -> "authenticated MCP call ok, note: audience ok"

> POST /mcp   Authorization: Bearer <token aud=https://some-other-mcp.example/mcp>
< HTTP 401
< WWW-Authenticate: Bearer resource_metadata="http://localhost:8080/.well-known/oauth-protected-resource", error="invalid_token", error_description="token audience does not match this server"