io.github.jsirp-dev/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

Every tool returns JSON as a single text block. Errors come back as { "error": "<code>", "hint": "…" } with isError: true, plus what helps to retry (candidates, for example).

Graph

Read from the serialized graph Nest keeps with snapshot: true, never from source. Every answer, errors included, carries scope, the boundary the instance observes: a forFeature instance lists only the modules in its closure, and the providers, dependencies and cycles among them.

• Tokens are text: a class by its name, a string or symbol token by its description. Instances are never returned.
• Nest's own modules and providers (InternalCoreModule, ModuleRef, ApplicationConfig, …) are hidden unless includeInternal: true.
• imports is what a module declares. Nest also links every module to every global module, and those links go to globals (with InternalCoreModule under includeInternal: true); a global module the module declares stays in imports. graph_cycles leaves the global links out: they would make every global module a cycle with whatever imports it.
• Modules that share a class name (two dynamic instances of one module, for example) are listed as Name#1, Name#2 in the order Nest registered them; use those names as input.
• dependsOn and dependents count constructor and property injection. Enhancers attached with @UseGuards and friends are not dependencies; the routes tools report them.
• An unknown name answers not_found with up to five similar candidates; a token declared in several modules answers ambiguous with each { token, module }, and module picks one.

Routes and enhancers

Every HTTP route Nest registered whose controller is in the instance's scope. The inspector is not one of them: it is not a controller. Routes that an RPC layer implements as controller handlers are ordinary routes; one served by a middleware of its own is not a route here.

