KwaFlux MCP Not Working? Fixes for Missing Tools, app_not_running, and Timeouts

Key takeaways

• Work from the outside in: does the host start the server, does the server reach the app, does the app accept the job?
• If no KwaFlux tools appear, the cause is nearly every time the host config: invalid JSON or YAML, the wrong file, Node.js not found, or no reload.
• app_not_running means the server works but KwaFlux isn't open (or isn't on the same computer).
• Long waits that fail after about a minute are a host timeout, not a failed job. The job keeps running in KwaFlux.

When KwaFlux's MCP connection doesn't work, the symptom tells you which layer to look at. Either the host didn't start the server, or the server couldn't reach the app, or the app refused the request. Each has a short list of causes, and each cause has an exact fix.

In this guide, you'll learn how to tell the three layers apart, the fixes for each, the error messages KwaFlux returns, and a two-minute check you can run without any AI host.

Contents

1. What can go wrong, layer by layer
2. Layer 1: no KwaFlux tools in the host
3. Layer 2: tools appear, but calls fail with app_not_running
4. Layer 3: the app refuses the job
5. Waits that time out
6. Jobs that fail or produce nothing
7. A check without any AI host
8. Quick reference
9. FAQ

What can go wrong, layer by layer

A request passes through three pieces:

1. The host (Cursor, Claude, Codex, DeepSeek Harness, Hermes, OpenClaw) reads its config and starts KwaFlux's MCP server.
2. The MCP server, a Node.js script on Windows or a helper inside the app on Mac, connects to the running KwaFlux app.
3. KwaFlux checks the request and queues the job.

Layer 1: no KwaFlux tools in the host

1. The config file is invalid. One error can make the host drop every server in the file.

• JSON (Cursor, Claude, OpenClaw): Windows paths need double backslashes, C:\\Program Files\\.... No comments, no trailing commas.
• TOML (Codex): use single quotes around Windows paths, as KwaFlux's snippet does, or double every backslash.
• YAML (DeepSeek Harness, Hermes): keep the indentation of the snippet; single quotes keep backslashes as they are.

2. It's in the wrong file or scope.

3. Node.js isn't found. On Windows, the host starts the server with Node.js 18 or newer. KwaFlux's Settings card looks for it and writes its full path into the config. If the card says "Node.js not found. Hosts start this server with Node.js 18 or later; install it first." or that your version "is too old", install the current LTS release, click Check for Node.js again, and copy the config again. If you wrote the config by hand with plain "node", replace it with the full path, such as C:\Program Files\nodejs\node.exe, or restart the host so it picks up the new PATH.

4. The path to the server is wrong. The script is kwaflux_mcp.mjs in Tools\kwaflux-mcp inside the KwaFlux install folder. If you installed KwaFlux somewhere other than C:\Program Files\KwaFlux, copy the snippet from KwaFlux's Settings › Agent (MCP) card, which fills in the real path. If the card warns "No bundled MCP server was found, so the path below is only a placeholder," reinstall KwaFlux.

5. The host wasn't reloaded. Each host has its own way:

Per-host walkthroughs: Cursor, Claude Code and Claude Desktop, Codex, DeepSeek Harness, Hermes and OpenClaw.

Layer 2: tools appear, but calls fail with app_not_running

This is the easiest one. On Windows, the full message looks like this:

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

It means the server started fine but found no running KwaFlux to talk to. Fixes:

• Open KwaFlux and wait until its window is up, then ask again. You don't need to reload the host.
• Same computer, same user. The server only reaches a KwaFlux running on the same computer under the same Windows or macOS account. An agent on a VPS, a Cursor Cloud Agent, or a session under another user account can't reach it.

Layer 3: the app refuses the job

When KwaFlux refuses a request, the tool result says why. The common ones:

Network paths like \\server\share\clip.mp4 are refused on purpose, before any file is opened. Copy the file to a local drive first. For why, see path and privacy rules.

Waits that time out

KwaFlux's wait tool waits up to 300 seconds in one call, 60 by default. Some hosts give an MCP call less than that:

A timed-out wait doesn't stop the job. It keeps running in KwaFlux's task list, and the assistant can wait again or check its status.

Jobs that fail or produce nothing

• Read the task's error reason. Ask the assistant: "Get the KwaFlux task and tell me its error." The task details include the reason.
• Check where the output went. Results are written next to the input, not to a folder the assistant names, and an existing file with the same name is kept: the new one is renamed name(1).ext. Converted files end in _kwaflux_<format>-<tier>, repaired files in _repair.
• Repair needs a reference. If the diagnosis says a reference file is required, give a healthy clip from the same camera. See Video File Repair.
• Not available from chat. Frame interpolation and the matting and replace tools aren't offered over MCP. Do them in the app.
• Still failing? Retry once in the KwaFlux window itself. If it fails there too, it's not an MCP problem; send the task's error reason to support.

A check without any AI host

If you're not sure whether the server can start at all, run it by hand in a terminal:

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

A healthy server prints nothing and waits for input, because it's waiting for a host to talk to it. Press Ctrl+C to stop it. If you see an error instead, such as "not recognized" (Node.js isn't on PATH) or "Cannot find module" (wrong path), fix that first; no host will do better.

Quick reference

Final thoughts

Find the layer first. No tools means the host config; app_not_running means the app isn't open on this computer; a refusal names its own reason; a one-minute failure is a host timeout. When in doubt, run the server by hand: if it waits quietly, the problem is in the host or the app, not the server.

Get KwaFlux working with your assistant

KwaFlux includes a local MCP server for Cursor, Claude, Codex, DeepSeek Harness, Hermes, OpenClaw, and other MCP apps. AI processing runs locally on your GPU — media files are not uploaded for processing. It runs on Windows 10 (64-bit, version 1809 or later), Windows 11, and macOS 12 or newer on Apple Silicon. Importing files and exploring the app need no account. Signing in with an active paid plan is required only to export, convert, repair a file, or download a file from a link.

Download KwaFlux · See plans