¿KwaFlux MCP no funciona? Soluciones si no aparecen las herramientas, sale app_not_running o se agota el tiempo de espera

Lo esencial

• Ve de fuera hacia dentro: ¿arranca el host el servidor?, ¿llega el servidor a la app?, ¿acepta la app el trabajo?
• Si no aparece ninguna herramienta de KwaFlux, la causa está, en la gran mayoría de los casos, en la configuración del host: JSON o YAML no válido, archivo equivocado, Node.js no encontrado o falta de recarga.
• app_not_running significa que el servidor funciona, pero KwaFlux no está abierto (o no está en el mismo ordenador).
• Si las esperas largas fallan al cabo de un minuto, más o menos, es un tiempo de espera del host, no un trabajo fallido. El trabajo sigue en marcha en KwaFlux.

Cuando la conexión MCP de KwaFlux no funciona, el síntoma indica en qué capa mirar: o el host no arrancó el servidor, o el servidor no pudo llegar a la app, o la app rechazó la petición. Cada caso tiene una lista corta de causas, y cada causa, una solución concreta.

En esta guía verás cómo distinguir las tres capas, las soluciones de cada una, los mensajes de error que devuelve KwaFlux y una comprobación de dos minutos que puedes hacer sin ningún host de IA.

Contenido

1. Qué puede fallar, capa por capa
2. Capa 1: no aparece ninguna herramienta de KwaFlux en el host
3. Capa 2: las herramientas aparecen, pero las llamadas fallan con app_not_running
4. Capa 3: la app rechaza el trabajo
5. Esperas que agotan el tiempo
6. Trabajos que fallan o no generan nada
7. Una comprobación sin ningún host de IA
8. Referencia rápida
9. Preguntas frecuentes

Qué puede fallar, capa por capa

Una petición pasa por tres piezas:

1. El host (Cursor, Claude, Codex, DeepSeek Harness, Hermes, OpenClaw) lee su configuración y arranca el servidor MCP de KwaFlux.
2. El servidor MCP, un script de Node.js en Windows o un programa auxiliar dentro de la app en Mac, se conecta a la app de KwaFlux en ejecución.
3. KwaFlux comprueba la petición y pone el trabajo en cola.

Capa 1: no aparece ninguna herramienta de KwaFlux en el host

1. El archivo de configuración no es válido. Un solo error puede hacer que el host descarte todos los servidores del archivo.

• JSON (Cursor, Claude, OpenClaw): las rutas de Windows necesitan barras invertidas dobles, C:\\Program Files\\.... Sin comentarios y sin comas finales.
• TOML (Codex): pon las rutas de Windows entre comillas simples, como hace el fragmento de KwaFlux, o duplica cada barra invertida.
• YAML (DeepSeek Harness, Hermes): respete la sangría del fragmento; las comillas simples dejan las barras invertidas tal cual.

2. Está en el archivo o el ámbito equivocado.

3. No se encuentra Node.js. En Windows, el host arranca el servidor con Node.js 18 o superior. La tarjeta de Ajustes de KwaFlux lo busca y escribe su ruta completa en la configuración. Si la tarjeta dice «No se encontró Node.js. Los hosts inician este servidor con Node.js 18 o posterior; instálelo primero.» o que tu Node.js «es demasiado antiguo», instala la versión LTS actual, haz clic en Volver a buscar Node.js y copia de nuevo la configuración. Si escribiste la configuración a mano con un simple "node", sustitúyelo por la ruta completa, por ejemplo C:\Program Files\nodejs\node.exe, o reinicia el host para que lea el nuevo PATH.

4. La ruta al servidor es incorrecta. El script es kwaflux_mcp.mjs, en Tools\kwaflux-mcp dentro de la carpeta de instalación de KwaFlux. Si instalaste KwaFlux en otro sitio que no sea C:\Program Files\KwaFlux, copia el fragmento desde la tarjeta Ajustes › Agent (MCP) de KwaFlux, que rellena la ruta real. Si la tarjeta avisa «No se encontró el servidor MCP incluido, así que la ruta de abajo es solo un marcador», reinstala KwaFlux.

5. No se ha recargado el host. Cada host tiene su manera:

Guías paso a paso por host: Cursor, Claude Code y Claude Desktop, Codex, DeepSeek Harness, Hermes y OpenClaw.

