Hilo MCP

Servidor MCP para integrarse con Hilo, la plataforma de mensajería por WhatsApp de Cenzontle.

Su objetivo es acompañar a tu agente mientras construye la integración: le da el contrato real de la API, herramientas para verificar su propio trabajo y un plan a seguir. Le dices «créame la integración con Hilo» y se pone a construirlo.

Opera en sandbox por defecto. Con una key de pruebas (hilo_sbx_…) los envíos no se cobran y solo llegan al número autorizado. Para operar en producción hace falta un opt-in explícito — ver Producción.

Instalar en un comando

Claude Code:

claude mcp add hilo -e HILO_API_KEY=hilo_sbx_TU_KEY -- npx -y @cenzontle/hilo-mcp

Después reinicia Claude Code (los servidores MCP se cargan al arrancar) y pide:

Créame la integración con Hilo.

¿Aún no tienes la key? Instálalo igual, sin -e: el servidor arranca de todos modos, el agente puede leer el contrato de la API e ir escribiendo el código, y hilo_diagnose te dirá exactamente qué pedirle al operador de Hilo.

Requisitos

• Node 20 o superior.
• Una API key de sandbox (hilo_sbx_…). No hay registro en autoservicio: el operador de Hilo crea la cuenta y la entrega.

El servidor arranca sin key: el agente puede leer el contrato y avanzar en el código mientras la consigues, y te dirá exactamente qué pedir.

Instalación manual

Si prefieres versionar la configuración con tu proyecto en vez de usar el comando de arriba. No necesitas instalar nada: npx descarga el paquete al vuelo.

Claude Code (.mcp.json del proyecto, o ~/.claude.json):

{
  "mcpServers": {
    "hilo": {
      "command": "npx",
      "args": ["-y", "@cenzontle/hilo-mcp"],
      "env": { "HILO_API_KEY": "hilo_sbx_tu_key_aqui" }
    }
  }
}

Claude Desktop (claude_desktop_config.json): mismo bloque.

Reinicia el cliente. Deberías ver las herramientas hilo_*, los recursos hilo:// y el prompt integrar_con_hilo.

Variables de entorno

Variable	Requerida	Default	Para qué
HILO_API_KEY	No (recomendada)	—	Tu API key. hilo_sbx_… de pruebas, hilo_… productiva. Sin ella el servidor arranca en modo sin credencial.
HILO_ALLOW_PRODUCTION	Solo en producción	false	Debe ser true para aceptar una key productiva.
HILO_BASE_URL	No	https://api.hilo.cenzontle.cloud	Solo para apuntar a otro entorno. Debe ser HTTPS (se acepta http://localhost para desarrollo).
HILO_TIMEOUT_MS	No	30000	Timeout por request.

Qué hace

Le da al agente el contrato de la API, herramientas para verificar su propio trabajo y un plan. La idea es que puedas decir "créame la integración con Hilo" y no tener que supervisarlo.

El plan

El prompt integrar_con_hilo le da al agente el orden completo: credencial → plantillas reales → diseño → implementación → verificación → cierre. En Claude Code aparece como /hilo:integrar_con_hilo, o simplemente pídeselo en tus palabras.

El contrato (recursos)

Recurso	Contenido
hilo://api/reference	Endpoints, cuerpos, respuestas, estados y errores
hilo://api/webhook	Firma HMAC, ejemplos en Node y Python, reglas de operación
hilo://integration/guide	Orden recomendado y los errores que se repiten

Se leen sin API key: el agente puede avanzar en el código mientras consigues la credencial.

Verificación (no necesitan key)

Herramienta	Para qué
hilo_diagnose	Estado de la integración y siguiente paso concreto
hilo_webhook_sample	Evento firmado real para probar tu handler sin exponer nada
hilo_verify_webhook_signature	Depura por qué tu handler rechaza eventos legítimos
hilo_check_webhook_endpoint	Revisa si tu URL sirve (HTTPS, host público)

Contra tu cuenta

Herramienta	Para qué	Costo
hilo_list_templates / hilo_get_template	Qué plantillas existen y qué variables esperan	—
hilo_validate_send / hilo_validate_broadcast	Valida el payload contra la plantilla real, sin enviar	—
hilo_get_usage	Saldo y consumo	—
hilo_get_message / hilo_list_messages	Estados de entrega	—
hilo_get_broadcast / hilo_list_broadcasts	Avance de un envío masivo	—
hilo_send_message	Envío real de prueba	1 crédito
hilo_send_broadcast	Envío masivo (solo producción)	1 por destinatario

Los envíos van marcados como destructivos: tu cliente MCP debería pedirte confirmación.

Dar de alta plantillas no está incluido: se crean en la cuenta real de WhatsApp, las revisa Meta y no tienen ambiente de pruebas. Coordínalas con el operador.

Cómo se usa

Instálalo, ábrelo en tu proyecto y pide la integración:

«Créame la integración con Hilo.»

El agente lee el contrato, corre hilo_diagnose, y si no hay credencial te dice exactamente qué pedirle al operador. Con la key de sandbox puesta, implementa el cliente, el envío y el handler del webhook, y verifica su propio trabajo: valida payloads contra las plantillas reales, manda un mensaje de prueba al número autorizado y comprueba que tu handler acepta un evento firmado y rechaza uno falso.

También sirve suelto:

«¿Por qué mi webhook rechaza los eventos de Hilo?» «Valida este broadcast antes de que lo mande.» «¿Cómo va el broadcast de la boda de Ana?»

Sandbox

Es el modo por defecto. Con una key hilo_sbx_…:

• Los envíos no se cobran.
• Solo llegan al número de prueba que el operador autorizó.
• Hay un tope de mensajes por cuenta.
• hilo_send_broadcast está deshabilitado — usa hilo_send_message para probar.

Todo lo demás —consultar plantillas, estados, broadcasts y saldo— funciona igual que en producción.

Producción

Cuando el operador te entregue tu key productiva, cambia dos cosas en la configuración:

"env": {
  "HILO_API_KEY": "hilo_tu_key_productiva",
  "HILO_ALLOW_PRODUCTION": "true"
}

Las herramientas son exactamente las mismas: lo que construiste y probaste en sandbox sigue funcionando sin tocar una línea. Lo que cambia es que los envíos son reales, se cobran, llegan a cualquier número y se habilita hilo_send_broadcast.

El opt-in existe a propósito: sin él, instalar este servidor nunca puede provocar un envío real por accidente.

Desarrollo

pnpm install
pnpm test         # 43 tests, sin red
pnpm typecheck
pnpm build

Para probar contra un Hilo local:

HILO_API_KEY=hilo_sbx_dev HILO_BASE_URL=http://localhost:3000 node dist/index.js

Estructura

src/
  config.ts          Lectura y validación del entorno
  client.ts          Cliente HTTP de la API v1 (único punto que hace fetch)
  server.ts          Registra recursos, prompt y herramientas
  index.ts           Entrypoint stdio
  reference/         Contrato y guías que se sirven como recursos MCP
  tools/             Una familia de herramientas por archivo

La lógica de herramientas no conoce el transporte, así que añadir un entrypoint HTTP remoto más adelante no obliga a tocarlas.

Licencia

MIT