How to Use KwaFlux from Codex: MCP Setup, Timeouts, and Approvals

Key takeaways

• Codex connects to KwaFlux with one codex mcp add command, or a [mcp_servers.kwaflux] table in ~/.codex/config.toml. KwaFlux generates both.
• Codex gives an MCP tool call 60 seconds by default, and KwaFlux's wait tool can wait up to 300. Set tool_timeout_sec higher, so long video jobs aren't cut off.
• The command line doesn't add the 20-second startup timeout that KwaFlux's TOML includes. Add it if the server is slow to start.
• Codex's approval modes let you run read-only KwaFlux tools freely while still asking before jobs that write files.

OpenAI's Codex can drive KwaFlux through the local MCP server that installs with the app. In KwaFlux's Settings, choose Codex and copy either the install command or the TOML table, add it to Codex, and keep KwaFlux open. Two settings are worth changing for video work: the tool timeout and the approval mode.

In this guide, you'll learn both ways to add KwaFlux to Codex, the timeout settings that matter for long jobs, how to control approvals, and what to ask first.

Contents

1. How Codex runs an MCP server
2. Before you start
3. Method 1. codex mcp add
4. Method 2. Edit config.toml
5. Timeouts for long video jobs
6. Approvals and tool lists
7. Your first requests
8. Troubleshooting
9. FAQ

How Codex runs an MCP server

Codex starts each local MCP server listed in its config when a session begins, and talks to it over standard input and output. The server's tools then appear to the model next to Codex's own. The same config is used by the Codex CLI and the Codex desktop app.

KwaFlux's server is a Node.js script installed with the app. It doesn't process anything itself. It passes requests to the running KwaFlux app, which checks them and runs the jobs.

Before you start

• KwaFlux 1.0.14 or later, open.
• Node.js 18 or newer, on PATH. Check with node --version; install the current LTS from nodejs.org if needed. KwaFlux's Settings card also looks for Node.js and writes its full path into the config, as in the examples below; if it can't find Node.js, it says so and writes node instead.
• In KwaFlux: Settings › Agent (MCP), then choose Codex under MCP host.

Method 1. codex mcp add

Click Copy install command and run it in a terminal. For a default Windows install, it's:

codex mcp add kwaflux -- "C:\Program Files\nodejs\node.exe" "C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs"

We ran it with Codex CLI 0.118.0, and it printed Added global MCP server 'kwaflux'. Then check:

codex mcp list

KwaFlux should be listed as enabled. This writes a table to ~/.codex/config.toml with only command and args. Read on for the two lines worth adding by hand.

Method 2. Edit config.toml

Click Copy config instead, and append the table to ~/.codex/config.toml, or to .codex/config.toml in a trusted project:

[mcp_servers.kwaflux]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs']
startup_timeout_sec = 20

As KwaFlux's hint says, "The key is mcp_servers (underscore)." Then restart Codex, or run /mcp in a session to see the server.

Sidenote: The path is in single quotes on purpose. In TOML, single-quoted strings are literal, so Windows backslashes don't need escaping. In double quotes, you'd have to write \\ for each one.

Timeouts for long video jobs

Codex's MCP documentation lists two timeouts per server:

The second one matters most. When Codex asks KwaFlux to wait for an export, the wait tool blocks until the task finishes or its own limit is reached, up to 300 seconds. With Codex's 60-second default, a longer wait is cut off from Codex's side, and the model may treat it as a failure. Set:

[mcp_servers.kwaflux]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs']
startup_timeout_sec = 20
tool_timeout_sec = 330

The task keeps running in KwaFlux either way. A timeout only ends that one wait, and Codex can check the task again.

Approvals and tool lists

Codex lets you choose, per server, when it asks before a tool runs. Its documentation lists auto, prompt, writes, and approve for default_tools_approval_mode, where writes "prompts for tools that aren't marked read-only." That suits KwaFlux: status and task-list calls go through, and jobs that write files still ask.

You can also narrow what Codex loads with enabled_tools, an allow list, or disabled_tools, a deny list. For example, if you only use Codex to convert and repair, list just the task, conversion, and repair tools. Fewer tools also leave more room in the model's context, as our tool design post explains.

Your first requests

Check whether KwaFlux is running, and list my recent KwaFlux tasks.

Then:

Frame interpolation and the matting and replace tools stay in the app; the assistant is told to send you there for those. Agent downloads stay off unless you set Let agents start downloads under Agent access to Ask every time. KwaFlux then shows a popup for each download, and the assistant also asks you to confirm in the chat that you have the right to download that content.

Troubleshooting

For issues common to every host, see the KwaFlux MCP troubleshooting guide.

Final thoughts

Add KwaFlux with the command or the TOML that KwaFlux copies for you, then add two lines: a 20-second startup timeout and a 330-second tool timeout. Pick the writes approval mode if you want Codex to ask only before jobs that create files. Keep KwaFlux open, and start with a status check.

Drive KwaFlux from Codex

KwaFlux includes a local MCP server for Codex 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