Nestjs MCP

@jsirp/nestjs-mcp

Runtime MCP inspector embedded in your NestJS app, for coding agents.

Add one module and your running app opens an MCP endpoint, on a port of its own, that tells an agent (Claude Code, Cursor, any MCP client) what Nest actually built: the module and provider graph, every route with the guards, interceptors, pipes and filters it goes through, what the app's Logger is writing right now, which enhancers a given request passed through and how long each took, event listeners and scheduled jobs. Nothing to install on the agent side: it points at http://127.0.0.1:7777/.

Status: released (changelog). Every tool group in Tools works on Nest 10 and 11.

Contents

• Install: a regular dependency, not a devDependency
• Quick start, one module on its own endpoint, options from a configuration source
• Point your agent at it
• Options
• Tools: graph, routes and enhancers, logs and your own logger, request traces, debug, events, scheduled jobs, runs
• How it works, Security, Limitations
• Contributing, License

Install

npm install @jsirp/nestjs-mcp

Install it as a regular dependency, not a devDependency. Your AppModule imports it, so a production install that leaves devDependencies out (npm ci --omit=dev, yarn workspaces focus --production, the last stage of most Docker images) would make the app fail at startup with Cannot find module '@jsirp/nestjs-mcp', before any option is read. In production it costs nothing but disk: enabled defaults to false there, and then the module opens no listener, copies no logs and wraps nothing.

If you want it out of production builds altogether, keep it in devDependencies and import it only where it is installed, so the production bundle never resolves it:

import { DynamicModule, Module } from '@nestjs/common';

const inspector: DynamicModule[] = process.env.NODE_ENV === 'production' ? [] : // eslint-disable-next-line @typescript-eslint/no-require-imports [require('@jsirp/nestjs-mcp').NestMcpModule.forRoot()];

@Module({ imports: [...inspector] }) export class AppModule {}

In an ES module app, use await import('@jsirp/nestjs-mcp') behind the same condition.

Everything a Nest app already has is a peer dependency: @nestjs/common and @nestjs/core 10 or 11, reflect-metadata, rxjs, and zod (3.25+ or 4, the versions the MCP SDK accepts). @nestjs/event-emitter and @nestjs/schedule are optional peers: their tools appear only if your app uses them. The only runtime dependency is @modelcontextprotocol/sdk.

The supported way to consume the package is the published npm package. Listing a checkout of this repository (a clone or a git submodule) as a workspace of a host monorepo is not supported: the repo keeps its own yarn.lock, which its CI and standalone development need, so Yarn treats that folder as a separate project and scripts run inside it fail until it gets its own install; and that install, or any workspace install, brings in the package's devDependencies, a second copy of Nest that the host's dependency injection does not recognise (Nest can't resolve dependencies of the NestMcpModule). The published tarball holds only dist/, this README, the changelog and the license, and npm never installs a package's devDependencies, so the app's own Nest is the only one. To try unreleased changes in an app, build here and install the result of npm pack in the app.

Quick start

import { Module } from '@nestjs/common';

import { NestMcpModule } from '@jsirp/nestjs-mcp';

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

Create the app with snapshot: true so Nest keeps the graph the graph_* and routes_* tools read:

const app = await NestFactory.create(AppModule, { snapshot: true });

At startup the module opens the inspector's own HTTP listener, next to your app's server and independent of it, and logs the endpoint, with context NestMcp:

[NestMcp] Inspector listening at http://127.0.0.1:7777/

Nothing of your app runs in front of it: no global prefix, no versioning, no middlewares, no global guards, interceptors, pipes or filters. Your auth guard never sees an inspector call, your request logger never logs one, your OpenAPI document does not list it, and the inspector's calls never show up in its own request traces. The listener closes with the app (app.close()).

One module on its own endpoint

forFeature mounts an instance whose scope is the module that imports it and everything that module imports. path is required. Any number of instances may coexist, each with its own path, authorize and switches, all on the same listener: forRoot answers at /, each forFeature at its path (http://127.0.0.1:7777/cats below).

The scope is resolved from the serialized graph at the first tool call, so it needs snapshot: true too: app_info.scope then reads { "kind": "module", "module": "CatsModule" }. Without snapshot, it reads { "kind": "module", "module": null, "error": "scope_unresolved", "fallback": "app" }. The closure leaves out Nest's internal modules and the instance's own module, and takes in every global module (@Global(), isGlobal: true) and what it imports: the module can inject what they export without declaring them.

@Module({

imports: [NestMcpModule.forFeature({ path: 'cats' })], }) export class CatsModule {}

Options from a configuration source

forRootAsync and forFeatureAsync follow Nest's configurable-module pattern, so any source works. With @nestjs/config, as an example:

NestMcpModule.forRootAsync({

imports: [ConfigModule], inject: [ConfigService], useFactory: (config: ConfigService) => ({ enabled: config.get('INSPECTOR_ENABLED') === 'true', }), });

`path` is given statically, next to useFactory, not returned by it, so a forFeatureAsync without it fails at once. Everything else, listen and authorize included, may come from the factory. enabled may go either way: given statically and false, nothing is registered; returned by the factory as false, the instance does not join the listener (with no other instance, no listener is opened) and nothing else is installed.

Point your agent at it

Claude Code:

claude mcp add --transport http my-nest-app http://127.0.0.1:7777/

Or any client that reads an mcpServers file:

{

"mcpServers": { "my-nest-app": { "type": "http", "url": "http://127.0.0.1:7777/" } } }

The URL does not depend on your app's port, prefix or versioning. Two apps on one machine need two ports: give each its own listen.port.

Options

All optional, except path in forFeature.

authorize is a plain function, not a Nest guard: there is no ExecutionContext. Close over what it needs, or build it in a forRootAsync factory from injected services:

NestMcpModule.forRootAsync({

imports: [ConfigModule], inject: [ConfigService], useFactory: (config: ConfigService) => ({ listen: { host: '0.0.0.0', port: 7777 }, authorize: (req) => req.headers['x-inspector-key'] === config.get('INSPECTOR_KEY'), }), });

Tools

| runs | runs_list, run_get (on