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.

Aug 19, 2026

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

  1. Reinicia la aplicación por completo, no solo la ventana.
  2. 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.
  3. Verifica que npx esté en el PATH con el que arranca la aplicación. Si tienes dudas, pon la ruta absoluta de npx en command.
  4. 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 bloque env, no en args.
  • unknown MCP_SERVER_MODE=... — el valor no es stdio ni http; el servidor sigue en stdio y 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

  • 422 al cambiar la disponibilidad de un agente. set_user_status necesita el id del espacio de trabajo en el cuerpo de la petición: define OMNIFOX_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_window y, si está cerrada, envía una plantilla aprobada con send_message y type: whatsapp_template.
  • La reserva de una cita falla. El starts_at tiene 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_contacts exige al menos 2 caracteres y busca por nombre, correo y teléfono; para buscar por id usa get_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_RETRIES en 0: 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. Un 200 descarta el problema de credenciales.

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp