NestJS MCP: cómo integrar el módulo oficial en tu backend

Volver

Kevin Riedl

20 min de lectura · 4 nov 2026
Última revisión 4 de noviembre de 2026

Siguiente

Tu backend de NestJS ya determina quién puede consultar una factura y qué operaciones pueden modificarla. Un asistente de IA necesita acceder a ese comportamiento sin crear una segunda versión de las reglas de tu aplicación.

Para integrar el módulo oficial NestJS MCP en una aplicación existente, comprueba la compatibilidad, registra McpModule y expón los métodos de proveedores que hayas seleccionado. Mantén los permisos sobre cada objeto y las operaciones de negocio en los servicios. Valida esquemas, guards y resultados mediante un cliente MCP; después, prueba el endpoint HTTP antes de conectar un asistente remoto.

Revisado y probado el 4 de noviembre de 2026. Compilamos un ejemplo para consultar el estado de facturas con @nestjs/mcp 0.0.2 y ejecutamos diez comprobaciones de comportamiento, dos de ellas por HTTP real. El proyecto descargable utiliza datos ficticios y tokens de prueba.

¿Qué aporta el módulo oficial NestJS MCP?

El módulo oficial NestJS MCP expone métodos concretos de proveedores como herramientas, recursos y prompts. Se encarga del protocolo y conecta esos métodos con la inyección de dependencias y los mecanismos de ejecución de Nest. Tú eliges qué expones; los demás métodos de tus servicios quedan fuera de la interfaz MCP.

El README de esta versión documenta Streamable HTTP sobre Express, Fastify y el adaptador de Node, además de stdio para conexiones con procesos locales. @nestjs/mcp es la integración oficial; @rekog/mcp-nest es otro paquete, mantenido por la comunidad. NestJS Observe también ofrece un servidor MCP para sus datos de observabilidad.

Un asistente de soporte puede invocar el mismo servicio de facturas que utiliza tu panel. Así, las reglas de las transacciones y las comprobaciones de acceso por tenant permanecen en un único lugar. Empezaríamos por una operación de lectura. Revisa qué registros puede consultar quien realiza la llamada, qué campos salen de la aplicación y qué recibe el asistente cuando falla una petición.

¿Es compatible esta versión con tu aplicación NestJS?

@nestjs/mcp 0.0.2 declara dependencias peer de NestJS 12 y MCP SDK ^2.4.0. NestJS 10 y 11 quedan fuera de ese contrato. Revisa primero tu árbol de dependencias; actualizar el framework merece un cambio independiente y sus propias pruebas de regresión.

El manifiesto del paquete 0.0.2 especifica los rangos de dependencias de la tabla. Nuestro proyecto de prueba verifica una combinación de versiones fijadas dentro de esos rangos.

npm ls @nestjs/core @nestjs/common @modelcontextprotocol/server zod

npm install --save-exact @nestjs/[email protected] \
  @modelcontextprotocol/[email protected] [email protected]

npm install --save-dev --save-exact @modelcontextprotocol/[email protected]

Nuestro ejemplo combina estas versiones con NestJS 12.3.3 y Node.js 24.22.1. Una dependencia ESM no tiene por qué obligarte a reescribir una aplicación CommonJS; comprueba cómo la importas y compilas. Forzar la instalación con un override de dependencias peer no demuestra compatibilidad.

El código de preparación de esquemas también merece revisión durante la actualización. Zod 3 se rechaza. ArkType es compatible; Valibot necesita toStandardJsonSchema() de @valibot/to-json-schema. Si ya tienes documentos JSON Schema, puedes utilizar fromJsonSchema() del paquete de servidor MCP. Los argumentos de las herramientas requieren un esquema de objeto convertible.

¿Cómo integrar NestJS MCP en tu backend existente?

Para integrar NestJS MCP en tu backend, registra McpModule y un proveedor de herramientas que reciba por inyección el servicio de aplicación que necesita. Limita el descubrimiento a ese módulo funcional. Si el endpoint HTTP debe estar protegido, configura un verificador real de tokens antes de exponer herramientas sensibles.

