MCP do KwaFlux não funciona? Soluções para ferramentas sumidas, app_not_running e timeouts

O essencial

• Investigue de fora para dentro: o host inicia o servidor? O servidor chega ao app? O app aceita o trabalho?
• Se nenhuma ferramenta do KwaFlux aparece, a causa está, na grande maioria das vezes, na configuração do host: JSON ou YAML inválido, arquivo errado, Node.js não encontrado ou falta de recarregar.
• app_not_running significa que o servidor funciona, mas o KwaFlux não está aberto (ou não está no mesmo computador).
• Esperas longas que falham depois de cerca de um minuto são um timeout do host, não um trabalho com falha. O trabalho continua rodando no KwaFlux.

Quando a conexão MCP do KwaFlux não funciona, o sintoma indica qual camada examinar. Ou o host não iniciou o servidor, ou o servidor não conseguiu chegar ao app, ou o app recusou o pedido. Cada caso tem uma lista curta de causas, e cada causa tem uma solução precisa.

Neste guia, você vai ver como distinguir as três camadas, as soluções para cada uma, as mensagens de erro que o KwaFlux retorna e uma verificação de dois minutos que dá para fazer sem nenhum host de IA.

Conteúdo

1. O que pode dar errado, camada por camada
2. Camada 1: nenhuma ferramenta do KwaFlux no host
3. Camada 2: as ferramentas aparecem, mas as chamadas falham com app_not_running
4. Camada 3: o app recusa o trabalho
5. Esperas que estouram o tempo
6. Trabalhos que falham ou não geram nada
7. Uma verificação sem nenhum host de IA
8. Referência rápida
9. Perguntas frequentes

O que pode dar errado, camada por camada

Um pedido passa por três peças:

1. O host (Cursor, Claude, Codex, DeepSeek Harness, Hermes, OpenClaw) lê a própria configuração e inicia o servidor MCP do KwaFlux.
2. O servidor MCP, um script Node.js no Windows ou um auxiliar dentro do app no Mac, se conecta ao KwaFlux em execução.
3. O KwaFlux verifica o pedido e coloca o trabalho na fila.

Camada 1: nenhuma ferramenta do KwaFlux no host

1. O arquivo de configuração é inválido. Um único erro pode fazer o host descartar todos os servidores do arquivo.

• JSON (Cursor, Claude, OpenClaw): os caminhos do Windows precisam de barras invertidas duplas, C:\\Program Files\\.... Sem comentários e sem vírgulas sobrando no fim.
• TOML (Codex): use aspas simples nos caminhos do Windows, como faz o trecho do KwaFlux, ou duplique cada barra invertida.
• YAML (DeepSeek Harness, Hermes): mantenha o recuo do trecho; aspas simples mantêm as barras invertidas como estão.

2. Está no arquivo ou no escopo errado.

3. O Node.js não é encontrado. No Windows, o host inicia o servidor com o Node.js 18 ou mais recente. O cartão nas configurações do KwaFlux procura o Node.js e grava o caminho completo dele na configuração. Se o cartão disser “Node.js não encontrado. Os hosts iniciam este servidor com Node.js 18 ou posterior; instale-o primeiro.” ou que a sua versão “é antigo demais”, instale a versão LTS atual, clique em Verificar Node.js novamente e copie a configuração outra vez. Se você escreveu a configuração à mão com um simples "node", troque pelo caminho completo, como C:\Program Files\nodejs\node.exe, ou reinicie o host para ele pegar o PATH novo.

4. O caminho do servidor está errado. O script é o kwaflux_mcp.mjs, em Tools\kwaflux-mcp, dentro da pasta de instalação do KwaFlux. Se você instalou o KwaFlux em outro lugar que não C:\Program Files\KwaFlux, copie o trecho do cartão Configurações › Agent (MCP) do KwaFlux, que preenche o caminho real. Se o cartão avisar “Nenhum servidor MCP incluído foi encontrado, então o caminho abaixo é apenas um espaço reservado”, reinstale o KwaFlux.

5. O host não foi recarregado. Cada host tem o seu jeito:

Guias passo a passo por host: Cursor, Claude Code e Claude Desktop, Codex, DeepSeek Harness, Hermes e OpenClaw.

