The Hilo MCP server enables AI agents to integrate with the Hilo WhatsApp messaging platform (by Cenzontle). It provides tools for diagnostics, webhook management, template handling, validation, usage tracking, and messaging.
Diagnostics: hilo_diagnose checks API credentials, balance, templates, and suggests next steps.
Webhooks: Generate signed samples (hilo_webhook_sample), verify signatures (hilo_verify_webhook_signature), and validate endpoint URLs (hilo_check_webhook_endpoint).
Templates: List approved templates (hilo_list_templates) and get template details with variables (hilo_get_template).
Validation (no cost): Validate single messages (hilo_validate_send) or broadcast payloads (hilo_validate_broadcast) against real templates without sending.
Account Usage: Check credit balance, billed messages, and estimated spend (hilo_get_usage).
Send Messages (costs credits): Send single messages to test/production numbers (hilo_send_message), check delivery (hilo_get_message), and list messages (hilo_list_messages).
Broadcasts (production only): Send bulk template messages (hilo_send_broadcast), get broadcast details (hilo_get_broadcast), and list broadcasts (hilo_list_broadcasts).
Guided Integration: A dedicated prompt (integrar_con_hilo) provides a full integration plan covering credentials, templates, design, and verification.
Provides integration with Hilo, a WhatsApp messaging platform, enabling message sending, template management, usage checking, and webhook verification for WhatsApp communications.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hilo MCP Créame la integración con Hilo."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Claude Code:
claude mcp add hilo -e HILO_API_KEY=hilo_sbx_TU_KEY -- npx -y @cenzontle/hilo-mcpDespué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.
Related MCP server: lingtai-whatsapp
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.
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.
Variable | Requerida | Default | Para qué |
| No (recomendada) | — | Tu API key. |
| Solo en producción |
| Debe ser |
| No |
| Solo para apuntar a otro entorno. Debe ser HTTPS (se acepta |
| No |
| Timeout por request. |
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 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.
Recurso | Contenido |
| Endpoints, cuerpos, respuestas, estados y errores |
| Firma HMAC, ejemplos en Node y Python, reglas de operación |
| 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.
Herramienta | Para qué |
| Estado de la integración y siguiente paso concreto |
| Evento firmado real para probar tu handler sin exponer nada |
| Depura por qué tu handler rechaza eventos legítimos |
| Revisa si tu URL sirve (HTTPS, host público) |
Herramienta | Para qué | Costo |
| Qué plantillas existen y qué variables esperan | — |
| Valida el payload contra la plantilla real, sin enviar | — |
| Saldo y consumo | — |
| Estados de entrega | — |
| Avance de un envío masivo | — |
| Envío real de prueba | 1 crédito |
| 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.
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?»
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.
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.
pnpm install
pnpm test # 43 tests, sin red
pnpm typecheck
pnpm buildPara probar contra un Hilo local:
HILO_API_KEY=hilo_sbx_dev HILO_BASE_URL=http://localhost:3000 node dist/index.jssrc/
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 archivoLa lógica de herramientas no conoce el transporte, así que añadir un entrypoint HTTP remoto más adelante no obliga a tocarlas.
MIT
Comprueba que la URL de tu webhook cumple lo que Hilo exige antes de configurarla: HTTPS y host público. Hilo bloquea localhost y redes privadas por defensa anti-SSRF, así que para desarrollo hace falta un túnel. NO hace ninguna petición a la URL.
Inputs: url (required).
Revisa el estado de la conexión con Hilo y devuelve los siguientes pasos concretos. EJECÚTALA PRIMERO, antes de escribir código: te dice si hay credencial, si es de sandbox o productiva, si la API responde, si hay saldo y cuántas plantillas hay disponibles para enviar. Si falta la key, explica exactamente cómo pedirla.
Inputs: no named parameters.
Devuelve el detalle de un broadcast con el conteo por estado (status_summary): cuántos se entregaron, cuántos fallaron y cuántos siguen en cola.
Inputs: id (required).
Devuelve el estado de entrega de un mensaje por su ref. Estados: queued → sent → delivered → read, o failed con failureReason (insufficient_credits | opt_out | provider_rejected).
Inputs: ref (required).
Devuelve el estado y la estructura (componentes y variables) de una plantilla por nombre.
Inputs: name (required), language.
Devuelve el saldo de créditos, los mensajes facturados del periodo y el gasto estimado. Un crédito equivale a un mensaje. Consúltalo antes de un envío masivo: sin saldo suficiente los envíos quedan en failed con insufficient_credits.
Inputs: no named parameters.
Lista los broadcasts con su resumen por estado. Se puede filtrar por metadata propia.
Inputs: limit, metadata.
Lista los mensajes enviados, del más reciente al más antiguo. Se puede filtrar por broadcast, por estado y por metadata propia.
Inputs: limit, status, metadata, broadcast.
Lista las plantillas disponibles para esta cuenta con su estado en Meta (APPROVED, PENDING, REJECTED). Solo se pueden enviar las APPROVED. Consúltala antes de enviar para usar el nombre exacto y saber qué variables espera.
Inputs: no named parameters.
Envía una plantilla aprobada a MUCHOS destinatarios de una vez. CUESTA UN CRÉDITO POR DESTINATARIO y llega a personas reales: muestra la lista y el total a quien te lo pide, y espera su confirmación antes de llamarla. Usa idempotencyKey para que un reintento no duplique los envíos. No disponible en cuentas de sandbox.
Inputs: template (required), recipients (required), language, metadata, +2 more.
Envía UNA plantilla de WhatsApp ya aprobada por Meta a un número. CUESTA UN CRÉDITO de la bolsa del cliente y le llega a una persona real: confirma el destinatario y el contenido antes de llamarla. Esta cuenta es de SANDBOX: solo puede enviar al número de prueba autorizado y no se cobra. Devuelve un ref para consultar el estado después con hilo_get_message.
Inputs: toPhone (required), templateName (required), language, variables, +1 more.
Revisa un payload de POST /v1/broadcasts sin enviarlo: teléfonos duplicados o mal formados, variables faltantes por destinatario (considerando template_variables compartidas) y estado de la plantilla. Reporta también el costo en créditos. NO envía nada. Corre esto antes de cualquier envío masivo.
Inputs: template (required), recipients (required), language, idempotencyKey, +1 more.
Revisa un payload de POST /v1/messages contra la plantilla REAL del catálogo: formato del teléfono, existencia y estado de la plantilla, y que las variables del BODY y del HEADER sean exactamente las que espera. NO envía nada ni gasta créditos. Úsala con el payload que genera tu código antes de disparar un envío de verdad.
Inputs: toPhone (required), templateName (required), language, variables, +1 more.
Comprueba si una firma corresponde a un cuerpo y un secreto, con la misma fórmula que usa Hilo. Úsala para depurar cuando tu handler rechaza eventos legítimos: casi siempre es porque se firmó el JSON re-serializado en vez del cuerpo crudo.
Inputs: secret (required), rawBody (required), signature (required).
Devuelve un evento de estado idéntico a los que manda Hilo, junto con su header X-Hilo-Signature válido para el secreto que le pases. Sirve para probar TU handler sin exponer un endpoint público ni esperar un mensaje real: manda este cuerpo crudo y este header a tu servidor y comprueba que lo acepta. Prueba también con una firma alterada: tu handler DEBE responder 401.
Inputs: secret (required), ref, status, failureReason.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 15 tools
Each tool has a clearly distinct purpose, from diagnostics to template management, validation, sending, and webhooks. No two tools overlap in functionality; descriptions are detailed and differentiate them.
All tool names follow a consistent 'hilo_verb_noun' pattern with lowercase underscores. Verbs are specific and indicative of the action (get, list, validate, send, etc.).
15 tools is well-scoped for the domain of WhatsApp messaging. It covers diagnostics, templates, validation, sending, broadcasts, webhooks, and usage monitoring without being excessive.
The surface covers the core workflows: connectivity check, template listing, payload validation, single/mass sending, status tracking, and webhook management. Missing are tools to update or delete templates, but the focus on sending and validation is comprehensive.
WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.
MCP server for Vonage API documentation, code snippets, tutorials, and troubleshooting.
MCP Server for agents to onboard, pay, and provision services autonomously with InFlow
WhatsApp (Web + Business API), SMS, contacts, and call records via 2Chat's MCP server.