Esta configuración muestra cómo conectar las piezas: debes aportar tus propios InvoicesModule, IdentityModule e IdentityTokenVerifier.

McpModule.forRoot({
  name: 'billing-assistant',
  version: '1.0.0',
  include: [InvoicesModule],
  imports: [IdentityModule],
  auth: {
    verifier: IdentityTokenVerifier,
    resource: 'https://api.example.com/mcp',
    authorizationServers: ['https://login.example.com'],
  },
})

Importa también InvoicesModule en la aplicación e incluye InvoiceTools en sus providers. La opción imports del módulo pone las dependencias exportadas a disposición del verificador. El registro de proveedores descubre los métodos decorados al arrancar; include determina qué módulos examina.

Este fragmento del proveedor procede de nuestro ejemplo ejecutado. La descarga incluye su servicio, el componente auxiliar de acceso, el guard y el módulo de pruebas.

export const InvoiceInput = z.object({
  invoiceId: z.string().regex(/^inv_[a-z0-9]+$/).max(64),
}).strict();

export const InvoiceStatus = z.object({
  invoiceId: z.string(),
  status: z.enum(['open', 'paid']),
});

@Injectable()
export class InvoiceTools {
  constructor(
    private readonly invoices: InvoicesService,
    private readonly access: InvoiceAccess,
  ) {}

  @Tool({
    name: 'get-invoice-status',
    description: 'Read the status of one invoice available to the signed-in user. Does not modify an invoice.',
    inputSchema: InvoiceInput,
    outputSchema: InvoiceStatus,
    scopes: ['invoices:read'],
    annotations: { readOnlyHint: true },
  })
  @UseGuards(SupportTeamGuard)
  async status(input: z.infer<typeof InvoiceInput>, ctx: McpContext) {
    const actor = this.access.requirePrincipal(ctx);
    return this.invoices.statusForActor(actor, input.invoiceId, ctx.signal);
  }
}

InvoiceAccess obtiene la identidad del usuario y el tenant del contexto verificado; InvoicesService comprueba el acceso a la factura. El modelo aporta un identificador de factura. Añadir un campo de tenant no concede permisos, y el esquema estricto rechaza campos no declarados.

El ejemplo devuelve únicamente un identificador y un estado. Una entidad de factura del ORM podría exponer también direcciones, información fiscal o notas internas. Define expresamente qué datos puede recibir el asistente.

Si no encuentras el endpoint, revisa el prefijo global y el versionado. Si una herramienta no aparece en el descubrimiento, comprueba el registro de proveedores, include y los errores de arranque. Un decorador no permite descubrir una clase que nunca registraste.

¿Qué métodos conviene exponer como herramientas, recursos o prompts?

En NestJS MCP, utiliza herramientas para operaciones con parámetros, recursos para datos identificados por URI y prompts para plantillas de mensajes reutilizables. Asigna una finalidad clara a cada primitiva. Quien revise la integración podrá evaluar conjuntamente sus permisos y su comportamiento ante fallos.

La guía oficial de primitivas especifica los decoradores y sus resultados. Para una aplicación de soporte sobre facturas, distribuiríamos las capacidades así:

Una herramienta genérica como run-sql o call-any-service resulta más difícil de revisar. Preferimos una capacidad de negocio concreta, con entradas acotadas: permite identificar mejor los registros y los efectos autorizados.

¿Funcionan tus guards actuales en las llamadas MCP?

Tus guards pueden ejecutarse en las llamadas de NestJS MCP si contemplan el contexto de ejecución mcp. Revisa también esa suposición en interceptores, pipes y filtros de excepciones. Un acceso al contexto pensado solo para HTTP puede leer argumentos equivocados aunque el guard esté bien registrado.

El componente de acceso al contexto MCP expone la entrada, el contexto de la llamada y la información de autenticación. El guard específico de nuestra herramienta lee una declaración de departamento que aporta el verificador de prueba:

