Build a secure MCP server with NestJS

npm i @modelcontextprotocol/server @modelcontextprotocol/node zod jose
npm i -D @modelcontextprotocol/client   # for tests

/** Everything security-relevant comes from configuration, never from the request. */
export const MCP_CONFIG = Symbol('MCP_CONFIG');

export interface McpConfig {
  /** Public URL of this MCP endpoint: the RFC 8707 resource and the required token audience. */
  resource: URL;
  /** Authorization server that issues tokens for this resource. */
  issuer: string;
  jwksUrl: URL;
  /** Host header values accepted (DNS rebinding protection). */
  allowedHosts: string[];
}

export function mcpConfigFromEnv(): McpConfig {
  return {
    resource: new URL(process.env.MCP_RESOURCE_URL ?? 'https://mcp.example.com/mcp'),
    issuer: process.env.MCP_ISSUER ?? 'https://auth.example.com',
    jwksUrl: new URL(process.env.MCP_JWKS_URL ?? 'https://auth.example.com/.well-known/jwks.json'),
    allowedHosts: (process.env.MCP_ALLOWED_HOSTS ?? 'mcp.example.com').split(','),
  };
}

import { Inject, Injectable } from '@nestjs/common';
import { OAuthError, OAuthErrorCode, type AuthInfo, type OAuthTokenVerifier } from '@modelcontextprotocol/server';
import { createRemoteJWKSet, errors, jwtVerify, type JWTVerifyGetKey } from 'jose';
import { MCP_CONFIG, type McpConfig } from './mcp.config.js';

export const JWKS = Symbol('JWKS');
export const remoteJwks = (config: McpConfig): JWTVerifyGetKey => createRemoteJWKSet(config.jwksUrl);

/**
 * The SDK's bearer helpers check the header format, scopes and expiry.
 * Issuer, signature and audience are this class's job, and the audience check is the one that matters most.
 */
@Injectable()
export class JwtTokenVerifier implements OAuthTokenVerifier {
  constructor(
    @Inject(MCP_CONFIG) private readonly config: McpConfig,
    @Inject(JWKS) private readonly keys: JWTVerifyGetKey,
  ) {}

  async verifyAccessToken(token: string): Promise<AuthInfo> {
    try {
      const { payload } = await jwtVerify(token, this.keys, {
        issuer: this.config.issuer,
        audience: this.config.resource.href, // a token minted for another API is refused here
        algorithms: ['ES256', 'RS256'],
        typ: 'at+jwt', // RFC 9068 access tokens, not ID tokens
        requiredClaims: ['exp', 'sub', 'client_id'],
        clockTolerance: 30,
      });
      const tenantId = payload.tenant_id;
      if (typeof tenantId !== 'string') throw new OAuthError(OAuthErrorCode.InvalidToken, 'Token has no tenant');
      return {
        token,
        clientId: String(payload.client_id),
        scopes: typeof payload.scope === 'string' ? payload.scope.split(' ') : [],
        expiresAt: payload.exp,
        resource: this.config.resource,
        extra: { sub: payload.sub, tenantId },
      };
    } catch (err) {
      if (err instanceof OAuthError) throw err;
      if (err instanceof errors.JOSEError) throw new OAuthError(OAuthErrorCode.InvalidToken, 'Invalid access token');
      throw err;
    }
  }
}

import { CanActivate, ExecutionContext, ForbiddenException, Inject, Injectable } from '@nestjs/common';
import { bearerAuthChallengeResponse, getOAuthProtectedResourceMetadataUrl, validateHostHeader, verifyBearerToken, type AuthInfo } from '@modelcontextprotocol/server';
import type { Request } from 'express';
import { JwtTokenVerifier } from './jwt-token.verifier.js';
import { MCP_CONFIG, type McpConfig } from './mcp.config.js';

/** Carries a ready-made 401/403 challenge to McpChallengeFilter. */
export class McpChallenge extends Error {
  constructor(readonly response: Response) {
    super('MCP authorization failed');
  }
}

export type McpRequest = Request & { mcpAuth?: AuthInfo };

@Injectable()
export class McpAuthGuard implements CanActivate {
  private readonly resourceMetadataUrl: string;

  constructor(private readonly verifier: JwtTokenVerifier, @Inject(MCP_CONFIG) private readonly config: McpConfig) {
    this.resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(config.resource);
  }

