What is Mcp Nest

NestJS MCP Server Module is a NestJS module designed to streamline the creation and exposure of AI tools, resources, and prompts through applications using the Model Context Protocol (MCP). It leverages the familiarity of the NestJS ecosystem and its dependency injection capabilities, enabling developers to build enterprise-ready MCP servers efficiently.

Use cases

This module is ideal for creating AI-driven applications that require flexibility in exposing various functionality, such as tools for data processing, resources for information retrieval, and prompts for user interaction. It can be applied in customer support bots, automated content generation, data analysis tools, and any scenarios requiring real-time communication between clients and servers.

How to use

To utilize the MCP server, developers need to import the McpModule in their NestJS application and configure it with essential parameters like server name and version. They can define tools and resources using annotations, which are automatically discovered and registered. The module also supports different transport types, allowing developers to choose between HTTP, SSE, or STDIO based on their requirements.

Key features

Key features of the module include support for multiple transport types (Streamable HTTP, HTTP+SSE, and STDIO), automatic tool and resource discovery, Zod-based validation for tool calls, progress notifications, guard-based authentication for endpoint protection, and access to HTTP request data within MCP resources.

Where to use

The module is best suited for applications that require a robust server-client architecture with asynchronous communication capabilities. It can be integrated into enterprise applications where AI functionalities are needed, such as internal tools for business analytics, customer engagement platforms, or any project that benefits from a structured way to expose backend services as tools and resources.

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

• 🚀 Support for all Transport Types:
  • Streamable HTTP
  • HTTP+SSE
  • STDIO
• 🔍 Automatic tool, resource, and prompt discovery and registration
• 💯 Zod-based tool call validation
• 📊 Progress notifications
• 🔒 Guard-based authentication
• 🌐 Access to HTTP Request information within MCP Resources (Tools, Resources, Prompts)

Installation

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

Quick Start

1. Import Module

// 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 {}

2. Define Tools and Resource

// 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',
        },
      ],
    };
  }
}

You are done!

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

Quick Start for STDIO

The main difference is that you need to provide the transport option when importing the module.

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

The rest is the same, you can define tools, resources, and prompts as usual. An example of a standalone NestJS application using the STDIO transport is the following:

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:

API Endpoints

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.

Tips

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'] });

Authentication

You can secure your MCP endpoints using standard NestJS Guards.

1. Create a Guard

Implement the CanActivate interface. 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.

2. Apply the Guard

Pass your guard(s) to the McpModule.forRoot configuration. The guard(s) will be applied to both the /sse and /messages endpoints.

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

Playground

The playground directory contains examples to quickly test MCP and @rekog/mcp-nest features.
Refer to the playground/README.md for more details.

Configuration

The McpModule.forRoot() method accepts an McpOptions object to configure the server. Here are the available options: