Drive KwaFlux from Codex, Claude, OpenClaw, DeepSeek, Hermes, and Cursor
KwaFlux comes with a local MCP server. Keep the app open and connect Codex, Claude, OpenClaw, DeepSeek, Hermes, or Cursor. Convert, repair, enhance, and download need sign-in and a paid plan.
What this is
Yes, an AI agent can drive KwaFlux: the desktop app comes with a local MCP server that Codex, Claude, OpenClaw, DeepSeek (DSH), Hermes, and Cursor can connect to. Open Settings › Advanced › Agent (MCP), copy the config into your chat app, and keep KwaFlux running. The link is local stdio on this computer, with no OAuth step.

Where each host stores the config
| Host | Where it goes |
|---|---|
| Codex | Append to ~/.codex/config.toml. The key is mcp_servers. Restart Codex, or run /mcp. |
| Claude Code | Project .mcp.json, or the install command. Open a new session after you change it. |
| Claude Desktop | Merge into claude_desktop_config.json, then quit the app fully. On Windows the file is under %APPDATA%\Claude\. |
| OpenClaw | Merge into ~/.openclaw/openclaw.json under mcp.servers, or run openclaw mcp set. |
| DeepSeek | A DSH profile YAML. Restart the DSH session. |
| Hermes | Run hermes mcp add, or write mcp_servers in config.yaml (%LOCALAPPDATA%\hermes on native Windows, ~/.hermes elsewhere). |
| Cursor | Use the in-app install, then Reload MCP in Cursor. |
What the agent can do
It can read whether the app is running and signed in, list tasks, and wait for one to finish. It can also pause, resume, cancel, or retry a task it started. Diagnose a damaged file before you repair it.
- Convert: exports to 64 formats by quality tier, with presets for YouTube, TikTok, and other platforms, and turns a time range into a GIF. The file lands next to the input.
- Repair: Diagnose can run first.
- Enhance: quality repair, color, stabilization, deinterlace, smart effects, and beauty. The file lands next to the input.
- Download: look up a link, then save it. Downloads stay off until you choose Ask every time under Agent access. KwaFlux then asks you in a popup before each one.
- Frame interpolation stays in the desktop app.
- Matting and background replacement for people, objects, and the sky stay in the desktop app.
- Clicking a subject on a paused frame stays in the desktop app.
- The agent cannot control a task you started yourself in the window.
Downloads stay off until you say so
Open Settings › General and find Agent access. Let agents start downloads has three modes: off, Ask every time, and one that lets downloads through without asking. With Ask every time, KwaFlux shows a desktop popup with the link, the folder, and the format, and only your click approves it. An unanswered popup expires after 120 seconds. The assistant also asks you in the chat to confirm you have the right to save the file, but its own claim doesn't count. KwaFlux does not sign into a site or skip a paywall.
Limits
Paths must be absolute and on this computer. Convert and enhance do not let the agent choose the output folder. The app itself is on download.
The agent route needs no extra license: one license covers the app and its MCP server on up to two computers, Windows and Mac in any mix. Jobs an agent starts run on that computer, and media files are not uploaded for processing.
What stays in the window
The agent can do the jobs listed above, and nothing beyond that list. It can check whether the app is running and whether you're signed in. It can list tasks and wait for one to finish. It can pause, resume, cancel, or retry a task it started. It can diagnose a damaged file before a repair. It can't control a task you started yourself by clicking in the KwaFlux window.
Convert exports to 64 formats by quality tier and can turn a time range into a GIF. Enhance covers quality repair, color, stabilization, deinterlace, smart effects, and beauty. The file lands next to the input. The agent does not choose that folder. Paths you give it have to be absolute paths on this computer.
Some features stay in the desktop app, and the agent does not run them: frame interpolation, matting and background replacement, clicking a subject on a paused frame, and the free 1-, 3-, and 5-second previews.
Downloads stay off until you set them to Ask every time under Agent access. Then KwaFlux asks you in a popup before each one. A sentence from the assistant does not count as approval. KwaFlux does not sign into a website for you, and it does not skip a paywall. The host table above shows where each app stores the config that Settings copied. Do not invent a path. Keep KwaFlux open while the chat app is connected over local stdio.
If it won't connect, or a job fails
Check the KwaFlux side first. Open Settings › General. Under Agent access, the line below Allow AI agents to control KwaFlux names each host that's connected right now. If it reads No agents connected, the chat app didn't reach KwaFlux at all, so the fix is on the chat app's side.
- Run
node --versionin a terminal. The server needs Node.js 18 or newer. An older version stops it at launch, and the host's log says so in plain words. - Codex: type
/mcpin the terminal UI to see active servers, or runcodex mcp list. - Claude Code:
claude mcp listputs a status next to each server, such as Connected or Failed to connect. A server from a project .mcp.json waits for your approval the first time you runclaude. - Claude Desktop: logs are in %APPDATA%\Claude\logs on Windows and ~/Library/Logs/Claude on a Mac. mcp.log covers connections, and mcp-server-kwaflux.log holds the server's own messages.
- Cursor: open the Output panel with Ctrl+Shift+U (Cmd+Shift+U on a Mac) and pick MCP Logs from the dropdown.
Once it's connected, a failed job comes back with a short code, and assistants tend to paraphrase it. Recent agent actions, in the same panel, lists each call with its host and result, so you can read the code yourself.
| Code | What it means | What to do |
|---|---|---|
app_not_running | KwaFlux isn't open on this computer. | Open KwaFlux, then reload MCP or restart the chat app. |
agent_control_disabled | Allow AI agents to control KwaFlux is turned off. | Turn it back on in Settings › General › Agent access. |
not_signed_in, entitlement_denied | The job needs sign-in and a paid plan. | Sign in to KwaFlux and check your plan. |
app_busy | Too many jobs were started in a short time. | Wait a minute, then ask again. |
input_not_local | The path starts with two slashes, like \\server\share, or is a web address. | Copy the file to a local folder and give its full path. |
model_not_installed | That feature's AI model isn't on this computer yet. | Open the feature in KwaFlux and download its model, or go to Settings › Models & Storage. |
agent_download_disabled | Agent downloads are still off. | Choose Ask every time under Agent access, if you want them. |
user_declined, approval_expired | You refused the download, or the popup went unanswered for 120 seconds. | Ask again when you're at the computer. |
Every job an agent queues also shows a short notice that names the host, for example "Codex queued a task". The job appears in Task Center next to your own. If you think the access token has leaked, click Reset agent access token at the end of the connection line. Current connections drop, and the hosts you set up reconnect with the new token on their next call.
Try It on Your Own Footage
Download KwaFlux and preview effects on your own footage for free before you pay. No account needed. Your media is processed on your GPU, not uploaded for processing. Video previews run 1, 3, or 5 seconds; stabilization previews run 5, 15, or 30 seconds.
Frequently asked questions
Can I control KwaFlux from Claude, Cursor, or another AI assistant?
Yes. KwaFlux includes a local MCP server that runs over stdio, so clients such as Codex, Claude, and Cursor can drive it. Keep KwaFlux running, copy the config from Settings → Advanced → Agent (MCP) into the AI app, and install Node.js 18 or newer. The AI app uses Node.js to start the server.
Why is there no Authenticate button for KwaFlux?
Because the KwaFlux MCP server runs locally over stdio, not at a remote URL, so there is no OAuth step.
Can the agent export or convert in KwaFlux for free?
No, KwaFlux needs sign-in and a paid plan to convert, repair, enhance, or download through MCP. The free 1s/3s/5s previews stay in the desktop app.
Can the agent start downloads in KwaFlux?
Yes, once you set Let agents start downloads to Ask every time. KwaFlux then asks you in a popup before each download, and the assistant can't approve it for you.
Why did KwaFlux turn down my file path?
Paths have to be full paths on this computer, like C:\Videos\clip.mp4 or /Users/you/Movies/clip.mp4. A relative path fails. So does one that starts with two slashes, such as \\server\share\clip.mp4. KwaFlux refuses that kind before opening anything, because on Windows even checking the file can start a sign-in handshake with that server. Copy the file to a local folder first.
How can I see what the agent did in KwaFlux?
In KwaFlux, open Settings › General › Agent access and look at Recent agent actions. Each line shows the time, the host, the call, and the result. Jobs the agent queued also sit in Task Center, and each one came with a notice naming the host.
Can Cursor Cloud Agents use a local MCP server?
No. A local stdio server is a program on your computer. Cloud Agents run on Cursor's infrastructure, so they can't start it. Use the agent in the Cursor desktop app on the same computer.
Why do Windows paths need double backslashes in mcp.json?
Because JSON treats a backslash as the start of an escape sequence. C:\\Program Files is valid JSON for C:\Program Files. A single backslash makes the file fail to parse. Forward slashes also work.
Why doesn't Claude Desktop see a new MCP server?
Usually because it's still running in the background. Close the window and quit from the system tray or menu bar, then reopen it. Invalid JSON, such as a single backslash in a Windows path, is the next thing to check.
Will Claude Code on the web see my local KwaFlux?
No. KwaFlux's server is a local program the host starts on your computer. Cloud sessions load project .mcp.json for remote servers, not a Node process next to KwaFlux. Use Claude Code or Claude Desktop on the same machine where the app is open.
What is tool_timeout_sec in Codex?
It's how long Codex waits for one MCP tool call before giving up, 60 seconds by default. Raise it for servers whose tools can block longer, such as a tool that waits for a video export. See how long-running jobs are handled.
Why use single quotes for Windows paths in config.toml?
Because single-quoted TOML strings are literal: backslashes stay as they are. In double-quoted strings, a backslash starts an escape, so C:\Program Files would need C:\\Program Files.
Do I set up MCP again in the ChatGPT desktop app?
No. OpenAI's MCP page says the ChatGPT desktop app, the CLI, and the IDE extension share the Codex host config. Add KwaFlux once in ~/.codex/config.toml, then open Codex in any of those clients. ChatGPT on the web does not read that file.
Where do I add MCP servers in DeepSeek Harness?
In a cordis.patch.yml file, as an insert row for the @deepseek-ai/dsh-mcp-client plugin. Use a profile's own file for that profile, or the home file ~/.dsh/cordis.patch.yml for every profile.
The patch file was `[]`. Do I append KwaFlux under it?
No, replace the [] with KwaFlux's - insert: block. A file that has both [] and another list item is not valid YAML, and DSH exits with a parse error. A new profile patch often starts as that empty list.
Can an agent on a VPS use a local MCP server on my PC?
No, not a stdio server. A stdio server runs as a child process of the agent, on the same machine. To use one on your PC, run the agent there too. See what an AI agent is for how the parts connect.
Why does an MCP server fail with "node is not recognized"?
Because Node.js isn't installed or isn't on the PATH the host sees. Install it, then quit and restart the host. If that doesn't help, put the full path to node.exe in the server's command.
Why do long MCP tool calls time out?
Because some hosts, such as Codex and DeepSeek Harness, cap a tool call at 60 seconds by default. Some KwaFlux tools are designed to wait longer than that. Raise the host's per-server tool timeout. The job itself usually keeps running.
The host says `env: node: No such file or directory` on a Mac. What now?
The host was probably opened from the Dock or Spotlight, so it doesn't get your Terminal PATH and can't see a Node.js installed with Homebrew or nvm. On a Mac, KwaFlux's launcher runs whichever node is on that PATH. Run which node in Terminal. Then set PATH in the server's env to that folder plus /usr/bin:/bin, for example /opt/homebrew/bin:/usr/bin:/bin. Or start the host from Terminal. More Mac notes: KwaFlux on Mac.
Sources
- Model Context Protocol: What is the Model Context Protocol (MCP)? (accessed 2026-10-11)
- Model Context Protocol specification: Transports (stdio) (accessed 2026-10-11)
- Node.js: Node.js releases (accessed 2026-10-11)
- Model Context Protocol: Connect to local MCP servers (troubleshooting and Claude Desktop logs) (accessed 2026-11-08)
- Claude Code docs: Connect Claude Code to tools via MCP (claude mcp list and server status) (accessed 2026-11-08)
- OpenAI Codex docs: Model Context Protocol (codex mcp list and /mcp) (accessed 2026-11-08)
Related articles
Video Converter
H.264, H.265 and AV1, processed locally
OpenConvert video formats locally without uploads
Convert finished masters locally after enhancement: which codec and container to pick, and why a built-in converter saves an upload.
OpenFile Repair
Video, image, and audio
OpenFile Download
A link you paste
Open