@Injectable()
export class SupportTeamGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const ctx = McpExecutionContext.create(context).getContext();
    return ctx.authInfo?.extra?.department === 'support';
  }
}

Aplica este guard al proveedor o al método MCP. Si utilizas un guard global compartido con rutas HTTP, distingue los tipos de contexto y aplica la política correspondiente en cada caso. Devolver true ante un contexto desconocido permitiría eludir esa política.

Mantén el estado del usuario y del tenant en los argumentos o en el contexto de la llamada. Otra petición puede sobrescribir this.currentTenant en un proveedor compartido. El registro rechaza árboles de dependencias con ámbito de petición; si tu proveedor inyecta un servicio de tenant con ese ámbito, tendrás que replantear el diseño.

En 0.0.2, McpContext es una unión de contextos de cliente y de agente interno. Comprueba ctx.transport antes de usar campos exclusivos del cliente, como server o era. El idempotencyKey opcional del agente interno no elimina automáticamente las escrituras MCP remotas duplicadas.

Los interceptores deberían registrar la operación, el resultado, el identificador de correlación y el tiempo transcurrido, sin guardar tokens bearer ni el contenido completo de las facturas. Revisa también los mensajes de excepción: una HttpException lanzada deliberadamente puede mostrar su mensaje a quien llama. Ese mensaje debe ayudar al cliente a recuperarse sin revelar registros internos ni credenciales.

¿Cómo se combinan los scopes de OAuth y las políticas de usuario?

En NestJS MCP, un scope de OAuth permite utilizar una capacidad; la política de la aplicación decide a qué objetos puede acceder quien la invoca. El módulo HTTP verifica los tokens de tu proveedor de identidad. Tener un token válido con permiso de lectura de facturas no basta para leer cualquier factura.

El control de autorización conecta tu verificador con las respuestas de desafío OAuth. Valida el emisor, la firma o el resultado de introspección, la audiencia y la caducidad. Decodificar un JWT y devolver la URL de recurso configurada no demuestra que el token se emitiera para ese recurso.

Nuestro servicio comprueba el acceso del actor a la factura después de que el scope invoices:read autorice la capacidad. authInfo.clientId identifica al cliente OAuth; obtén por separado la identidad del usuario y su tenant. Nuestra arquitectura de autorización MCP para empresas desarrolla ese diseño general.

La integración con @CurrentUser() y @Can() necesita @nestjs/authentication 0.1.3+ y @nestjs/authorization 0.1.1+, ambos configurados. Las pruebas de integración del proyecto oficial muestran cómo intervienen los dos módulos en la inyección de usuarios y las políticas de las llamadas a herramientas.

La configuración documentada decorators: [Public()] exime a la ruta del endpoint del guard de autenticación para que MCP devuelva su propio desafío de descubrimiento OAuth. Debe acompañarse de auth en MCP y de la autorización prevista para los proveedores. Aplicar @Public() de forma general a los proveedores de herramientas no equivale a esa configuración.

En un endpoint HTTP, declarar scopes de herramientas sin una configuración de autenticación que los haga cumplir provoca un rechazo al arrancar. Stdio tiene un modelo de seguridad diferente: un scope OAuth en un decorador no protege por sí solo una llamada local por stdio.

¿Qué cambia entre HTTP, stdio y los clientes anteriores?

NestJS MCP atiende a clientes remotos mediante Streamable HTTP y a procesos locales mediante stdio. Las peticiones HTTP son independientes; stdio mantiene una conexión con el proceso. Contrasta las interacciones que necesita tu cliente con el transporte y la generación del protocolo, sobre todo cuando una herramienta solicita información al usuario.

La documentación de transportes permite comprobar estas opciones:

HTTP sin estado elimina la necesidad de mantener afinidad de sesión para el transporte del módulo. Tu base de datos, las colas de trabajo, los límites de uso y la idempotencia de negocio siguen necesitando la consistencia adecuada para sus operaciones. Nuestra guía de migración a servidores MCP sin estado trata la transición del protocolo en general.

