Construye un servidor MCP en Node.js y TypeScript: Un tutorial práctico de HazelJS

El protocolo MCP (Model Context Protocol) se ha convertido en un estándar ligero para conectar asistentes basados en inteligencia artificial con herramientas y datos empresariales. Su diseño minimalista sobre JSON-RPC 2.0 permite que un mismo servidor sea consumido por Cursor, Claude Desktop o cualquier cliente compatible, sin necesidad de adaptadores propietarios. En este tutorial exploramos cómo construir un servidor MCP en Node.js y TypeScript utilizando HazelJS, una biblioteca que abstrae la complejidad del protocolo y permite exponer clases existentes como herramientas para agentes IA.

HazelJS ofrece un enfoque basado en decoradores para definir herramientas. Con el decorador @Tool se especifica el nombre, la descripción y los parámetros de cada función, y el framework se encarga de convertirlos en el esquema JSON que el protocolo requiere. Esto elimina la necesidad de escribir el enrutamiento de mensajes, el manejo de errores JSON-RPC o la serialización de esquemas manualmente. El resultado es un servidor que se comunica por stdio o HTTP/SSE y que cualquier cliente MCP puede descubrir e invocar al instante.

Para ponerlo en práctica, imaginemos un tablero de tareas sencillo con operaciones como listar, crear y completar tareas. Cada método anotado con @Tool se convierte en una herramienta que el modelo de lenguaje puede llamar. El servidor se monta en pocas líneas: se crea un registro de herramientas, se registran las instancias de los agentes y se invoca el método listenStdio. Este patrón es escalable: un mismo registro puede albergar múltiples agentes, cada uno con su dominio (soporte, facturación, administración), y el servidor expone todas las herramientas de forma unificada.

La ventaja real de este enfoque es la portabilidad. Un equipo que ya desarrolla aplicaciones a medida en TypeScript puede adaptar sus clases de negocio existentes para que sean consumidas por asistentes de IA sin reescribir la lógica. HazelJS reutiliza el mismo decorador @Tool que se emplea en los agentes internos, de modo que una herramienta diseñada para un chatbot corporativo funciona automáticamente como herramienta MCP. Esto reduce la duplicación de código y acelera la integración de ia para empresas en flujos de trabajo cotidianos.

Para llevar este prototipo a producción, es necesario sustituir el almacenamiento en memoria por una base de datos persistente. Puede usarse Prisma, Redis o incluso un cliente HTTP que llame a APIs existentes. La interfaz de las herramientas no cambia; solo se modifica la implementación interna. También conviene adoptar validación de esquemas con Zod para asegurar que los argumentos recibidos del modelo siguen la estructura esperada. HazelJS soporta pasar un esquema Zod directamente en el decorador, lo que genera tanto la validación en tiempo de ejecución como el esquema JSON que el cliente MCP necesita.

La seguridad es otro aspecto crítico. Aunque el servidor MCP se ejecuta como un proceso hijo de un cliente de confianza, los inputs del modelo pueden estar contaminados por inyección de prompt. Por eso es recomendable tratar todas las entradas como no confiables, aplicar escapes adecuados y evitar operaciones destructivas sin aprobación humana. En entornos donde se manejan datos sensibles, las prácticas de ciberseguridad deben incluir la redacción de logs y la limitación de herramientas que exponen información crítica.

La observabilidad se integra de forma natural porque cada llamada a herramienta genera un evento que puede ser monitorizado. Se pueden añadir métricas como contadores de invocaciones y duración, y enviar trazas a sistemas de telemetría. Esto es especialmente útil cuando el servidor MCP es parte de una arquitectura más amplia que incluye servicios cloud aws y azure, donde la trazabilidad entre componentes es fundamental para mantener la fiabilidad.

Desde la perspectiva de negocio, un servidor MCP bien diseñado permite que los equipos de producto expongan funcionalidades internas a asistentes de IA sin desarrollar interfaces adicionales. Un analista puede preguntar por el estado de un proyecto en lenguaje natural y el modelo invoca la herramienta correspondiente. Esta capacidad encaja con los servicios inteligencia de negocio que facilitan la toma de decisiones basada en datos, y puede complementarse con paneles en Power BI que se actualicen a partir de las mismas fuentes.

La evolución natural de este tipo de servidores es la creación de múltiples procesos especializados, cada uno con su propia superficie de herramientas y su propio ámbito de responsabilidad. Así se consigue un aislamiento de fallos y una gestión de permisos más granular. Empresas como Q2BSTUDIO ofrecen consultoría para implementar este tipo de arquitecturas, ayudando a transformar lógica de negocio en capacidades accesibles para agentes IA. El resultado es un ecosistema donde el software a medida se vuelve más inteligente y adaptable, sin perder el control sobre la seguridad y la gobernanza de los datos.