@markygab/nest-mcp

Internal NestJS primitives for defining and serving Model Context Protocol (MCP) tools. The package provides decorator-based tool discovery, TypeBox/AJV input and output validation, explicit parameter injection, and MCP SDK server construction.

It deliberately does not include HTTP routing, authentication, authorization, tenant policy, or application-specific context. Each host application supplies those concerns at its own boundary.

Install and register

Add the workspace package as a dependency, then import NestMcpModule once in the application's root module or a module visible to all MCP tool providers.

import { Module } from "@nestjs/common";
import { NestMcpModule } from "@markygab/nest-mcp";

import { ProjectsModule } from "./projects/projects.module.js";

@Module({
  imports: [NestMcpModule, ProjectsModule],
})
export class AppModule {}

The package uses Nest's DiscoveryService to find decorated providers across the application container. Tool classes must still be registered as normal Nest providers in their feature modules.

Define a tool

Use TypeBox schemas for inputs and, where practical, outputs. @McpTools() assigns the provider to one named MCP server. @McpTool() declares a single tool, while @McpArgs() and @McpContext() make handler injection explicit.

import { Inject, Injectable } from "@nestjs/common";
import {
  McpArgs,
  McpContext,
  McpTool,
  McpTools,
  type McpRequestContext,
  type McpToolArgs,
} from "@markygab/nest-mcp";
import { Type } from "@sinclair/typebox";

import { ProjectsQueryService } from "./projects-query.service.js";

const GetProjectInput = Type.Object({
  id: Type.String({ minLength: 1 }),
});
const GetProjectOutput = Type.Object({
  project: Type.Union([
    Type.Object({ id: Type.String(), name: Type.String() }),
    Type.Null(),
  ]),
});

type GetProjectInput = McpToolArgs<typeof GetProjectInput>;

@Injectable()
@McpTools("projects_mcp")
export class ProjectsMcp {
  constructor(
    @Inject(ProjectsQueryService)
    private readonly projects: ProjectsQueryService,
  ) {}

  @McpTool({
    name: "projects_get",
    title: "Get project",
    description: "Get a project visible to the current caller.",
    inputSchema: GetProjectInput,
    outputSchema: GetProjectOutput,
  })
  async getProject(
    @McpArgs() input: GetProjectInput,
    @McpContext() context: McpRequestContext,
  ) {
    return {
      project: await this.projects.getVisibleTo(context.actorId, input.id),
    };
  }
}

Tool names must be unique within a named server. Keep handlers thin: enforce application policy and call existing domain services rather than placing vendor-client or persistence logic in MCP classes.

Tool schemas

@McpTool() accepts TypeBox schemas and ordinary JSON Schema for both input and output. TypeBox remains a convenient authoring option and McpToolArgs<typeof schema> continues to infer its handler type. For plain JSON Schema—such as a schema derived from an OpenAPI document—supply your own generated or application type for the handler argument; arbitrary JSON Schema is not inferred as TypeScript.

const CreateIssueInputSchema = {
  type: "object",
  properties: {
    priority: { type: "string", enum: ["low", "high"] },
    title: { type: "string" },
  },
  required: ["priority", "title"],
} as const;

type CreateIssueInput = {
  priority: "low" | "high";
  title: string;
};

@McpTool({
  name: "issues_create",
  description: "Create an issue",
  inputSchema: CreateIssueInputSchema,
})
createIssue(@McpArgs() input: CreateIssueInput) {
  return this.issues.create(input);
}

Guard tool invocations

@UseMcpGuards() attaches policy-agnostic guards to a tools class or an individual tool. Guards run after the input schema is validated and before the handler. Class guards run first, followed by method guards. Return false or throw to prevent invocation; the caller receives the normal MCP tool error response. Pass either a guard instance or an injectable Nest provider class; provider classes are resolved from the application container.

import { Injectable } from "@nestjs/common";
import {
  McpArgs,
  McpTool,
  McpTools,
  UseMcpGuards,
  type McpExecutionContext,
  type McpGuard,
} from "@markygab/nest-mcp";

const auditGuard: McpGuard = {
  canActivate(context: McpExecutionContext) {
    // validatedArgs, serverName, toolName, requestContext, and toolOptions
    // are available here. Application policy remains outside this library.
    return true;
  },
};

@Injectable()
class ProjectsAccessGuard implements McpGuard {
  canActivate(context: McpExecutionContext) {
    return Boolean(context.requestContext.actorId);
  }
}

@McpTools("projects_mcp")
@UseMcpGuards(auditGuard, ProjectsAccessGuard)
class ProjectsMcp {
  @McpTool({ name: "projects_get", description: "Get a project", inputSchema: GetProjectInput })
  @UseMcpGuards({ canActivate: () => true })
  getProject(@McpArgs() input: GetProjectInput) {
    return { project: input.id };
  }
}

