MCP-Nest

Installation

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

The MCP SDK packages are peer dependencies. 2.0.0-beta.5 is the minimum — it is the first release matching the final 2026-07-28 wire, which MCP-Nest serves alongside the 2025-era protocol (see Protocol Revisions).

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).