NestJS MCP Agent API

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

La intención fue mantener el proyecto pequeño: la misma lógica de negocio puede ser consumida desde una API REST tradicional o desde un cliente/agente compatible con MCP.

Arquitectura

                 ┌─────────────────┐
                 │   Agente / IA   │
                 └────────┬────────┘
                          │ MCP
                 ┌────────▼────────┐
                 │   MCP Server    │
                 │ 3 herramientas │
                 └────────┬────────┘
                          │
        ┌─────────────────▼─────────────────┐
        │          Servicios NestJS         │
        ├────────────┬────────────┬─────────┤
        │ Clientes   │ Productos  │Solicitudes│
        └─────┬──────┴─────┬──────┴────┬────┘
              │            │           │
          REST API       datos mock  lógica demo

Related MCP server: nestjs-langgraph-mcp

Herramientas MCP

• consultar_cliente: busca un cliente por ID.

• listar_productos: lista productos y puede filtrar los disponibles.

• crear_solicitud: registra una solicitud simple.

El punto importante es que las tools no duplican la lógica de negocio. MCP llama a los mismos servicios que utilizan los controllers REST.

Requisitos

• Node.js 20 o superior.

• npm.

Instalación

npm install

Ejecutar API REST

npm run start:dev

Ejemplos:

curl http://localhost:3000/clientes/1
curl "http://localhost:3000/productos?disponibles=true"
curl -X POST http://localhost:3000/solicitudes \
  -H "Content-Type: application/json" \
  -d '{"clienteId":1,"productoId":101,"detalle":"Quiero información del plan"}'

Ejecutar servidor MCP

npm run start:mcp

El servidor usa transporte stdio, pensado para que un host MCP lo levante como proceso local.

Ejemplo conceptual de configuración de un cliente MCP:

{
  "mcpServers": {
    "nestjs-demo": {
      "command": "npm",
      "args": ["run", "start:mcp"],
      "cwd": "/ruta/al/nestjs-mcp-agent-api"
    }
  }
}

La ubicación exacta de esta configuración depende del cliente MCP utilizado.

Probar

npm test
npm run build

¿Por qué este proyecto?

Normalmente una API se diseña pensando en un frontend u otros servicios. MCP permite agregar otro consumidor: un agente de IA capaz de descubrir y ejecutar herramientas con contratos definidos.

Para mí, lo interesante no es reemplazar REST, sino reutilizar un backend existente y controlar qué operaciones se exponen a un agente.

Próximos pasos

Este repositorio es intencionalmente simple. Una evolución natural sería agregar autenticación, permisos por tool, PostgreSQL, auditoría y un transporte HTTP para escenarios remotos.

Tecnologías

NestJS · TypeScript · MCP · Zod · Jest

Licencia

MIT