Streamline Your AI Model Interactions: Building MCP Servers with NestJS

Want to create powerful AI-driven applications? This article shows you how to build a robust Model Context Protocol (MCP) server using NestJS, complete with real-time updates and secure access control. Learn how to quickly integrate AI models into your applications using the @rekog/mcp-nest module.

What is the @rekog/mcp-nest Module?

The @rekog/mcp-nest module simplifies the process of building MCP servers within the NestJS framework. It leverages Server-Sent Events (SSE) for efficient data streaming and tool execution. The module offers:

• SSE Transport: Enables real-time communication and streaming of data.
• Automatic Discovery: Simplifies tool and resource registration.
• Zod Validation: Ensures request data integrity.
• Progress Notifications: Keeps users informed with real-time updates.
• Guard-Based Authentication: Secures your endpoints.

Installation: Get Started Quickly

Install the necessary packages with npm using the command:

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

Quick Start: Building Your First MCP Server

Here is how to create a basic MCP server with a simple "hello-world" tool.

1. Import the McpModule

In your app.module.ts file, import the McpModule and configure it using forRoot:

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 Resources

Create a greeting.tool.ts file to define your first tool and a resource:

import { Injectable } from '@nestjs/common';
import { Tool, Context, Resource } 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) {
    const greeting = `Hello, ${name}!`;
    const totalSteps = 5;
    for (let i = 0; i < totalSteps; i++) {
      await new Promise((resolve) => setTimeout(resolve, 500));
      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',
  })
  async getCurrentSchema({ uri, userName }) {
    return {
      content: [
        {
          uri,
          text: `User is ${userName}`,
          mimeType: 'text/plain',
        },
      ],
    };
  }
}

This example showcases a simple tool named hello-world that takes a name parameter and returns a personalized greeting. The @Resource decorator defines an MCP resource linked to this tool.

Understanding Key Concepts

• Tools: Functions decorated with @Tool that perform specific actions. They are central to the Model Context Protocol (MCP) allowing you to integrate and use different models and services.
• Resources: Data sources or endpoints, decorated with @Resource, that provide information.
• Context: An object available within tools, enabling progress reporting and other functionalities.
• Server-Sent Events (SSE): A server-push technology enabling real-time updates to the client using the /sse endpoint.

API Endpoints Explained

The module exposes two main API endpoints:

• GET /sse: Establishes an SSE connection for real-time communication.
• POST /messages: Executes tools defined in your MCP server application.

Optimize with Global Prefix Exclusion

When using a global prefix for your NestJS application, exclude the MCP endpoints to avoid conflicts using:

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

Authentication: Securing Your MCP Server

You can secure your MCP endpoints using NestJS Guards to control access.

1. Create a Guard

Implement the CanActivate interface to create a custom guard. Handle request validation (JWTs, API keys) and attach user information to the request object if needed. Refer to the NestJS documentation for detailed guidance on creating guards.

2. Apply the Guard

Pass your guard(s) to the McpModule.forRoot configuration:

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

This configuration applies the AuthGuard to both the /sse and /messages endpoints, securing your MCP server.

Conclusion: Build Powerful AI Integrations with NestJS and MCP

The @rekog/mcp-nest module significantly simplifies the development of MCP servers within NestJS. Using this module will empower you to build robust, real-time AI integrations with features such as progress updates and secure authentication. Start building your next-generation AI application today!