NestJS MCP Server Module

A NestJS module for exposing your services as an MCP (Model Context Protocol) server with Server-Sent Events (SSE) transport. This package simplifies exposing tools that clients can discover and execute via SSE.

Features

SSE Transport: Built-in /sse endpoint for streaming and /messages for handling tool execution
Tool Discovery: Automatically discover and register tools using decorators
Tool Request Validation: Define Zod schemas to validate tool requests.
Progress Notifications: Send continuous progress updates from tools to clients.

Installation

npm install @rekog/mcp-nest reflect-metadata @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

// greeting.tool.ts
import { Injectable } from '@nestjs/common';
import { Tool } from '@rekog/mcp-nest';
import { z } from 'zod';
import { Context } from '@rekog/mcp-nest/dist/services/mcp-tools.discovery';
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));

      // Send a progress update.
      await context.reportProgress({
        progress: (i + 1) * 20,
        total: 100,
      } as Progress);
    }

    return {
      content: [{ type: 'text', text: greeting }],
    };
  }
}

You are done!

Client Connection

Clients can connect using the MCP SDK:

// client.ts
import { Client } from '@modelcontextprotocol/sdk/client';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse';

const client = new Client(
  { name: 'client-name', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(
  new SSEClientTransport(new URL('http://localhost:3000/sse'))
);

// Execute the 'hello-world' tool with progress tracking
const greetResult = await client.callTool(
  {
    name: 'hello-world',
    arguments: {
      name: 'MCP User',
    },
  },
  undefined, // responseSchema is optional, or you can define a Zod schema here
  {
    onprogress: (progress) => {
      console.log(
        `Progress: ${progress.progress}/${progress.total}`
      );
    },
  },
);

console.log(greetResult.content[0].text); // Output: Hello MCP User! I'm Test User from Test Org.

API Endpoints

GET /sse: SSE connection endpoint
POST /messages: Tool execution endpoint

Configuration Reference

`McpOptions`

Property	Type	Description	Default Value
`name`	string	Server name	-
`version`	string	Server version	-
`capabilities`	Record<string, any>	Server capabilities, defines what the server can do.	`{}`
`sseEndpoint`	string (optional)	Endpoint for SSE connections.	`'sse'`
`messagesEndpoint`	string (optional)	Endpoint for handling tool execution.	`'messages'`
`globalApiPrefix`	string (optional)	Global API prefix for all endpoints.	`''`

Tool Decorator

The @Tool decorator is used to define a method as an MCP tool.

@Tool({ name: string, description: string, parameters?: z.ZodObject<any> })

name: The name of the tool. This will be used to list it in the listTools request.
description: A description of the tool.
parameters: (Optional) A Zod schema defining the expected structure of the tool's input arguments.

NestJS MCP Server Module

Integrations

NestJS MCP Server Module

Features

Installation

Quick Start

1. Import Module

2. Define Tools

Client Connection

API Endpoints

Configuration Reference

`McpOptions`

Tool Decorator

Related Resources