NestJS MCP Server Module

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

With@rekog/mcp-nestyou 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.

- 🚀 Support for all Transport Types:

- Streamable HTTP
- HTTP+SSE
- STDIO

npm install @rekog/mcp-nest @modelcontextprotocol/sdk zod

// app.module.ts import { Module } from '@nestjs/common'; import { McpModule } from '@rekog/mcp-nest'; import { GreetingTool } from './greeting.tool'; @Module({ imports: [ McpModule.forRoot({ name: 'my-mcp-server', version: '1.0.0', }), ], providers: [GreetingTool], }) export class AppModule {}

// greeting.tool.ts import type { Request } from 'express'; import { Injectable } from '@nestjs/common'; import { Tool, Resource, Context } from '@rekog/mcp-nest'; import { z } from 'zod'; import { Progress } from '@modelcontextprotocol/sdk/types'; @Injectable() export class GreetingTool { constructor() {} @Tool({ name: 'hello-world', description: 'Returns a greeting and simulates a long operation with progress updates', parameters: z.object({ name: z.string().default('World'), }), }) async sayHello({ name }, context: Context, request: Request) { const userAgent = request.get('user-agent') || 'Unknown'; const greeting = Hello, ${name}! Your user agent is: ${userAgent}; const totalSteps = 5; for (let i = 0; i < totalSteps; i++) { await new Promise((resolve) => setTimeout(resolve, 100)); // Send a progress update. await context.reportProgress({ progress: (i + 1) * 20, total: 100, } as Progress); } return { content: [{ type: 'text', text: greeting }], }; } @Resource({ uri: 'mcp://hello-world/{userName}', name: 'Hello World', description: 'A simple greeting resource', mimeType: 'text/plain', }) // Different from the SDK, we put the parameters and URI in the same object. async getCurrentSchema({ uri, userName }) { return { content: [ { uri, text: User is ${userName}, mimeType: 'text/plain', }, ], }; } }

[!TIP] The above example shows how HTTPRequestheaders are accessed within MCP Tools. This is useful for identifying users, adding client-specific logic, and many other use cases. For more examples, see theAuthentication Tests.

McpModule.forRoot({ name: 'playground-stdio-server', version: '0.0.1', transport: McpTransportType.STDIO, });

async function bootstrap() { const app = await NestFactory.createApplicationContext(AppModule, { logger: false, }); return app.close(); } void bootstrap();

Next, you can use the MCP server with an MCP Stdio Client (see example), or after building your project you can use it with the following MCP Client configuration:

{ "mcpServers": { "greeting": { "command": "node", "args": [ "<path to dist js file>", ] } } }

HTTP+SSE transport exposes two endpoints:

- GET /sse: SSE connection endpoint (Protected by guards if configured)
- POST /messages: Tool execution endpoint (Protected by guards if configured)

Streamable HTTP transport exposes the following endpoints:

- POST /mcp: Main endpoint for all MCP operations (tool execution, resource access, etc.). In stateful mode, this creates and maintains sessions.
- GET /mcp: Establishes Server-Sent Events (SSE) streams for real-time updates and progress notifications.Only available in stateful mode.
- DELETE /mcp: Terminates MCP sessions.Only available in stateful mode.

It's possible to use the module with global prefix, but the recommended way is to exclude those endpoints with:

app.setGlobalPrefix('/api', { exclude: ['sse', 'messages', 'mcp'] });

You can secure your MCP endpoints using standard NestJS Guards.

Implement theCanActivateinterface. The guard should handle request validation (e.g., checking JWTs, API keys) and optionally attach user information to the request object.

Nothing special, check the NestJS documentation for more details.

Pass your guard(s) to theMcpModule.forRootconfiguration. The guard(s) will be applied to both the/sseand/messagesendpoints.

// app.module.ts import { Module } from '@nestjs/common'; import { McpModule } from '@rekog/mcp-nest'; import { GreetingTool } from './greeting.tool'; import { AuthGuard } from './auth.guard'; @Module({ imports: [ McpModule.forRoot({ name: 'my-mcp-server', version: '1.0.0', guards: [AuthGuard], // Apply the guard here }), ], providers: [GreetingTool, AuthGuard], // Ensure the Guard is also provided }) export class AppModule {}

That's it! The rest is the same as NestJS Guards.

Theplaygrounddirectory contains examples to quickly test MCP and@rekog/mcp-nestfeatures. Refer to theplayground/README.mdfor more details.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB