Solución de problemas del servidor MCP de Omnifox
Los errores más comunes al usar @omnifox/mcp-server y qué revisar en cada caso, del arranque a los códigos de la API.
Mira este paso en el video · Solución de problemas
Guía rápida para cuando el servidor MCP de Omnifox no responde como esperas. Los mensajes del servidor se escriben en stderr, así que revisa el registro de tu cliente de IA: ahí aparecen.
No aparece ninguna herramienta en el cliente
- Reinicia la aplicación por completo, no solo la ventana.
- Comprueba que el JSON de configuración sea válido: una coma de más rompe el archivo entero y el cliente lo ignora en silencio.
- Verifica que
npxesté en el PATH con el que arranca la aplicación. Si tienes dudas, pon la ruta absoluta denpxencommand. - Comprueba la versión de Node: hace falta 18.17 o superior.
El servidor no arranca
OMNIFOX_API_KEY is required— la variable no llegó al proceso. Tiene que ir en el bloqueenv, no enargs.unknown MCP_SERVER_MODE=...— el valor no esstdionihttp; el servidor sigue enstdioy lo avisa por stderr.
Códigos de error de la API
| Código | Qué significa | Qué hacer |
|---|---|---|
401 |
Token inválido, revocado o vencido. | Emite una clave nueva en Configuración → Desarrollo → API Keys. |
402 / PLAN_API_ACCESS_REQUIRED |
El plan no incluye Acceso a API, o el módulo consultado no está en el plan. | Acceso a API está disponible desde el plan Crece. |
403 |
A la clave le falta el scope de ese módulo. | Edita la clave y agrega el permiso (read:crm, write:projects, etc.). |
404 |
El registro no existe en el espacio de trabajo de la clave. | Los ids son por espacio; revisa que la clave apunte al correcto. |
422 |
Faltan campos o vienen mal. | El mensaje de error trae el detalle campo por campo. |
429 |
Superaste el límite de solicitudes por minuto de tu plan. | El servidor reintenta solo, respetando Retry-After, hasta OMNIFOX_MAX_RETRIES veces. |
Casos concretos que confunden
422al cambiar la disponibilidad de un agente.set_user_statusnecesita el id del espacio de trabajo en el cuerpo de la petición: defineOMNIFOX_WORKSPACE_ID.- El mensaje de WhatsApp no llega y no hay error claro. La ventana de 24 horas está cerrada. Consulta primero
get_conversation_sending_windowy, si está cerrada, envía una plantilla aprobada consend_messageytype: whatsapp_template. - La reserva de una cita falla. El
starts_attiene que ser exactamente uno de los que devolviólist_free_slots; si pasó tiempo, vuelve a consultarlos. - El asistente dice que no encuentra un contacto que sí existe.
search_contactsexige al menos 2 caracteres y busca por nombre, correo y teléfono; para buscar por id usaget_contact. - Todo va lento o corta. Sube
OMNIFOX_TIMEOUT_MS; el valor por defecto es 30 segundos por petición.
Consejos
- Mientras depuras, pon
OMNIFOX_MAX_RETRIESen0: el error real aparece de inmediato en vez de después de tres reintentos. - Si sospechas del token, pruébalo aparte con
curl:curl -H "Authorization: Bearer TU_TOKEN" https://omnifox.io/api/v1/contacts. Un200descarta el problema de credenciales.
Artículos relacionados
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.