NestJS MCP Agent API

Prueba de concepto para explorar cómo exponer lógica de un backend desarrollado con NestJS a agentes de IA mediante Model Context Protocol (MCP).

La idea principal es simple: reutilizar la misma lógica de negocio desde una API REST tradicional y desde herramientas MCP, sin duplicar los servicios del backend.

Arquitectura

                         ┌─────────────────┐
                         │   Agente / IA   │
                         └────────┬────────┘
                                  │ MCP
                         ┌────────▼────────┐
                         │   MCP Server    │
                         │     Tools       │
                         └────────┬────────┘
                                  │
                                  │
┌──────────────┐         ┌────────▼────────┐
│ Cliente REST │────────►│ Servicios NestJS│
└──────────────┘         └────────┬────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
                Clientes      Productos     Solicitudes

REST y MCP reutilizan los mismos servicios de NestJS.

Related MCP server: nestjs-langgraph-mcp

Herramientas MCP

El servidor expone tres tools:

• consultar_cliente: obtiene un cliente por ID.

• listar_productos: lista productos y permite filtrar los disponibles.

• crear_solicitud: registra una nueva solicitud.

Las tools no contienen una segunda implementación de la lógica de negocio. MCP actúa como una capa de entrada adicional sobre los servicios existentes.

Stack

• NestJS 12

• TypeScript 6

• Model Context Protocol (MCP)

• Zod

• Jest

• ts-jest

Requisitos

• Node.js 22 o superior.

• npm.

Para utilizar la versión actual de MCP Inspector se recomienda mantener Node.js actualizado dentro de la línea 22 o utilizar una versión superior compatible.

Instalación

npm install

Ejecutar API REST

npm run start:dev

La API queda disponible por defecto en:

http://localhost:3000

Consultar cliente

curl http://localhost:3000/clientes/1

Listar productos

curl http://localhost:3000/productos

También es posible solicitar solamente productos disponibles:

curl "http://localhost:3000/productos?disponibles=true"

Crear solicitud

curl -X POST http://localhost:3000/solicitudes \
  -H "Content-Type: application/json" \
  -d '{"clienteId":1,"productoId":101,"detalle":"Solicitud de prueba desde la API REST"}'

Los DTO y ValidationPipe de NestJS validan los datos antes de ejecutar la lógica de negocio.

Ejecutar servidor MCP

npm run start:mcp

El servidor utiliza transporte stdio, por lo que queda esperando que un cliente MCP inicie la comunicación mediante entrada y salida estándar.

Probar con MCP Inspector

Se puede utilizar el Inspector oficial de MCP:

npx @modelcontextprotocol/inspector@latest

Agregar el servidor manualmente con:

Transport: stdio
Command: npm

Arguments:
run
start:mcp

Working directory:
/ruta/al/nestjs-mcp-agent-api

Al conectarse, el cliente descubre automáticamente:

consultar_cliente
listar_productos
crear_solicitud

Desde Inspector es posible revisar el esquema de entrada de cada tool y ejecutarla sin llamar directamente a los endpoints REST.

Tests

Ejecutar:

npm test

Actualmente se prueban los servicios utilizados por las tres operaciones principales:

✓ consulta un cliente
✓ filtra productos disponibles
✓ crea una solicitud

Build

npm run build

¿Qué demuestra este proyecto?

Normalmente un backend expone su lógica mediante HTTP para aplicaciones frontend u otros servicios.

MCP permite incorporar otro tipo de consumidor:

Aplicación ──REST──┐
                   ├──► Servicios NestJS
Agente IA ──MCP────┘

El agente puede descubrir qué herramientas existen, conocer los parámetros que necesita cada una y ejecutarlas utilizando un contrato definido por MCP.

Para mí, lo interesante no es reemplazar REST, sino poder reutilizar un backend existente y decidir qué capacidades queremos exponer a agentes de IA.

Próximos pasos

El proyecto utiliza datos mock intencionalmente para mantener el foco en la integración NestJS + MCP.

Una evolución natural sería incorporar:

• PostgreSQL.

• autenticación.

• autorización y permisos por tool.

• auditoría de operaciones ejecutadas por agentes.

• rate limiting.

• transporte HTTP para escenarios remotos.

Licencia

MIT