  async canActivate(ctx: ExecutionContext): Promise<boolean> {
    const req = ctx.switchToHttp().getRequest<McpRequest>();
    // DNS rebinding protection first: only our public hostname may reach the endpoint.
    if (!validateHostHeader(req.headers.host, this.config.allowedHosts).ok) throw new ForbiddenException('Host not allowed');
    try {
      // Missing or malformed header, bad token, no expiry, expired: all become OAuthErrors.
      req.mcpAuth = await verifyBearerToken(req.headers.authorization, {
        verifier: this.verifier,
        requiredScopes: ['mcp:connect'],
        resourceMetadataUrl: this.resourceMetadataUrl,
      });
      return true;
    } catch (err) {
      // 401/403 with WWW-Authenticate: Bearer ..., resource_metadata="..." so clients can discover the AS.
      throw new McpChallenge(bearerAuthChallengeResponse(err, {
        requiredScopes: ['mcp:connect'],
        resourceMetadataUrl: this.resourceMetadataUrl,
      }));
    }
  }
}

import { ArgumentsHost, Catch, ExceptionFilter } from '@nestjs/common';
import type { Response as ExpressResponse } from 'express';
import { McpChallenge } from './mcp-auth.guard.js';

@Catch(McpChallenge)
export class McpChallengeFilter implements ExceptionFilter {
  async catch(exception: McpChallenge, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse<ExpressResponse>();
    const challenge = exception.response;
    challenge.headers.forEach((value, key) => res.setHeader(key, value));
    res.status(challenge.status).send(await challenge.text());
  }
}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", scope="mcp:connect", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"

import { Injectable } from '@nestjs/common';

export interface Invoice { id: string; tenantId: string; customer: string; status: 'open' | 'paid' | 'void'; totalCents: number }
export interface RefundDraft { id: string; tenantId: string; invoiceId: string; amountCents: number; reason: string; requestedBy: string }

/** Stands in for your database layer. Every method takes the tenant explicitly. */
@Injectable()
export class InvoicesService {
  private readonly invoices: Invoice[] = [
    { id: 'INV-1001', tenantId: 'acme', customer: 'Northwind', status: 'paid', totalCents: 129_00 },
    { id: 'INV-1002', tenantId: 'acme', customer: 'Contoso', status: 'open', totalCents: 87_50 },
    { id: 'INV-2001', tenantId: 'globex', customer: 'Initech', status: 'paid', totalCents: 990_00 },
  ];
  readonly drafts = new Map<string, RefundDraft>();

  list(tenantId: string, status: Invoice['status'] | undefined, limit: number): Invoice[] {
    return this.invoices.filter((i) => i.tenantId === tenantId && (!status || i.status === status)).slice(0, limit);
  }

  find(tenantId: string, id: string): Invoice | undefined {
    return this.invoices.find((i) => i.tenantId === tenantId && i.id === id);
  }

  /** Idempotent: one open draft per invoice. A person approves it outside MCP. */
  draftRefund(draft: Omit<RefundDraft, 'id'>): RefundDraft {
    const key = `${draft.tenantId}:${draft.invoiceId}`;
    const existing = this.drafts.get(key);
    if (existing) return existing;
    const created = { ...draft, id: `RFD-${this.drafts.size + 1}` };
    this.drafts.set(key, created);
    return created;
  }
}

import { Injectable } from '@nestjs/common';
import { McpServer, type AuthInfo } from '@modelcontextprotocol/server';
import { z } from 'zod';
import { InvoicesService, type Invoice } from './invoices.service.js';

const InvoiceOut = z.object({
  id: z.string(),
  customer: z.string(),
  status: z.enum(['open', 'paid', 'void']),
  totalCents: z.number().int(),
});
const InvoiceId = z.string().regex(/^INV-\d{4,10}$/, 'Invoice IDs look like INV-1001');
const toOut = ({ id, customer, status, totalCents }: Invoice) => ({ id, customer, status, totalCents });
const text = (s: string) => [{ type: 'text' as const, text: s }];

/**
 * Builds a fresh McpServer for one request. Only tools the token's scopes allow are registered,
 * so tools/list never advertises something the caller cannot use.
 */
@Injectable()
export class McpServerFactory {
  constructor(private readonly invoices: InvoicesService) {}