Camada 2: as ferramentas aparecem, mas as chamadas falham com app_not_running

Este é o caso mais fácil. No Windows, a mensagem completa é parecida com esta:

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

Ela significa que o servidor iniciou sem problemas, mas não encontrou nenhum KwaFlux em execução com quem conversar. Soluções:

• Abra o KwaFlux e espere a janela aparecer; depois, peça de novo. Não é preciso recarregar o host.
• Mesmo computador, mesmo usuário. O servidor só alcança um KwaFlux que esteja rodando no mesmo computador e na mesma conta do Windows ou do macOS. Um agente em uma VPS, um Cursor Cloud Agent ou uma sessão em outra conta de usuário não conseguem alcançá-lo.

Camada 3: o app recusa o trabalho

Quando o KwaFlux recusa um pedido, o resultado da ferramenta diz por quê. Os motivos mais comuns:

Caminhos de rede como \\server\share\clip.mp4 são recusados de propósito, antes de qualquer arquivo ser aberto. Copie o arquivo para um disco local antes. Para entender o motivo, veja as regras de caminhos e privacidade.

Esperas que estouram o tempo

A ferramenta de espera do KwaFlux espera até 300 segundos em uma única chamada, 60 por padrão. Alguns hosts dão menos tempo que isso a uma chamada MCP:

Uma espera que estoura o tempo não interrompe o trabalho. Ele continua rodando na lista de tarefas do KwaFlux, e o assistente pode esperar de novo ou consultar o status.

Trabalhos que falham ou não geram nada

• Leia o motivo do erro da tarefa. Peça ao assistente: “Consulte a tarefa no KwaFlux e me diga qual foi o erro.” Os detalhes da tarefa incluem o motivo.
• Veja para onde foi o resultado. Os resultados são gravados ao lado do arquivo de entrada, não em uma pasta indicada pelo assistente, e um arquivo existente com o mesmo nome é mantido: o novo é renomeado para name(1).ext. Os arquivos convertidos terminam em _kwaflux_<format>-<tier>, e os reparados, em _repair.
• O reparo precisa de uma referência. Se o diagnóstico disser que é necessário um arquivo de referência, forneça um clipe íntegro gravado pela mesma câmera. Veja Reparo de arquivo.
• Não disponível pelo chat. A interpolação de quadros e as ferramentas de recorte e de substituição não são oferecidas via MCP. Faça isso no app.
• Ainda falhando? Tente mais uma vez na própria janela do KwaFlux. Se falhar lá também, não é um problema de MCP; envie o motivo do erro da tarefa para o suporte.

Uma verificação sem nenhum host de IA

Se você não tem certeza de que o servidor consegue sequer iniciar, rode-o à mão em um terminal:

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

Um servidor saudável não exibe nada e fica aguardando entrada, porque está esperando que um host converse com ele. Pressione Ctrl+C para encerrá-lo. Se aparecer um erro, como “not recognized” (no Windows em português, “não é reconhecido”; o Node.js não está no PATH) ou “Cannot find module” (caminho errado), corrija isso primeiro; trocar de host não vai resolver.

Referência rápida

Conclusão

Encontre a camada primeiro. Sem ferramentas, o problema é a configuração do host; app_not_running quer dizer que o app não está aberto neste computador; uma recusa informa o próprio motivo; uma falha depois de um minuto é timeout do host. Na dúvida, rode o servidor à mão: se ele ficar esperando em silêncio, o problema está no host ou no app, não no servidor.

Faça o KwaFlux funcionar com o seu assistente

O KwaFlux inclui um servidor MCP local para o Cursor, o Claude, o Codex, o DeepSeek Harness, o Hermes, o OpenClaw e outros apps compatíveis com MCP. O processamento de IA roda na sua própria GPU e os seus arquivos de mídia não são enviados para processamento. Roda no Windows 10 (64 bits, versão 1809 ou mais recente), no Windows 11 e no macOS 12 ou mais recente em Apple Silicon. Importar arquivos e explorar o app não exigem conta. O login com um plano pago só é necessário para exportar, converter, reparar um arquivo ou baixar um arquivo de um link.

Baixar o KwaFlux · Ver planos