Intercept tool invocations

@UseMcpInterceptors() wraps a permitted tool invocation. It accepts McpInterceptor objects or injectable Nest provider classes and may be applied to a tools class or a single tool. Provider classes are resolved from the application container. Interceptors receive the same McpExecutionContext as guards, including the validated arguments and trusted request context. Class interceptors enter in declaration order, then method interceptors; they unwind in reverse order. Thrown errors propagate to the standard MCP tool error response.

import { Injectable } from "@nestjs/common";
import {
  UseMcpInterceptors,
  type McpExecutionContext,
  type McpInterceptor,
} from "@markygab/nest-mcp";

@Injectable()
class TimingInterceptor implements McpInterceptor {
  async intercept(context: McpExecutionContext, next) {
    const startedAt = Date.now();

    try {
      return await next();
    } finally {
      // Hosts decide whether and where to record this information.
      console.log(context.toolName, Date.now() - startedAt);
    }
  }
}

@UseMcpInterceptors(TimingInterceptor)
class ProjectsMcp {
  // @UseMcpInterceptors(...) can also be applied to an @McpTool() method.
}

Request context and policy

McpRequestContext contains common request identifiers, optional actor and tenant fields, an optional integration object, and allowedToolNames. Applications can add their own fields when creating the context.

When a request context contains allowedToolNames, the package hides every other tool from both tools/list and tools/call. Authentication and authorization should run before the MCP request reaches the package; build the trusted context from the verified principal and route parameters, never from model-provided tool arguments.

Serve over HTTP

The host owns the controller, authentication, and request-context mapping. Add a controller and transport service to the application that imports NestMcpModule; the example below exposes POST, GET, and DELETE requests at /mcp/projects_mcp, as required by Streamable HTTP clients.

import {
  All,
  Controller,
  Inject,
  Injectable,
  Module,
  Param,
  Req,
  Res,
} from "@nestjs/common";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { McpServerService, type McpRequestContext } from "@markygab/nest-mcp";
import type { Request, Response } from "express";

@Injectable()
export class ProjectsMcpHttpService {
  constructor(
    @Inject(McpServerService)
    private readonly mcpServer: McpServerService,
  ) {}

  async handle(
    serverName: string,
    request: Request,
    response: Response,
    context: McpRequestContext,
  ) {
    const transport = new StreamableHTTPServerTransport({
      // Use stateless requests when the host does not persist MCP sessions.
      sessionIdGenerator: undefined,
    });
    const server = this.mcpServer.createServer(serverName, context);

    await server.connect(transport);

    try {
      await transport.handleRequest(request, response, request.body);
    } finally {
      await transport.close();
    }
  }
}

@Controller("mcp")
export class ProjectsMcpHttpController {
  constructor(
    @Inject(ProjectsMcpAuthService)
    private readonly auth: ProjectsMcpAuthService,
    @Inject(ProjectsMcpHttpService)
    private readonly http: ProjectsMcpHttpService,
  ) {}

  @All(":serverName")
  async handle(
    @Param("serverName") serverName: string,
    @Req() request: Request,
    @Res() response: Response,
  ) {
    const context = this.auth.verifyAuthorization(
      request.header("authorization"),
      serverName,
    );

    await this.http.handle(serverName, request, response, context);
  }
}

Register these host-side providers alongside the shared module:

@Module({
  imports: [NestMcpModule],
  controllers: [ProjectsMcpHttpController],
  providers: [ProjectsMcpAuthService, ProjectsMcpHttpService],
})
export class ProjectsMcpModule {}

ProjectsMcpAuthService should verify the bearer token and return only trusted context, for example { requestId, actorId, tenantId, allowedToolNames }. Bind the token to serverName so a credential issued for projects_mcp cannot be reused against another named server. If you use stateful MCP sessions, replace the stateless transport configuration with a host-managed session ID strategy and retain the corresponding transport for later requests.

The host application owns the corresponding controller, authentication service, and transport service.

Runtime limits

Set these optional environment variables in the host process to bound tool execution and serialized responses:

• NEST_MCP_TOOL_TIMEOUT_MS defaults to 15000.
• NEST_MCP_TOOL_RESPONSE_MAX_BYTES defaults to 128000.

Both values must be positive integers.

Serve over stdio

For a local process, retrieve McpServerService from the Nest application context and provide the named server explicitly:

const app = await NestFactory.createApplicationContext(AppModule);
await app.get(McpServerService).startStdio("projects_mcp");

Exports

• NestMcpModule - registers discovery, validation, invocation, and server providers.
• McpTools, McpTool, McpArgs, McpContext - tool-definition decorators.
• McpServerService - creates MCP SDK server instances, lists tools, and calls tools programmatically.
• McpRequestContext, McpToolArgs, McpToolOptions, and tool metadata types.