Si hay clientes en el navegador, distingue la opción allowedOrigins del módulo, que utiliza nombres de host, de los orígenes CORS de Nest. Una petición sin cabecera Origin puede superar esa comprobación de origen, por lo que esta no sustituye a la autenticación. Además, el analizador del cuerpo HTTP puede rechazar la petición antes de que intervenga el límite de tamaño del módulo.

En stdio, dirige los logs de la aplicación a McpStdioLogger; stdout transporta los mensajes del protocolo. Una conexión local satisfactoria no verifica el descubrimiento OAuth, TLS ni el comportamiento del proxy de tu despliegue remoto.

¿Qué debes cambiar al migrar desde mcp-nest?

Para migrar desde @rekog/mcp-nest, identifica cómo se corresponden las API de tu versión comunitaria con las de proveedores, esquemas y contexto del módulo oficial. Enumera las funciones que utilizas antes de sustituir dependencias. Dos decoradores con nombres parecidos pueden tener comportamientos distintos de autorización o transporte.

Contrasta estos cambios con la guía oficial de migración para las API 1.x y 2.x del paquete comunitario.

El antiguo transporte HTTP+SSE de 2024 y la coexistencia de varios servidores MCP en una aplicación también quedan fuera del diseño compatible con esta versión. Si habilitas autenticación HTTP, no se mantienen las excepciones de acceso anónimo por herramienta que ofrecía el módulo comunitario.

Migra primero una herramienta de lectura y conserva su nombre y contrato cuando sea posible. Compara el descubrimiento, los resultados y los rechazos con la integración anterior antes de abordar escrituras y llamadas repetidas.

¿Cómo probar el comportamiento MCP que recibe tu asistente?

Utiliza connectMcpClient() para probar el comportamiento de NestJS MCP y después ejercita la ruta HTTP para comprobar el middleware y el despliegue. Probar directamente los proveedores no recorre el flujo del protocolo: deja fuera la validación de argumentos, los scopes, los guards y la serialización de resultados.

El cliente auxiliar en memoria llama al servicio HTTP sin abrir un socket, incluidas sus comprobaciones de Host y Origin. Omite el middleware del endpoint y los guards de ruta suministrados mediante decorators. Utiliza un objeto de petición simplificado con la URL http://localhost/mcp.

Este fragmento comprueba que una entrada mal formada nunca llega al servicio de facturas. El proyecto de prueba proporciona el módulo de pruebas y el cliente autenticado, y cierra ambos al terminar.

const service = moduleRef.get(InvoicesService);
const before = service.calls;

const result = await client.callTool({
  name: 'get-invoice-status',
  arguments: { invoiceId: 123 },
});

assert.equal(result.isError, true);
assert.equal(service.calls, before);

La guía de pruebas distingue los errores de herramienta de los fallos de autenticación: los argumentos mal formados pueden devolver isError: true, la falta de scopes genera InsufficientScopeError y la ausencia de un token obligatorio impide conectar. Si esperas que todos los fallos rechacen una promesa, pasarás por alto los errores devueltos dentro del resultado de la herramienta.

Si tu entorno de producción configura allowedHosts, permite la URL localhost del cliente auxiliar mediante una configuración exclusiva de pruebas. Mantén intacta la política de hosts de producción.

¿Qué verificó nuestro ejemplo de integración?

Nuestro ejemplo de NestJS MCP superó ocho comprobaciones en memoria y dos por HTTP real con Express. Utiliza una factura ficticia, un doble de servicio que comprueba el tenant y tokens de prueba fijos. Los resultados muestran cómo responde este ejemplo a llamadas autorizadas y rechazadas bajo esas condiciones.

Las versiones probadas son @nestjs/mcp 0.0.2, NestJS 12.3.3, cliente y servidor MCP 2.4.0, Zod 4.6.7, TypeScript 7.0.2 y Node.js 24.22.1. El código fuente, el archivo de bloqueo de dependencias y la salida registrada están incluidos en el proyecto descargable de pruebas de integración con NestJS MCP.

