MCP-Nest

NestJS MCP Server Module

A NestJS module to effortlessly expose tools, resources, and prompts for AI, from your NestJS applications using the Model Context Protocol (MCP).

With @rekog/mcp-nest you define tools, resources, and prompts in a way that's familiar in NestJS and leverage the full power of dependency injection to utilize your existing codebase in building complex enterprise ready MCP servers.

Features

• 🧩 NestJS Microservice Strategy: MCP runs as a CustomTransportStrategy, so tools/resources/prompts are real @MessagePattern handlers — guards, pipes, interceptors, and exception filters apply to them natively
• 🚀 Multi-Transport Support: Streamable HTTP and STDIO — selected via the transports array
• 🕰️ Dual-Era Protocol Support: One endpoint serves both the 2025-era protocol (initialize + sessions) and the stateless 2026-07-28 revision, concurrently — with no change to your tool code
• 🔧 Tools: Expose NestJS methods as MCP tools with automatic discovery and Zod validation
  • 🛠️ Elicitation: Interactive tool calls with user input elicitation
  • 🔁 Multi Round-Trip Requests: Elicitation, sampling and roots on protocol revision 2026-07-28 — one handler serves both eras
  • 🌐 HTTP Request Access: Full access to request context within MCP handlers
  • 🔐 Per-Tool Authorization: Implement fine-grained authorization for tools
• 📁 Resources: Serve content and data through MCP resource system
• 📚 Resource Templates: Dynamic resources with parameterized URIs
• 💬 Prompts: Define reusable prompt templates for AI interactions
• 🔐 Guard-based Authentication: Guard-based security with OAuth support
• 🏠 Built-in Authorization Server — Using the built-in Authorization Server for easy setups. (Beta)
• 🌐 External Authorization Server — Securing your MCP server with an external authorization server (Keycloak, Auth0, etc).
• 💉 Dependency Injection: Leverage NestJS DI system throughout MCP components
• 🔍 Server mutation and instrumentation — Mutate the underlying mcp server for custom logic or instrumentation purposes.

Are you interested to build ChatGPT widgets (with the OpenAI SDK) or MCP apps? Find out how to do that with @rekog/MCP-Nest in this repository MCP-Nest-Samples

[!TIP] You can easily learn about this package using the chat tab in Context7. Better yet, connect the Context7 MCP server to allow your AI agents to access the documentation and implement MCP-Nest for you.

Installation

npm install @rekog/mcp-nest \
  @modelcontextprotocol/server \
  @modelcontextprotocol/core \
  @modelcontextprotocol/node \
  zod@^4

Optional dependencies

The built-in authorization server now lives in a separate package. If you use it, install it alongside @rekog/mcp-nest:

npm install @rekog/mcp-nest-auth

If you additionally use the TypeORM store for the authorization server, install the following optional peer dependencies as well:

npm install @nestjs/typeorm typeorm

Quick Start

MCP-Nest runs as a NestJS microservice transport strategy. Tools, resources, and prompts live on @McpController() classes (so NestJS guards, pipes, interceptors, and exception filters apply to them), and the strategy serves them over one or more transports (Streamable HTTP, STDIO).

// greeting.controller.ts
import { McpController, Tool, McpContext } from '@rekog/mcp-nest';
import { Ctx, Payload } from '@nestjs/microservices';
import { z } from 'zod';

@McpController()
export class GreetingController {
  @Tool({
    name: 'greeting-tool',
    description: 'Returns a greeting with progress updates',
    parameters: z.object({ name: z.string().default('World') }),
  })
  async sayHello(
    @Payload() { name }: { name: string },
    @Ctx() ctx: McpContext,
  ) {
    await ctx.reportProgress({ progress: 50, total: 100 });
    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
  }
}

// app.module.ts
import { Module } from '@nestjs/common';
import {
  McpStrategy,
  MCP_STRATEGY,
  StreamableHttpTransport,
} from '@rekog/mcp-nest';
import { GreetingController } from './greeting.controller';

// The strategy is the whole configuration — there is no McpModule.
export const mcp = new McpStrategy({
  name: 'my-mcp-server',
  version: '1.0.0',
  transports: [
    new StreamableHttpTransport(),
  ],
});

@Module({
  controllers: [GreetingController],
  // Optional: only needed if a provider injects the strategy (e.g. for
  // runtime/dynamic tool registration).
  providers: [{ provide: MCP_STRATEGY, useValue: mcp }],
})
export class AppModule {}

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule, mcp } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  mcp.setHttpAdapter(app.getHttpAdapter()); // needed for HTTP transports
  app.connectMicroservice({ strategy: mcp });
  await app.startAllMicroservices(); // mounts the MCP transports
  await app.listen(3000); // also serves your normal HTTP routes
}
void bootstrap();

Order matters: call startAllMicroservices() before listen() so the MCP HTTP routes are mounted before the server starts accepting connections.

That /mcp endpoint is dual-era: it answers both the 2025-era protocol (initialize handshake + sessions) and the stateless 2026-07-28 revision, concurrently, from the same @Tool methods. ctx.reportProgress(...) above reaches a 2026-07-28 client as-is — every modern request can stream progress back even though it is sessionless. A 2025-era client needs a session-aware transport for it (new StreamableHttpTransport({ statefulMode: true }) or StdioTransport); on the legacy stateless default it is a no-op. See Protocol Revisions.

For an STDIO-only server, skip the HTTP adapter and use NestFactory.createMicroservice(AppModule, { strategy: mcp }) with transports: [new StdioTransport()] and disable logging (stdout is reserved for the protocol).

Documentation

• Migration to the Strategy API - Moving from McpModule.forRoot(options) to McpStrategy + @McpController
• Protocol Revisions & Dual-Era Serving - Serving the 2025-era protocol and 2026-07-28 from one endpoint
• Tools Guide - Define and expose NestJS methods as MCP tools
• Discovery and Registration of Tools - Automatic discovery and manual registration of tools
• Dynamic Capabilities Guide - Register tools, resources, and prompts programmatically at runtime
• Resources Guide - Serve static and dynamic content
• Resource Templates Guide - Create parameterized resources
• Prompts Guide - Build reusable prompt templates
• Built-in Authorization Server - Secure your MCP server with built-in OAuth
• External Authorization Server - Securing your MCP server with an external authorization server (Keycloak, Auth0, etc)
• Server examples - MCP servers examples (Streamable HTTP, HTTP, and STDIO) and with Fastify support

Examples

The examples directory contains working examples for all features. Refer to examples/README.md for details.