Codex Stuck Loading on Windows? Fix the MCP Path in config.toml

If Codex Desktop on Windows stays on its startup screen after you add or edit an MCP server, check config.toml before reinstalling the app. A Windows path inside a TOML double-quoted string must use escaped backslashes, forward slashes, or a TOML literal string. One unescaped path such as F:\project\server.ps1 can make the entire file fail to parse and keep the app waiting at startup.

Quit Codex, back up the affected configuration file, correct only the malformed path, run codex mcp list if the CLI is installed, and reopen the app. Do not delete ~/.codex, reset the app, or remove your repositories.

Match the Exact Startup Failure

Use this guide when the failure begins after an MCP configuration change and the app never reaches its normal task view.

The August 8 report that defines this failure showed:

failed to reload config: C:\Users\<user>\.codex\config.toml:150:77:
missing escaped value, expected `b`, `e`, `f`, `n`, `r`, `\`, `"`, `x`, `u`, `U`

That exact parser error is stronger evidence than a generic loading screen. If Codex was already running and active tasks remain alive, treat that as a window-versus-task recovery instead of a fresh-start configuration failure. If the configuration parses but an MCP server says startup interrupted, follow the MCP startup diagnostic.

Why the Backslash Breaks TOML

Codex stores user-level configuration in ~/.codex/config.toml. Trusted projects can also add .codex/config.toml, and profiles can add another configuration layer. The desktop app, CLI, and IDE extension share these settings, so one invalid user-level MCP entry can affect more than one Codex surface.

TOML has two relevant single-line string forms:

• Double-quoted basic strings interpret backslash escapes such as \n, \t, and \\.

• Single-quoted literal strings preserve backslashes as written.

This MCP argument is invalid TOML:

[mcp_servers.local_agent]
command = "powershell"
args = ["-NoLogo", "-File", "F:\project\local-agent\start.ps1"]

Inside a double-quoted string, \p and \l are not valid TOML escapes. Other path fragments can be more deceptive: \t and \n are valid escapes, but they become a tab or newline instead of a literal backslash plus letter. A file can therefore fail visibly or parse into the wrong value depending on the directory name.

This is a configuration syntax boundary. Reinstalling Codex does not necessarily replace a user-owned config.toml, which is why reinstalling can leave the loading screen unchanged.

Step 1: Stop and Back Up the Right File

Close Codex normally before editing shared configuration. If another Codex surface is actively changing MCP settings, finish that change first so two processes do not overwrite each other.

For the default user-level file, open PowerShell and create a backup:

$Config = Join-Path $HOME ".codex\config.toml"
Copy-Item $Config "$Config.before-mcp-path-fix"
notepad $Config

If you set CODEX_HOME, use its config.toml instead:

$Config = Join-Path $env:CODEX_HOME "config.toml"
Copy-Item $Config "$Config.before-mcp-path-fix"
notepad $Config

The reported error includes a line and column. Go to that location and inspect the surrounding MCP table. If the user-level file is valid, check the trusted project's .codex/config.toml and the selected profile file next, following Codex's documented configuration precedence.

Do not paste the complete file into a public issue or an agent prompt. MCP tables can contain environment names, private URLs, headers, tokens, and local paths. Share only a sanitized error and the smallest affected block.

Step 2: Correct One Path With a Valid TOML Form

Choose one representation and change only the malformed path.

Option A: Use a TOML literal string

For a normal Windows path, single quotes are the clearest repair:

[mcp_servers.local_agent]
command = "powershell"
args = ["-NoLogo", "-File", 'F:\project\local-agent\start.ps1']

The single quotes belong to TOML. They are not passed to PowerShell as part of the path. Use another form if the path itself contains a single quote.

Option B: Use forward slashes

The original report confirmed that this form restored startup:

args = ["-NoLogo", "-File", "F:/project/local-agent/start.ps1"]

Use this only when the invoked program accepts a Windows path with forward slashes. The reported PowerShell -File case did.

Option C: Escape every backslash

Keep double quotes and write each literal backslash twice:

args = ["-NoLogo", "-File", "F:\\project\\local-agent\\start.ps1"]

Do not mix escaped and unescaped separators in the same path. A single missed backslash can preserve the failure or silently create a control character.

Step 3: Validate Before Reopening the Desktop App

Save the file, then run this read-only check if the Codex CLI is installed:

codex mcp list

The expected result is a list of configured MCP servers, not a TOML parse error. OpenAI documents codex mcp list as the supported command for viewing configured servers.

Then reopen Codex Desktop and verify:

1. The app reaches the normal project and task view.

2. Settings can display the MCP server list.

3. The repaired server appears with the expected command and arguments.

4. A harmless read-only call to that server succeeds, or it returns a server-specific startup error instead of a configuration parse error.

5. Unrelated MCP servers and Codex settings remain present.

A later authentication, executable, or server timeout error is progress: it means TOML parsing succeeded and the failure moved to the actual MCP server boundary. Diagnose that new error separately rather than editing more configuration at once.

If the App Still Hangs

Restore the distinction between syntax and runtime failures before changing anything else.

• If codex mcp list still reports a line and column, inspect that exact location for another invalid string.

• If the line moved, fix the next parser error one at a time.

• If the CLI reads the file but Desktop still hangs, restart Windows once and collect the app version plus a sanitized timestamped error.

• If the failure happens only inside one trusted project, compare its .codex/config.toml with the user-level file.

• If the MCP server is marked required = true and configuration parses, a server initialization failure can block startup or resume by design. Test the server boundary rather than changing TOML quoting again.

Do not add enabled = false beside a malformed string and expect the parser to skip it. TOML must parse the whole file before Codex can apply the enabled setting.

Avoid Broad Resets

For this exact failure, do not:

• delete the entire .codex directory;

• erase task history, credentials, or plugin state;

• reset or reinstall the desktop app before checking the shared file;

• delete every MCP server block;

• rename a repository or move its files;

• disable the Windows sandbox;

• publish a complete configuration file or log containing secrets.

The narrow recovery is one backup, one syntax correction, one parser check, and one app restart.

Monitor the Upstream Issue With Aident Loadout

Start with the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then give your agent a bounded, read-only check:

Check Aident Loadout authentication and Vault status. Discover the current GitHub issue-read and web-search Actions, inspect their schemas, and preflight them. If the estimates are within the configured approval limit, read openai/codex issue 37616 and the current official Codex configuration and MCP documentation. Return the issue state, last update, linked fix or release if one exists, and the source URLs. Do not create, edit, label, close, comment on, or react to issues, and do not include local configuration values.

Set up Aident Loadout and monitor the Codex Windows path bug read-only.

Success is measurable: the configuration parses, Codex Desktop reaches its task view, the intended MCP server remains configured, and the monitoring check returns current evidence without a provider write.

Sources

• Codex issue 37616: MCP Windows path causes a TOML startup failure

• OpenAI Codex configuration basics

• OpenAI Codex MCP configuration

• OpenAI Codex configuration reference

• TOML 1.0.0 string specification

Refresh this guide when issue 37616 changes state, Codex gains a startup fallback for invalid configuration, the desktop app reports the parser location directly, or official MCP path guidance changes.