• path is what the app serves, as Nest computed it: global prefix (unless the route is in its exclude list) and the URI version. rawPath is the controller and method paths alone, the one to use with header or media-type versioning. route_get takes either; a raw path shared by several versions answers ambiguous with the full paths.
• version is the handler's version, or the controller's, or defaultVersion; VERSION_NEUTRAL is 'neutral'. Without versioning there is none.
• Each enhancer is { name, level }, a class name and never an instance. Each list is in the order Nest runs it:

  Level	Comes from
  global	app.useGlobalGuards(...) and friends, and APP_GUARD / APP_INTERCEPTOR / APP_PIPE / APP_FILTER providers, in the order Nest registered them
  controller	@UseGuards, @UseInterceptors, @UsePipes, @UseFilters on the controller class
  method	The same decorators on the handler; then parameter pipes, which carry param ('id' for @Param('id', ParseIntPipe), #n for an argument without a name)

• Filters are listed in the same order but resolved the other way round: Nest tries the method's filters first, then the controller's, then the globals, and the first whose @Catch matches handles the exception.
• middlewares are the middlewares whose forRoutes path and method match the route's raw path. Plain paths match exactly; wildcards match by the prefix before them, and exclude(...) is not read, so the list is approximate (route_get says so in middlewaresMatch).
• A function middleware (consumer.apply((req, res, next) => next()), or nestjs-pino's two) reads <functional middleware from LoggerModule>, after the module whose configure applied it. Nest wraps the function in a class with a random name and keeps the function only in a closure, so its own name cannot be read. Each one is listed once.

Logs

At startup the module wraps the logger your app set (with app.useLogger, the logger option of NestFactory.create, or Nest's default ConsoleLogger) in a transparent tee: every call to Nest's Logger reaches your logger exactly as it was made, and a copy goes to an in-memory ring buffer of logs.bufferSize entries. Nothing is masked, filtered or altered, and nothing is persisted. If your services log through a logger of their own (PinoLogger, winston…), hand its output to the same buffer with a log sink. The tee and the buffer are installed once per process and shared by every instance: the first instance that installs them decides logs.bufferSize, and an instance with logs.capture other than 'sink' installs the tee, so give every instance with the logs group on the same logs. Switching the logs group off in every instance installs nothing.

• Levels are Nest's: verbose, debug, log, warn, error, fatal. minLevel keeps that level and the more severe ones.
• source says where an entry came from: 'nest' for Nest's Logger, 'sink' for your logger through the sink.
• context is the trailing string argument, as ConsoleLogger reads it: the class name for a new Logger(MyService.name). In error, the multi-line string before it is the stack. Non-string messages are stored as JSON, capped at 2000 characters.
• seq grows by one per entry and never repeats. Without sinceSeq the answer is the newest limit entries; with it, the oldest limit after it, so paging never skips or repeats one.
• A forFeature instance keeps only entries whose context is the name of a class in its scope (controllers, providers, injectables) and says so in scopeFilter. It is approximate: a context that is not a class name, or a class name shared with another module, is judged by name alone. scope: 'app' lifts the filter.
• A level your logger reports as disabled (isLevelEnabled) is forwarded as usual but not copied, so the buffer holds what your logger keeps. With logger: false nothing is printed, as before, and the buffer still fills.
• The inspector's own lines (context NestMcp) are in the buffer too.
• requestId is the id of the request being traced when the entry was captured (the correlation header's value, or the generated id requests_list shows); logs_tail({ requestId }) reads one request's lines and request_trace lists them. It is read from the request's async context at the moment the tee or the sink receives the line, so an entry written outside a request has none, and so has a sink line delivered outside that context: one your logger hands over later (an asynchronous transport, a worker-thread destination such as pino.transport) or one the sink held before it was connected. A line logged by a middleware that runs after one that lost the async context (and before the first guard) has none either, nor has one written once the response is sent (a res.on('finish') listener, such as pino-http's request completed line) of a request whose context was lost: Node calls it where Nest's router ended the response. It needs the requests group on; without it no entry carries one.
• runId is, likewise, the id of the job or listener run executing when the entry was captured; logs_tail({ runId }) and run_get read a run's lines. A line a listener writes while it runs inside a request carries both ids. It needs the runs group on.

Reading your own logger

The tee sees only what goes through Nest's Logger. A service that logs through a logger of its own writes past it: with nestjs-pino, this is what reaches logs_tail:

createLogSink() returns a log sink: a writable stream your logger writes to like any other output, plus a record(entry) function for loggers that hand over objects. Create it before your logger, add it to the logger's outputs and pass it as logs.sink (from forRoot, or returned by a forRootAsync factory). The sink only reads: your other outputs get exactly what they got before, and it never throws into your logger (a failure is swallowed and counted in logs_levels.sink).

pino, with nestjs-pino. Write to stdout and to the sink with pino.multistream:

import { Module } from '@nestjs/common';
import { createLogSink, NestMcpModule } from '@jsirp/nestjs-mcp';
import { LoggerModule } from 'nestjs-pino';
import pino from 'pino';

const logSink = createLogSink();

@Module({
  imports: [
    LoggerModule.forRoot({
      pinoHttp: [
        { level: 'debug' },
        pino.multistream([
          { stream: process.stdout, level: 'debug' },
          { stream: logSink, level: 'debug' },
        ]),
      ],
    }),
    // app.useLogger(app.get(Logger)) routes Nest's Logger through pino too: read it once, from the sink.
    NestMcpModule.forRoot({ logs: { sink: logSink, capture: 'sink' } }),
  ],
})
export class AppModule {}

The sink must run in your process: add it to multistream (or as a plain stream), not as a pino.transport target, which runs in a worker thread.

winston, with or without nest-winston. A transport that hands each record to record:

import { createLogSink, NestMcpModule } from '@jsirp/nestjs-mcp';
import * as winston from 'winston';
import Transport from 'winston-transport';

const logSink = createLogSink();

class InspectorTransport extends Transport {
  override log(info: unknown, next: () => void): void {
    logSink.record(info);
    next();
  }
}

export const logger = winston.createLogger({
  transports: [new winston.transports.Console(), new InspectorTransport()],
});

// In AppModule. With WinstonModule as the app logger, Nest's Logger goes through winston too:
NestMcpModule.forRoot({ logs: { sink: logSink, capture: 'sink' } });

What the sink reads out of the box:

• pino and bunyan JSON lines: the numeric level (10 → verbose, 20 → debug, 30 → log, 40 → warn, 50 → error, 60 → fatal), msg, time, context (what nestjs-pino and nest-winston set) or else name, and the stack of err.
• Objects passed to record, such as winston's: a level name (info → log, warning → warn, trace and silly → verbose…, colour codes ignored), message, timestamp, context.
• Plain text: each line is a log entry with the line as its message and no context.

One write may carry several lines; each is one entry. Anything else maps with logs.normalize, which receives the parsed JSON line, the plain-text line as a string, or what you passed to record, and returns { level?, message?, context?, timestamp?, stack? }, or undefined to use the built-in mapping:

NestMcpModule.forRoot({
  logs: {
    sink: logSink,
    normalize: (record) =>
      typeof record === 'object' && record !== null && 'severity' in record
        ? { level: String(record.severity), message: (record as { text?: string }).text }
        : undefined,
  },
});

Which logs.capture to pick:

• 'both' (the default): your services log through their own logger and Nest's Logger prints elsewhere (Nest's ConsoleLogger, for example). Nothing is duplicated.
• 'sink': Nest's Logger also writes through the logger the sink is attached to (nestjs-pino's or nest-winston's logger set with app.useLogger). With 'both' each of those lines would be there twice, once per source. No tee is installed, so logs_levels.levels is null.
• 'nest': the sink is ignored.

What arrives before the app starts is held by the sink (up to 1000 entries) and delivered when the inspector connects it; when the app closes, the sink is disconnected and holds again. With the inspector disabled the sink is never connected, so it only keeps those last 1000 lines; leave it out of your logger's outputs where you never enable the inspector.

Request traces

Fire a request at the app, then ask where it went. Set the correlation header (x-nest-mcp-request-id, or your requests.idHeader) to an id of your choosing and read the trace by that id; without the header the request gets a generated id, and requests_list finds it.

curl -H 'x-nest-mcp-request-id: try-1' http://localhost:3000/api/cats/abc
# then, from the agent: request_trace { "id": "try-1" }

Each step is { kind, name, level?, outcome, error?, startedAtMs, durationMs }, timed from the start of the request:

So GET /api/cats/abc on a route with an API-key guard, a timing interceptor and ParseIntPipe reads ApiKeyGuard allowed → TimingInterceptor enter → ParseIntPipe(id) threw BadRequestException → TimingInterceptor exit threw, status 400.

• What a trace stores: method, the URL with its query string, route pattern, status, timings, controller, handler and steps; request headers per requests.headers: 'none', 'names' (the default, names only) or 'full' (names and values, credentials included: choose it knowingly). Bodies are never stored, neither of requests nor of responses.
• The correlation header is read, never echoed back: the response carries nothing it did not carry before. To reuse an id your app already propagates (x-request-id from a proxy or request logger), set requests.idHeader: 'x-request-id'.
• level (global, controller, method) comes from the route's enhancer chain, so it needs snapshot: true, like module. Without it the steps are there and those fields are not.
• A forFeature instance lists only traces whose handler is in its scope; a request that matched no route has no handler and is seen from app scope only. scope: 'app' lifts the filter.
• The inspector's own calls are never traced: they arrive on its listener, not through Nest. One ring buffer of requests.bufferSize traces per app, shared by its instances; the first instance with the requests group on decides requests.*.
• Enhancers in REQUEST or TRANSIENT scope have no long-lived instance to observe; a trace lists the ones on its route in notTraced.
• logs (with the logs group on) are the log entries written during this request that the logs buffer still holds, oldest first, as logs_tail answers them: Nest's own exceptions handler logs an unhandled error inside the request, so a 500 lists that line too. At most 200, the newest, with logsTruncated: true when more matched; logsDropped: true when the buffer already discarded some of them, so the list is not taken for the whole. Lines of an earlier request that reused the same id are not listed. They are listed whatever the instance's scope, since the trace itself already is in scope. Lines are matched as requestId says, with its limits.

Debug: stacks of failing steps

With debug: true, every error in a trace (on the step that threw, and on the filter step with the exception it caught) and the error of a run carry stack: the exception's frames, from the throw outwards, at most debug.stackFrames (30).

"error": {
  "name": "NotFoundException",
  "message": "Cat 999 not found",
  "stack": [
    { "function": "CatsController.findOne", "file": "/app/src/cats/cats.controller.ts", "line": 31, "column": 21, "mapped": true },
    { "function": "<anonymous>", "file": "/app/node_modules/@nestjs/core/router/router-execution-context.js", "line": 38, "column": 29, "mapped": false, "external": true }
  ]
}

• file, line and column are the original source's when a source map is found (mapped: true): Node's own, when the process runs with --enable-source-maps or process.setSourceMapsEnabled(true) (then the stack is already mapped and read as it is), or else the one the compiled file points to with its sourceMappingURL comment (a .js.map next to it, as tsc and the Nest CLI write with sourceMap: true, or an inline map). Without one, the frame keeps the compiled position with mapped: false. A position in a file that is not JavaScript (.ts) is mapped: true: something mapped it already, or the process runs it as it is. The inspector never turns source maps on in the process; app_info.debug.sourceMaps says whether Node applies them (process) and how many compiled files' own maps the inspector has read (files).
• function is the name V8 writes (CatsController.find, new Thing, async Promise.all), <anonymous> without one; an anonymous async frame (at async /app/dist/main.js:3:7) is async <anonymous>, with the path alone in file, mapped like any other.
• external: true flags frames in node_modules, node: internals and frames without a file (<anonymous>, native), so an agent can skip to your code. They are kept, unmapped.
• stack holds positions only: function name, file, line, column. No source text (a map's sourcesContent is dropped when it is read). The values in scope are in locals, below.
• Off, nothing changes: errors are { name, message } as before, no stack is read and no worker or inspector session exists.
• The stack is read when the error is recorded, from error.stack, as any logger would read it; a compiled file's map is read once and kept. How many frames there are is V8's Error.stackTraceLimit (10 unless your process raises it); the inspector does not change it.

Locals at the throw

With debug on (and debug.locals not false), the error of the step that threw, and of a failing run, also carries locals: the variables in scope in the top frames at the moment of the throw, aligned with stack (locals[0] is the frame stack[0] names when the error was created where it was thrown, as usual).

"error": {
  "name": "Error",
  "message": "failed with 42",
  "stack": [{ "function": "OrdersController.total", "file": "/app/src/orders.controller.ts", "line": 18, "column": 11, "mapped": true }, "…"],
  "locals": [
    {
      "function": "OrdersController.total",
      "file": "/app/src/orders.controller.ts",
      "line": 18,
      "scopes": {
        "local": { "total": 42, "order": { "[[Class]]": "Order", "id": 7, "lines": "[Array(2)]" }, "note": "nnnn…[500 chars]" },
        "closure": { "TAX": 0.21 }
      }
    },
    { "function": "<anonymous>", "file": "/app/node_modules/@nestjs/core/router/router-execution-context.js", "line": 38, "external": true }
  ]
}

• What is read: the local scopes (block and catch scopes merged in) and closure scopes of the top debug.locals.frames frames; never module, script or global scopes. Frames outside your code (node_modules, node:) are listed with external: true and not read.
• How values look: strings, numbers, booleans and null as they are; plain objects and arrays depth levels deep, then [Object], [Array(3)] or the class name; class instances with "[[Class]]"; undefined, NaN, 42n, symbols as bracketed strings; functions by name ([Function: find]), never their source; a Map, Set, Date, Promise or proxy by its description, never entered. Only own enumerable data properties are read: a getter shows as [Getter] and is never called. Nothing in your app is evaluated.
• Bounds: properties per object (and variables per scope, and items per array), with "…": "[N more]"; strings cut at stringLength with their length; at most bytes of JSON per error, after which reading stops and the error says localsTruncated: true; at most perMinute captures, after which the error says localsSkipped: 'rate' and nothing is read.
• Which exceptions: those your own code throws while a traced request or a run is in flight. Exceptions thrown with nothing in flight (startup, a timer of yours) are never read, nor those thrown inside node_modules (a pipe's BadRequestException), nor your code rethrowing from a catch block the error it caught (the first throw keeps its locals). Exceptions your code throws and catches itself during a request are read too, and count against the rate.
• One step, not all of them: in request_trace the locals go on the first step that recorded the exception, the one that threw; the interceptors it passed through and the filter that caught it carry its stack (and localsSkipped, when there is one) without them.
• When none are given: two exceptions with the same stack text pending at once (the same code failing in two concurrent requests) are not told apart: the error says localsSkipped: 'ambiguous' rather than show another request's values. An exception whose stack your code replaced after the throw, or that is not an Error, gets none.
• What it costs: the main thread stops at every exception while the worker decides; measured on an M-series Mac, Node 20 and 22, about 0.13 ms per exception it does not read and about 1.8 ms per exception it reads (the CHANGELOG has the numbers). It is a development tool; turn it off under load.
• It can expose anything that was in scope: a password a handler compared, the body it parsed, a token in a closure. Keep debug to development, and protect the endpoint as the Security section says.
• With your own debugger attached: the worker is one more debugger session. Pauses it did not cause (your breakpoints) are left alone, but pauses on exceptions are resumed by it, including ones you asked your debugger for ("pause on caught exceptions"). Set debug.locals: false while you debug by hand.

Events

With @nestjs/event-emitter installed and EventEmitterModule imported, the inspector lists who listens to what and records what was emitted. Without the package, or without its module, there are no events_* tools and app_info.tools.events is false.

• Listeners come from the @OnEvent metadata of every provider and controller, request-scoped ones included. With event, a listener matches when its pattern contains the text or when the emitter itself would call it for that event: with wildcard: true, events_listeners { "event": "cat.adopted" } returns the cat.* listeners too.
• Emissions are recorded by wrapping emit and emitAsync on the app's EventEmitter2: the event name, the method, the time and listenerCount(event) at that moment. Payloads are never kept. The wrapper returns exactly what the original returned (the boolean, the same promise) and throws what it threw. event filters by substring or, as a pattern, through the emitter (cat.*).
• A forFeature instance lists only listeners declared in its scope. Emissions have no module, so every instance sees all of them; one buffer of the latest 500 per emitter, shared by the instances.

Scheduled jobs

With @nestjs/schedule installed and ScheduleModule imported, the inspector lists what the app's SchedulerRegistry holds. Without the package, or without its module, there is no schedule_jobs and app_info.tools.schedule is false.

// schedule_jobs { "kind": "cron" }, for @Cron('0 3 * * *', { name: 'cleanup' }) on CatsService
{ "scope": { "kind": "app" }, "jobs": [{ "kind": "cron", "name": "cleanup", "className": "CatsService",
  "methodName": "cleanup", "module": "CatsModule", "expression": "0 3 * * *", "running": true,
  "nextRun": "2026-10-26T03:00:00.000+01:00" }] }

• The registry is read on every call: cron jobs (expression, running, lastFiredAt as the CronJob knows it, and nextRun while running), intervals (everyMs) and timeouts (delayMs; running: false once fired or cleared), the ones the app added with addCronJob/addInterval/addTimeout included. timeZone appears when it differs from the process's own.
• Class, method and module come from the @Cron/@Interval/@Timeout metadata, matched to the registry by name; a decorator without a name, which the registry knows by a generated id, is matched by its expression or period when exactly one job has it.
• A forFeature instance lists only jobs declared by classes in its scope. A job the app added to the registry by hand has no class, so only scope: 'app' (or a forRoot instance) lists it.
• With the runs group on, a decorated job carries lastRun ({ id, startedAt, outcome, durationMs? }), its latest run; so does each listener of events_listeners.

Runs

With @nestjs/schedule or @nestjs/event-emitter installed and its module imported, the inspector records each execution (a run) of the decorated jobs and of the @OnEvent listeners: what ran, when, for how long, and whether it threw, with the error, even though the scheduler and the emitter catch it and only log it. Without either package, or with tools.runs: false, nothing is wrapped, there are no runs_list or run_get and app_info.tools.runs is false.

// runs_list { "outcome": "threw" }, for @Cron('0 5 * * *', { name: 'purge' }) that threw
{ "scope": { "kind": "app" }, "runs": [{ "id": "…", "kind": "cron", "className": "JobsService",
  "methodName": "purge", "module": "JobsModule", "name": "purge",
  "startedAt": "2026-10-26T05:00:00.002Z", "durationMs": 1.42, "outcome": "threw",
  "error": { "name": "Error", "message": "purge failed" } }] }

• Only what the scheduler or the emitter starts is a run. A call your code makes to the method itself is not recorded. name matches the job's decorator name or Class.method; event matches a substring of the emitted event or, as a pattern, what the emitter would match (cat.*).
• Never the event payload or the job's arguments. A run keeps the class, method, module, job name or event, times, outcome and the error's name and message (and its stack with debug, and its locals, where the method's arguments are in scope); requestId when it started inside a traced request.
• The error line the scheduler (Scheduler) or the emitter (Event) logs after the method threw is written outside the run, so it is in logs_tail without the runId; the run's error has what was thrown.
• A forFeature instance lists only runs of classes in its scope. One buffer of the latest runs.bufferSize runs per app, shared by the instances; a run in progress has outcome: 'running'.

How it works

• Stateless Streamable HTTP. Each POST gets its own MCP server and transport, answered and closed. GET and DELETE return 405 with Allow: POST: there are no sessions to stream to or tear down.
• Its own listener. A plain node:http server, one per app, opened by the first instance at onApplicationBootstrap and closed when the app closes. It routes each request by path to its instance, runs that instance's authorize, and hands the raw request to the MCP transport. No controller is registered, so nothing of the app (prefix, versioning, middlewares, enhancers, OpenAPI generation) touches it, and it works in an app that never calls listen.
• Traces by wrapping enhancer instances. With the requests group on, the module wraps, in place, canActivate, intercept, transform and catch on the guard, interceptor, pipe and filter instances Nest built (global, per controller and per route) before Nest builds the routes. Each wrapper records a step into the current request's trace, held in an AsyncLocalStorage that a middleware opens, and returns exactly what the original returned, with the same this and the same exceptions. When a middleware after it loses that async context (one that calls next from a stream callback, as multer before 2.3 does), guards, interceptors and filters find the trace by the request object and run the rest of the request back inside it; the Observable an interceptor returns is subscribed inside it too, so its exit phase (what runs after next.handle()) keeps it. It also adds one global interceptor of its own, which names the handler. With the group off, nothing is wrapped and neither is installed.
• Emissions by wrapping the emitter. With the events group on and the app's EventEmitter2 in the container, emit and emitAsync are replaced on that instance, once, by functions that record the event name and listener count and then call the original. Nothing else of the emitter changes.
• Scheduled jobs by reading the registry. With the schedule group on, the module finds the app's SchedulerRegistry and reads it per call. Nothing is wrapped, started or stopped.
• Runs by wrapping job and listener methods. With the runs group on, before any onModuleInit, the module defines on each long-lived provider or controller with a @Cron, @Interval, @Timeout or @OnEvent method an own property wrapping it, carrying the original's metadata so the scheduler and the emitter still find the decorators. The scheduler binds the job wrapper at its onModuleInit, and at onApplicationBootstrap the module takes the property back, so your own calls go to the original. Listener wrappers stay, and record only when called inside an emit/emitAsync (wrapped to know the event) for an event the method listens to. Each wrapper returns what the original returned (the same promise) and throws what it threw (ADR-0006).
• Stacks by reading error.stack. With debug on, the error a step or a run records is parsed from the stack V8 formatted, and each frame is looked up in the compiled file's source map (node:module's findSourceMap and SourceMap; no dependency). Nothing is installed: no Error.prepareStackTrace, no change to Error.stackTraceLimit or to the process's source maps.
• Locals through a worker's inspector session. With debug.locals, a worker thread opens a node:inspector session on the main thread (connectToMainThread), with breakpoints inactive and pause on every exception. On a pause it reads, only when a trace or run is in flight (a counter in shared memory) and the frame is your code, the scopes with Runtime.getProperties, posts them and resumes; the main thread pairs the capture with the error by its stack text when it records it. No Runtime.evaluate, no callFunctionOn, no breakpoint is ever set (ADR-0005). The worker starts with the first instance and stops when the last one is destroyed.
• Nothing leaves the process. The server runs inside your app; the only network is the agent calling the inspector's listener.

Security

The inspector shows the inside of your app. By default it is off in production and its listener binds to loopback (127.0.0.1), so only the machine itself reaches it. If you open it beyond loopback, check every request with authorize:

NestMcpModule.forRoot({
  enabled: true,
  listen: { host: '0.0.0.0' },
  authorize: (req) => req.headers.authorization === `Bearer ${process.env.INSPECTOR_TOKEN}`,
});

Listening beyond loopback without authorize works, and logs a warning at every startup. Your app's own guards do not run on the inspector: to put your existing authentication in front of it, call it from authorize or put a reverse proxy before the listener.

debug raises the stakes: with it, traces and runs carry the values of local variables at each throw (Locals at the throw), which may include secrets and request bodies. It is off by default, whatever enabled is.

Limitations

• Verified with Express. Fastify is not supported in v1.
• graph_* and routes_* need snapshot: true in NestFactory.create; without it the module warns at startup and those tools return snapshot_disabled with the exact option to set.
• Without a log sink, the log capture sees only what goes through Nest's Logger: with nestjs-pino, the lines written through PinoLogger/@InjectPinoLogger() and the pino-http request lines are not captured. With a sink, only the fields the sink maps are kept (level, message, context, time, stack); the other fields of a record (req, res, bindings) are not.
• The tee is installed during app.init() (in onModuleInit). Lines written before that, including the ones bufferLogs: true holds until useLogger flushes them, and the onModuleInit hooks of modules Nest initialises before the inspector's, are not in the buffer. A useLogger after the app started replaces the tee, and capture stops. A log sink is not affected: it holds what arrives before the inspector connects it.
• With Nest's default logger, every Logger prints through one shared ConsoleLogger; a per-instance new Logger(context, { timestamp: true }) loses its elapsed-time suffix.
• Request tracing needs the app's routes to be built after the module is configured, which is the normal NestFactory.create → listen (or init) bootstrap. Global enhancers added after app.init() are not traced (Nest does not run them on existing routes either). Enhancer instances that are frozen are left unwrapped. Nest's built-in exception handler is not a step: an exception no filter of yours caught shows in the step that threw and in the status.
• Requests that do not go through a Nest middleware (outside the global prefix, or served before Nest's router) are not traced.
• Emissions are recorded from the moment the module is configured (before any onModuleInit); an emitter the app creates on its own, outside EventEmitterModule, is not observed. Listeners added by hand with emitter.on(...) count in listeners but are not in events_listeners, which reads @OnEvent metadata.
• schedule_jobs lists what SchedulerRegistry holds: a decorated job ScheduleModule did not register (a request-scoped provider, a kind switched off in forRoot) is not listed. Periods and pending state of intervals and timeouts are read from Node's timer objects.
• Runs are not recorded for request-scoped listeners (the emitter builds an instance per emission) nor for jobs your app adds to SchedulerRegistry itself, which run its own callbacks. A method that is both a job and a listener records a job run when the scheduler calls it outside an emission.
• With debug, an exception that is not an Error (a thrown string or plain object) has no stack. Frames are as deep as Error.stackTraceLimit lets V8 capture. A stack another library already mapped from JavaScript to JavaScript (a bundle's map applied by a custom Error.prepareStackTrace) is read as compiled code. A compiled file rebuilt while the process runs keeps the map read the first time.
• With debug.locals, a process whose inspector is unavailable (Node built without it) logs a warning and records stacks without locals; app_info.debug.locals says failed and why.
• Clients that only speak stdio cannot connect: there is no stdio bridge in v1.
• app_info reports the Nest version the package resolves and the app name and version from the package.json of the working directory; set serverInfo if the app starts from elsewhere.

Contributing

The package is its own Yarn 4 project (packageManager pins the version; corepack enable once).

yarn install --immutable
yarn format-check && yarn lint && yarn type-check
yarn build && yarn test   # the suite imports dist/index.cjs: build first

The devDependencies run the suite on Nest 11. To run it on Nest 10, install the four Nest packages at once (so the tree holds one major), run the suite, then throw the change away:

yarn add -D @nestjs/common@^10 @nestjs/core@^10 @nestjs/platform-express@^10 @nestjs/testing@^10
yarn build && yarn test
git checkout package.json yarn.lock && yarn install

CI (.github/workflows/ci.yml) runs format, lint, type-check, build and the suite on every push to main and every pull request, on Nest 10 and 11, each on Node 20 and 22. Branch protection on main requires the four ci checks to pass; a maintainer sets it in the repository settings, it is not part of this repo.

Releases are cut by a maintainer, never by the workflow: add a ## x.y.z section at the top of CHANGELOG.md, run npm version patch|minor|major (commit and vx.y.z tag), then git push --follow-tags. The tag starts .github/workflows/release.yml: the full CI matrix, then npm publish --provenance --access public (with the NPM_TOKEN repository secret) and a GitHub release whose notes are that CHANGELOG.md section. A manual run of the workflow, or a tag ending in -test, does all of it with npm publish --dry-run and creates no release.

License

MIT