Para reproducir el ejemplo, extrae el archivo y ejecuta estos comandos desde su directorio:

npm ci
npm test

Node informa de 12 pruebas superadas porque cuenta dos pruebas principales además de las diez comprobaciones. El verificador simulado debe permanecer exclusivamente en el código de pruebas. Este ejemplo no probó Fastify, el adaptador de Node, proveedores de identidad de producción, escrituras concurrentes ni el comportamiento de balanceadores de carga.

¿Qué debes resolver antes de exponer herramientas de escritura?

Antes de exponer una herramienta de escritura de NestJS MCP, define su autorización, un identificador persistente de operación, la regla de concurrencia y el comportamiento de recuperación. El servicio de aplicación debe decidir qué ocurre cuando una llamada se repite tras agotar el tiempo de espera. Un decorador no puede decidir si corresponde repetir un pago.

Para corregir una factura, registra la acción aprobada y sus datos, vuelve a comprobar el acceso al ejecutarla y conserva el identificador de operación en los reintentos. Rechaza argumentos distintos bajo el mismo identificador. Si el primer intento confirmó la transacción pero se perdió la respuesta, devuelve el resultado registrado o comprueba el estado para recuperarlo.

Este es un diseño propuesto, independiente de nuestro ejemplo ejecutado de solo lectura. Necesita pruebas de transacciones y concurrencia sobre tu almacenamiento real. Un modelo que inventa una nueva clave de idempotencia en cada intento anula la utilidad de una comprobación de duplicados basada en esa clave.

Los responsables de MCP describen las anotaciones de herramientas como indicaciones orientativas. readOnlyHint e idempotentHint informan al cliente del comportamiento previsto, pero no lo hacen cumplir. Del mismo modo, redactar un prompt para pedir confirmación no concede permiso de ejecución.

Antes del primer despliegue con escrituras, exigiríamos estos resultados observables:

• Se rechaza un actor u objeto no autorizado antes de cualquier cambio persistente.
• Dos intentos concurrentes de ejecutar la misma acción aprobada producen un único efecto de negocio, el previsto.
• Se rechazan datos modificados bajo el mismo identificador de operación.
• Se puede recuperar el resultado de una operación cuyo tiempo de espera venció después de confirmar la transacción, sin repetir ciegamente su efecto.
• Un registro de auditoría identifica al actor, la operación, el resultado de autorización y el estado resultante, sin conservar tokens.

Aplica la misma autorización de datos tanto si la operación llega por REST como por un trabajo en cola o MCP. Nuestra guía para controlar el acceso de los agentes a los datos desarrolla ese límite de seguridad.

¿Cuándo utilizaríamos el módulo oficial NestJS MCP?

Utilizaríamos el módulo oficial NestJS MCP cuando la aplicación cumpla su contrato de dependencias y ya aplique los permisos de negocio en los servicios. Empieza con un proveedor adaptador cuyos permisos, salidas y errores puedas revisar, y compruébalos mediante el protocolo del cliente.

Si tu producto utiliza NestJS 10 u 11, decide primero cómo actualizar el framework antes de comprometerte a instalar MCP. Si el sistema depende de proveedores con ámbito de petición, del registro de herramientas en ejecución o de varios servidores MCP aislados dentro de un proceso, resuelve esa incompatibilidad antes de reemplazar una integración que funciona.

El trabajo de desarrollo con NestJS de Wavect cubre los cambios necesarios en la aplicación. Nuestro servicio de desarrollo de servidores MCP puede ayudarte a definir las herramientas que expones, conectar la autorización y establecer criterios de aceptación. El caso de estudio de PromptID presenta trabajo relacionado en aplicaciones de IA.

Utiliza la lista de comprobación de QA antes del lanzamiento para situar las pruebas de herramientas dentro de la decisión general de publicación. Empieza con una lectura cuyos permisos y resultados puedas explicar, demuestra cómo rechaza los accesos indebidos y amplía la interfaz una operación de negocio cada vez.