  create(auth: AuthInfo): McpServer {
    const tenantId = String(auth.extra?.tenantId); // from the verified token, never from tool arguments
    const can = (scope: string) => auth.scopes.includes(scope);
    const server = new McpServer({ name: 'billing', version: '1.0.0' });

    if (can('invoices:read')) {
      server.registerTool('list_invoices', {
        title: 'List invoices',
        description: 'List invoices for the signed-in customer account, newest first.',
        inputSchema: z.object({
          status: z.enum(['open', 'paid', 'void']).optional(),
          limit: z.number().int().min(1).max(50).default(20),
        }).strict(),
        outputSchema: z.object({ invoices: z.array(InvoiceOut) }),
        annotations: { readOnlyHint: true, openWorldHint: false },
      }, async ({ status, limit }) => {
        const invoices = this.invoices.list(tenantId, status, limit).map(toOut);
        return { content: text(`${invoices.length} invoice(s)`), structuredContent: { invoices } };
      });

      server.registerTool('get_invoice', {
        title: 'Get invoice',
        description: 'Get one invoice by ID.',
        inputSchema: z.object({ invoiceId: InvoiceId }).strict(),
        outputSchema: InvoiceOut,
        annotations: { readOnlyHint: true, openWorldHint: false },
      }, async ({ invoiceId }) => {
        const invoice = this.invoices.find(tenantId, invoiceId);
        // Same answer for "missing" and "belongs to someone else": no existence oracle.
        if (!invoice) return { content: text(`No invoice ${invoiceId}`), isError: true };
        return { content: text(`${invoice.id}: ${invoice.status}`), structuredContent: toOut(invoice) };
      });
    }

    if (can('refunds:draft')) {
      server.registerTool('draft_refund', {
        title: 'Draft a refund',
        description: 'Create a refund draft for a paid invoice. A staff member must approve it before any money moves.',
        inputSchema: z.object({
          invoiceId: InvoiceId,
          amountCents: z.number().int().positive().max(1_000_000),
          reason: z.string().trim().min(5).max(500),
        }).strict(),
        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
      }, async ({ invoiceId, amountCents, reason }) => {
        const invoice = this.invoices.find(tenantId, invoiceId);
        if (!invoice) return { content: text(`No invoice ${invoiceId}`), isError: true };
        if (invoice.status !== 'paid') return { content: text('Only paid invoices can be refunded'), isError: true };
        if (amountCents > invoice.totalCents) return { content: text('Refund exceeds the invoice total'), isError: true };
        const draft = this.invoices.draftRefund({
          tenantId, invoiceId, amountCents, reason, requestedBy: `${auth.clientId}/${String(auth.extra?.sub)}`,
        });
        return { content: text(`Refund draft ${draft.id} created and waiting for approval`) };
      });
    }
    return server;
  }
}

import { All, Controller, Get, Inject, OnModuleDestroy, Req, Res, UseFilters, UseGuards } from '@nestjs/common';
import { buildOAuthProtectedResourceMetadata, createMcpHandler, type AuthInfo } from '@modelcontextprotocol/server';
import { toNodeHandler } from '@modelcontextprotocol/node';
import type { Response } from 'express';
import { McpAuthGuard, type McpRequest } from './mcp-auth.guard.js';
import { McpChallengeFilter } from './mcp-challenge.filter.js';
import { MCP_CONFIG, type McpConfig } from './mcp.config.js';
import { McpServerFactory } from './mcp-server.factory.js';

@Controller()
export class McpController implements OnModuleDestroy {
  // Stateless (2026-07-28): one handler, a fresh McpServer per request built from that request's token.
  // legacy: 'stateless' (the default) also answers clients that still open with the 2025 handshake;
  // switch to 'reject' only when every client you support speaks 2026-07-28.
  private readonly handler = createMcpHandler(({ authInfo }) => this.servers.create(authInfo!), {
    legacy: 'stateless',
    onerror: (e) => console.error('mcp error', e.message),
  });
  constructor(private readonly servers: McpServerFactory, @Inject(MCP_CONFIG) private readonly config: McpConfig) {}

  async onModuleDestroy() {
    await this.handler.close();
  }

  /** RFC 9728 metadata: tells clients which authorization server issues tokens for this resource. */
  @Get('.well-known/oauth-protected-resource/mcp')
  metadata() {
    return buildOAuthProtectedResourceMetadata({
      resourceServerUrl: this.config.resource,
      scopesSupported: ['mcp:connect', 'invoices:read', 'refunds:draft'],
      resourceName: 'Billing MCP server',
      oauthMetadata: {
        issuer: this.config.issuer,
        authorization_endpoint: `${this.config.issuer}/authorize`,
        token_endpoint: `${this.config.issuer}/token`,
        response_types_supported: ['code'],
        code_challenge_methods_supported: ['S256'],
      },
    });
  }

