How to Build an MCP Server in NestJS: Streamable HTTP, Guards and DI (Tested)

npm install @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs \ @modelcontextprotocol/server @modelcontextprotocol/node zod npm install -D typescript @types/node @types/express @nestjs/testing @modelcontextprotocol/client 

{ "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext", "target": "ES2023", "experimentalDecorators": true, "emitDecoratorMetadata": true, "strict": true, "strictPropertyInitialization": false, "skipLibCheck": true, "outDir": "dist", "rootDir": "." }, "include": ["src", "test"] } 

// src/notes/notes.service.ts import { Injectable } from "@nestjs/common"; export interface Note { id: number; title: string; body: string; owner: string; createdAt: string } @Injectable() export class NotesService { private notes: Note[] = []; private nextId = 1; search(owner: string, q?: string): Note[] { const needle = q?.toLowerCase(); return this.notes.filter( (n) => n.owner === owner && (!needle || `${n.title} ${n.body}`.toLowerCase().includes(needle)), ); } create(owner: string, title: string, body: string): Note { const note = { id: this.nextId++, title, body, owner, createdAt: new Date().toISOString() }; this.notes.push(note); return note; } } 

// src/mcp/mcp.service.ts import { Injectable, Logger, OnModuleDestroy } from "@nestjs/common"; import { createMcpHandler, McpServer, type McpRequestContext } from "@modelcontextprotocol/server"; import { toNodeHandler } from "@modelcontextprotocol/node"; import * as z from "zod/v4"; import { NotesService } from "../notes/notes.service.js"; @Injectable() export class McpService implements OnModuleDestroy { private readonly logger = new Logger(McpService.name); // Built once. The factory runs once per HTTP request, so every request gets a fresh McpServer. private readonly handler = createMcpHandler((ctx) => this.createServer(ctx), { responseMode: "json", onerror: (err) => this.logger.warn(err.message), }); readonly node = toNodeHandler(this.handler); constructor(private readonly notes: NotesService) {} private createServer({ authInfo }: McpRequestContext): McpServer { const owner = authInfo?.clientId ?? "anonymous"; const scopes = authInfo?.scopes ?? []; const server = new McpServer({ name: "notes", version: "1.0.0" }); server.registerTool( "search_notes", { title: "Search notes", description: "Search the caller's notes by a word in the title or body. Returns at most 20.", inputSchema: z.object({ q: z.string().max(200).optional().describe("Text to match; omit to list all") }), annotations: { readOnlyHint: true }, }, async ({ q }) => { const hits = this.notes.search(owner, q).slice(0, 20); return { content: [{ type: "text", text: JSON.stringify(hits) }] }; }, ); // Only tokens with the write scope ever see this tool in tools/list. if (scopes.includes("notes:write")) { server.registerTool( "create_note", { title: "Create note", description: "Save a new note for the caller.", inputSchema: z.object({ title: z.string().min(1).max(120), body: z.string().max(5000) }), outputSchema: z.object({ id: z.number(), title: z.string() }), }, async ({ title, body }) => { const note = this.notes.create(owner, title, body); const out = { id: note.id, title: note.title }; return { content: [{ type: "text", text: JSON.stringify(out) }], structuredContent: out }; }, ); } return server; } async onModuleDestroy() { await this.handler.close(); } } 

// src/mcp/mcp-auth.guard.ts import { CanActivate, ExecutionContext, ForbiddenException, Injectable, UnauthorizedException } from "@nestjs/common"; import { createHash, timingSafeEqual } from "node:crypto"; import { validateOriginHeader, type AuthInfo } from "@modelcontextprotocol/server"; import type { Request, Response } from "express"; const sha = (s: string) => createHash("sha256").update(s).digest(); const same = (a: string, b: string) => timingSafeEqual(sha(a), sha(b)); // token -> who it belongs to and what it may do. Load from env or a DB in a real app. function tokenTable(): Array<{ token: string; clientId: string; scopes: string[] }> { return [ { token: process.env.MCP_READ_TOKEN ?? "", clientId: "reader", scopes: ["notes:read"] }, { token: process.env.MCP_WRITE_TOKEN ?? "", clientId: "writer", scopes: ["notes:read", "notes:write"] }, ].filter((t) => t.token.length >= 32); } const ALLOWED_ORIGINS = (process.env.MCP_ALLOWED_ORIGINS ?? "localhost,127.0.0.1").split(","); @Injectable() export class McpAuthGuard implements CanActivate { canActivate(ctx: ExecutionContext): boolean { const http = ctx.switchToHttp(); const req = http.getRequest<Request & { auth?: AuthInfo }>(); // DNS rebinding / CSRF: a browser Origin must be on the list. No Origin (CLI, agents) passes. const origin = validateOriginHeader(req.headers.origin, ALLOWED_ORIGINS); if (!origin.ok) throw new ForbiddenException(origin.message); const m = /^Bearer\s+(\S+)$/i.exec(req.headers.authorization ?? ""); const hit = m && tokenTable().find((t) => same(m[1], t.token)); if (!hit) { http.getResponse<Response>().setHeader("WWW-Authenticate", 'Bearer realm="mcp"'); throw new UnauthorizedException("Invalid or missing bearer token"); } req.auth = { token: m[1], clientId: hit.clientId, scopes: hit.scopes }; return true; } } 

// src/mcp/mcp.controller.ts import { All, Controller, Header, HttpCode, Post, Req, Res, UseGuards } from "@nestjs/common"; import type { Request, Response } from "express"; import { McpAuthGuard } from "./mcp-auth.guard.js"; import { McpService } from "./mcp.service.js"; @Controller("mcp") export class McpController { constructor(private readonly mcp: McpService) {} @Post() @UseGuards(McpAuthGuard) async handle(@Req() req: Request, @Res() res: Response): Promise<void> { // With @Res() the SDK writes the response itself, so set headers on res directly. res.setHeader("Cache-Control", "no-store"); // Pass req.body: Nest's JSON parser has already read the stream. await this.mcp.node(req, res, req.body); } // Stateless server: no GET stream, no DELETE session. @All() @HttpCode(405) @Header("Allow", "POST") notAllowed() { return { error: "Method not allowed" }; } } 

// src/mcp/mcp.module.ts import { Module } from "@nestjs/common"; import { NotesModule } from "../notes/notes.module.js"; import { McpController } from "./mcp.controller.js"; import { McpService } from "./mcp.service.js"; @Module({ imports: [NotesModule], controllers: [McpController], providers: [McpService] }) export class McpModule {} 

// src/main.ts import "reflect-metadata"; import { NestFactory } from "@nestjs/core"; import type { NestExpressApplication } from "@nestjs/platform-express"; import { AppModule } from "./app.module.js"; const app = await NestFactory.create<NestExpressApplication>(AppModule); // Express's JSON parser defaults to 100kb; the MCP SDK itself allows 4 MiB. app.useBodyParser("json", { limit: "4mb" }); app.enableShutdownHooks(); await app.listen(Number(process.env.PORT ?? 3000), "127.0.0.1"); console.log(`MCP endpoint: ${await app.getUrl()}/mcp`); 

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3000/mcp \ --transport http --header "Authorization: Bearer $MCP_WRITE_TOKEN" \ --method tools/call --tool-name create_note --tool-arg title=Hello --tool-arg body=From-inspector