Capa 2: las herramientas aparecen, pero las llamadas fallan con app_not_running

Es el caso más fácil. En Windows, el mensaje completo tiene este aspecto:

app_not_running: Error: app_not_running: no control file of a running KwaFlux in C:\Users\<you>\AppData\Local\KwaFlux\agent

Significa que el servidor arrancó bien, pero no encontró ningún KwaFlux en ejecución con el que hablar. Soluciones:

• Abre KwaFlux y espera a que aparezca su ventana; después, vuelve a preguntar. No hace falta recargar el host.
• El mismo ordenador y el mismo usuario. El servidor solo llega a un KwaFlux que se ejecute en el mismo ordenador y con la misma cuenta de Windows o macOS. Un agente en un VPS, un Cloud Agent de Cursor o una sesión con otra cuenta de usuario no pueden llegar a él.

Capa 3: la app rechaza el trabajo

Cuando KwaFlux rechaza una petición, el resultado de la herramienta indica el motivo. Los más comunes:

Las rutas de red como \\server\share\clip.mp4 se rechazan a propósito, antes de abrir ningún archivo. Copia primero el archivo a una unidad local. Para saber por qué, consulta las reglas sobre rutas y privacidad.

Esperas que agotan el tiempo

La herramienta de espera de KwaFlux espera hasta 300 segundos en una sola llamada, 60 por defecto. Algunos hosts dan a una llamada MCP menos tiempo que eso:

Una espera que agota el tiempo no detiene el trabajo. Este sigue en marcha en la lista de tareas de KwaFlux, y el asistente puede volver a esperar o consultar su estado.

Trabajos que fallan o no generan nada

• Lee el motivo del error de la tarea. Pide al asistente: «Consulta la tarea de KwaFlux y dime cuál es su error.» Los detalles de la tarea incluyen el motivo.
• Comprueba dónde ha ido el resultado. Los resultados se guardan junto al archivo de entrada, no en una carpeta que indique el asistente, y si ya existe un archivo con el mismo nombre, se conserva: el nuevo se renombra como name(1).ext. Los archivos convertidos terminan en _kwaflux_<format>-<tier>, y los reparados, en _repair.
• La reparación necesita una referencia. Si el diagnóstico dice que hace falta un archivo de referencia, aporta un clip en buen estado grabado con la misma cámara. Consulta Reparación de archivo de vídeo.
• No disponible desde el chat. La interpolación de fotogramas y las herramientas de recorte y sustitución no se ofrecen por MCP. Úsalas en la app.
• ¿Sigue fallando? Vuelve a intentarlo una vez en la propia ventana de KwaFlux. Si también falla ahí, no es un problema de MCP; envía al soporte el motivo del error de la tarea.

Una comprobación sin ningún host de IA

Si no estás seguro de que el servidor llegue siquiera a arrancar, ejecútalo a mano en un terminal:

node "C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs"

Un servidor sano no muestra nada y se queda esperando una entrada, porque está esperando a que un host le hable. Pulsa Ctrl+C para detenerlo. Si en su lugar ves un error, como «not recognized» (en Windows en español, «no se reconoce como un comando interno o externo»; Node.js no está en el PATH) o «Cannot find module» (ruta equivocada), corrígelo primero; ningún host funcionará mejor.

Referencia rápida

Conclusión

Primero, localiza la capa. Si no hay herramientas, es la configuración del host; app_not_running significa que la app no está abierta en este ordenador; un rechazo indica su propio motivo; un fallo al minuto es un tiempo de espera del host. Si tienes dudas, ejecuta el servidor a mano: si se queda esperando en silencio, el problema está en el host o en la app, no en el servidor.

Haz que KwaFlux funcione con tu asistente

KwaFlux incluye un servidor MCP local para Cursor, Claude, Codex, DeepSeek Harness, Hermes, OpenClaw y otras apps MCP. El procesamiento de IA corre en tu propia GPU y tus archivos multimedia no se suben para procesarlos. Funciona en Windows 10 (64 bits, versión 1809 o posterior), Windows 11 y macOS 12 o posterior en Apple Silicon. Importar archivos y explorar la app no requieren cuenta. Iniciar sesión con un plan de pago solo hace falta para exportar, convertir, reparar un archivo o descargar un archivo desde un enlace.

Descargar KwaFlux · Ver planes