  @All('mcp')
  @UseGuards(McpAuthGuard)
  @UseFilters(McpChallengeFilter)
  async mcp(@Req() req: McpRequest, @Res() res: Response) {
    const authInfo: AuthInfo = req.mcpAuth!;
    const serve = toNodeHandler({ fetch: (request, opts) => this.handler.fetch(request, { ...opts, authInfo }) });
    await serve(req, res, req.body);
  }
}

import { Module } from '@nestjs/common';
import { InvoicesService } from './invoices.service.js';
import { JWKS, JwtTokenVerifier, remoteJwks } from './jwt-token.verifier.js';
import { McpAuthGuard } from './mcp-auth.guard.js';
import { MCP_CONFIG, mcpConfigFromEnv, type McpConfig } from './mcp.config.js';
import { McpController } from './mcp.controller.js';
import { McpServerFactory } from './mcp-server.factory.js';

@Module({
  controllers: [McpController],
  providers: [
    { provide: MCP_CONFIG, useFactory: mcpConfigFromEnv },
    { provide: JWKS, useFactory: remoteJwks, inject: [MCP_CONFIG] },
    JwtTokenVerifier,
    McpAuthGuard,
    McpServerFactory,
    InvoicesService,
  ],
})
export class AppModule {}

import 'reflect-metadata';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module.js';

const app = await NestFactory.create(AppModule);
app.enableShutdownHooks();
await app.listen(Number(process.env.PORT ?? 3000), process.env.HOST ?? '127.0.0.1'); // TLS terminates at your proxy

{"resource":"https://mcp.example.com/mcp","authorization_servers":["https://auth.example.com"],"scopes_supported":["mcp:connect","invoices:read","refunds:draft"],"resource_name":"Billing MCP server"}

async function connect(token: string, modern = false) {
  // Default v2 client: 2025 handshake. modern: pin the 2026-07-28 revision.
  const client = new Client({ name: 'test-client', version: '1.0.0' }, modern ? { versionNegotiation: { mode: { pin: '2026-07-28' } } } : undefined);
  const transport = new StreamableHTTPClientTransport(new URL(`${BASE}/mcp`), {
    requestInit: { headers: { Authorization: `Bearer ${token}` } },
  });
  await client.connect(transport);
  return client;
}

test('tools/list only shows tools the token\'s scopes allow', async () => {
  const reader = await connect(await sign({}));
  assert.deepEqual((await reader.listTools()).tools.map((t) => t.name).sort(), ['get_invoice', 'list_invoices']);
  await reader.close();
  const drafter = await connect(await sign({ scope: 'mcp:connect invoices:read refunds:draft' }));
  assert.ok((await drafter.listTools()).tools.some((t) => t.name === 'draft_refund'));
  await drafter.close();
});

test('tenant comes from the token, not from arguments (2026-07-28 client)', async () => {
  const client = await connect(await sign({ tenant_id: 'acme' }), true);
  const list = await client.callTool({ name: 'list_invoices', arguments: {} });
  assert.deepEqual((list.structuredContent as { invoices: { id: string }[] }).invoices.map((i) => i.id), ['INV-1001', 'INV-1002']);
  const other = await client.callTool({ name: 'get_invoice', arguments: { invoiceId: 'INV-2001' } }); // globex's invoice
  assert.equal(other.isError, true);
  await client.close();
});

test('missing, wrong-audience, expired and ID tokens get 401 with resource metadata', async () => {
  const cases = {
    missing: undefined,
    wrongAudience: await new SignJWT({}).setProtectedHeader({ alg: 'HS256' }).sign(new Uint8Array(32)),
    otherApi: await sign({}, { aud: 'https://api.other.example.com' }), // valid token, wrong audience
    expired: await sign({}, { expSeconds: -120 }),
    idToken: await sign({}, { typ: 'JWT' }),
  };
  for (const [name, token] of Object.entries(cases)) {
    const res = await post(token);
    assert.equal(res.status, 401, name);
    assert.match(res.headers.get('www-authenticate') ?? '', /resource_metadata="https:\/\/mcp\.example\.com\/\.well-known\/oauth-protected-resource\/mcp"/, name);
  }
});