Integrating NestJS with xmcp

Learn how to turn your existing NestJS app into an MCP server with xmcp. Instead of standing up a separate service, xmcp drops into your project as a regular Nest module: your tools live in src/tools/, they're discovered automatically, and they're served through Nest's own controllers, dependency injection, and lifecycle hooks.

What You'll Build

By the end of this guide, you'll have:

• An /mcp endpoint served by a NestJS module
• Tools auto-discovered from your src/tools/ directory
• Tools that read from your existing Nest providers and services
• Optional JWT authentication using a reusable guard

Install xmcp

xmcp works on top of your existing NestJS project. From your project directory, run:

npx init-xmcp@latest

The framework (@nestjs/core) and package manager are detected automatically. The only thing you're prompted for is which of tools, prompts, and resources to scaffold.

? Which components do you want to initialize? (tools, prompts, resources)

That single command does the whole setup for you. After it finishes, init has:

• Generated xmcp.config.ts with the NestJS adapter and your selected paths.
• Generated a src/xmcp/ folder with the module, controller, exception filter, and an auth guard stub.
• Scaffolded a sample tool in src/tools/ (plus prompts/resources if you picked them).
• Wired package.json so build runs xmcp build before your Nest build.
• Updated tsconfig.json with the @xmcp/* path alias and xmcp-env.d.ts.
• Updated .gitignore to ignore the generated .xmcp folder.
• Installed xmcp and zod with your package manager.

The generated src/xmcp/ folder holds the module files you'll customize:

src/xmcp/
├── xmcp.filter.ts      # Exception filter for JSON-RPC errors
├── xmcp.controller.ts  # Controller with configurable route
├── xmcp.module.ts      # NestJS module configuration
└── xmcp.auth.ts        # Auth guard stub (createMcpAuthGuard)

Adjust the Dev Script

Init already wired your build script to run xmcp build && nest build, added the @xmcp/* path alias and xmcp-env.d.ts to your tsconfig.json, and ignored the generated .xmcp folder in .gitignore. There's one script worth adjusting by hand.

NestJS apps watch with start:dev, so init can't know to combine it with xmcp. It writes a standalone dev: "xmcp dev". Update it to run both watchers together:

{
  "scripts": {
    "dev": "xmcp dev & nest start --watch"
  }
}

The Generated Config

Because init detected @nestjs/core, it already generated an xmcp.config.ts set up for the NestJS adapter. You don't write this by hand:

import { type XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  http: true,
  experimental: {
    adapter: "nestjs",
  },
  paths: {
    tools: "src/tools",
    prompts: false,
    resources: false,
  },
};

export default config;

The paths reflect the components you selected during init (false for the ones you skipped). The NestJS adapter uses HTTP transport and integrates with Nest's module system, so you can inject XmcpService into your own controllers if you ever need to. Edit this file only if you want to change the adapter or move your tool directories.

Register the Module

This is the one integration step init leaves to you, it prints these exact instructions when it finishes. This is deliberate: init won't edit your app.module.ts to auto-register XmcpModule, because mounting the service into your application graph without your say-so could introduce a breaking change to a project that's already running. You decide when the MCP endpoint goes live. Import XmcpModule into your application module:

import { Module } from "@nestjs/common";
import { XmcpModule } from "./xmcp/xmcp.module";

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

That's it for wiring. This registers a /mcp endpoint that handles MCP requests via POST.

A Tour of the Generated Files

The files in src/xmcp/ are yours to customize. Here's what each one does.

Controller

The controller extends XmcpController and uses standard Nest decorators:

import { Controller, UseFilters } from "@nestjs/common";
import { XmcpController } from "@xmcp/adapter";
import { McpExceptionFilter } from "./xmcp.filter";

@Controller("mcp")
@UseFilters(McpExceptionFilter)
export class McpController extends XmcpController {}

Want a different route? Just change the @Controller argument:

@Controller("api/v1/mcp") // Now accessible at /api/v1/mcp
export class McpController extends XmcpController {}

Module

The module registers the controller and providers, and wires up OAuth resource metadata and the auth guard out of the box:

import { Module } from "@nestjs/common";
import { XmcpService, OAuthModule } from "@xmcp/adapter";
import { McpController } from "./xmcp.controller";
import { McpExceptionFilter } from "./xmcp.filter";
import { McpAuthGuard } from "./xmcp.auth";

const config = {
  authorizationServers: [process.env.OAUTH_ISSUER!],
};

@Module({
  imports: [OAuthModule.forRoot(config)],
  controllers: [McpController],
  providers: [XmcpService, McpExceptionFilter, McpAuthGuard],
  exports: [XmcpService],
})
export class XmcpModule {}

OAUTH_ISSUER is only read when a client requests the OAuth resource metadata endpoint, so the module boots and serves tools even if you haven't set it yet. Wire it up when you're ready to advertise an authorization server.

Exception Filter

The filter handles MCP errors in JSON-RPC format. Customize it to handle specific error types or change the response shape:

import { ExceptionFilter, Catch, ArgumentsHost, Logger } from "@nestjs/common";
import { Response } from "express";

@Catch()
export class McpExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(McpExceptionFilter.name);

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    this.logger.error(
      "MCP request failed",
      exception instanceof Error ? exception.stack : String(exception)
    );

    if (!response.headersSent) {
      response.status(500).json({
        jsonrpc: "2.0",
        error: {
          code: -32603,
          message: "Internal server error",
        },
        id: null,
      });
    }
  }
}

Auth Guard

Init also generates an xmcp.auth.ts stub built around the createMcpAuthGuard factory. It's already imported by the module, so all you do is fill in verifyToken when you want authentication:

import { createMcpAuthGuard } from "@xmcp/adapter";

/**
 * MCP Auth Guard configuration.
 *
 * To enable authentication:
 * 1. Add McpAuthGuard to providers in xmcp.module.ts
 * 2. Add @UseGuards(McpAuthGuard) to xmcp.controller.ts
 */
export const McpAuthGuard = createMcpAuthGuard({
  verifyToken: async (token) => {
    // TODO: Implement your token verification logic
    throw new Error("Token verification not implemented");
  },
  required: false, // Set to true to require authentication
});

With required: false, the guard lets unauthenticated requests through and never calls verifyToken, so the default scaffold runs without any auth wiring. The Authentication section below shows how to fill it in.

Add a Tool

Tools are discovered automatically from your src/tools/ directory. Create a file, export a schema, metadata, and a default handler:

import { z } from "zod";
import { type InferSchema } from "xmcp";

export const schema = {
  name: z.string().describe("The name of the user to greet"),
};

export const metadata = {
  name: "greet",
  description: "Greet the user by name",
};

export default async function greet({ name }: InferSchema<typeof schema>) {
  return `Hello, ${name}!`;
}

When you run xmcp dev or xmcp build, xmcp registers this as an MCP tool. No extra configuration, no manual registration.

The more interesting part is that tools can read from the rest of your application. A tool is just a function, so it can call into your existing stores and services:

import { type ToolMetadata } from "xmcp";
import { getUsersStore } from "../users/users.store";

export const schema = {};

export const metadata: ToolMetadata = {
  name: "list-users",
  description: "List all users in the system",
};

export default async function listUsers() {
  const usersStore = getUsersStore();
  const users = usersStore.findAll();

  if (users.length === 0) {
    return "No users found in the system.";
  }

  const userList = users
    .map(
      (user, index) =>
        `${index + 1}. ${user.name} (${user.email}) - ID: ${user.id}`
    )
    .join("\n");

  return `Found ${users.length} user(s):\n\n${userList}`;
}

This is the payoff of running inside your Nest app: the same data that backs your REST API now backs your MCP tools.

Authentication

The guard from createMcpAuthGuard is already generated in xmcp.auth.ts and already registered in your module's providers. Two things are left to you: implement verifyToken, and apply the guard to the controller.

The generated stub throws from verifyToken. Fill it in with your verification logic — here's a JWT example. Start by installing the JWT library:

npm install jsonwebtoken
npm install -D @types/jsonwebtoken

Then replace the stub's verifyToken:

import { createMcpAuthGuard } from "@xmcp/adapter";
import * as jwt from "jsonwebtoken";

export const McpAuthGuard = createMcpAuthGuard({
  verifyToken: async (token) => {
    const decoded = jwt.verify(
      token,
      process.env.JWT_SECRET!
    ) as jwt.JwtPayload;

    return {
      clientId: decoded.sub || "unknown",
      scopes: decoded.scope?.split(" ") || [],
      expiresAt: decoded.exp,
    };
  },
  required: true, // Reject requests without a valid token
});

The adapter handles token extraction, error responses, and attaching auth info to the request. The guard is registered in the module already, so the only wiring left is applying it to the controller with @UseGuards:

import { Controller, UseFilters, UseGuards } from "@nestjs/common";
import { XmcpController } from "@xmcp/adapter";
import { McpExceptionFilter } from "./xmcp.filter";
import { McpAuthGuard } from "./xmcp.auth";

@Controller("mcp")
@UseFilters(McpExceptionFilter)
@UseGuards(McpAuthGuard)
export class McpController extends XmcpController {}

Inside a tool, the auth info is available through the extra argument:

import { type ToolMetadata, type ToolExtraArguments } from "xmcp";

export const schema = {};

export const metadata: ToolMetadata = {
  name: "whoami",
  description: "Returns information about the authenticated user",
};

export default async function whoami(
  _args: unknown,
  extra: ToolExtraArguments
) {
  const authInfo = extra.authInfo;

  if (!authInfo) {
    return "Not authenticated";
  }

  return JSON.stringify(
    {
      clientId: authInfo.clientId,
      scopes: authInfo.scopes,
    },
    null,
    2
  );
}

For the full list of guard options, see the NestJS adapter docs.

Lifecycle and Logging

Because the adapter runs as a real Nest service, it plays by Nest's rules. XmcpService implements OnModuleInit and OnModuleDestroy, so it initializes and shuts down with the rest of your application, and every internal log goes through Nest's Logger. That means MCP traffic shows up in the same logs, with the same formatting, as the rest of your app, no separate logging setup required.

Test It

With the server running, send a request to the /mcp endpoint:

# Without authentication (if required: false)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# With authentication
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Conclusion

Now your NestJS app has an MCP server. Tools are auto-discovered, served through a module you fully control, and able to reuse the services and data you already have.

For the full reference, check the NestJS adapter docs.