Codex Says Invalid Transport in mcp_servers.codex_app? Fix It Safely

If Codex Desktop says invalid transport in mcp_servers.codex_app even though that table is absent from your config.toml, do not invent the missing entry or delete your Codex state. Update Codex Desktop through its supported channel, fully quit it, reopen it, and test one new conversation before changing configuration.

OpenAI issue 40860 tracked this exact regression across macOS and Windows with WSL. The issue closed as completed on August 28, 2026, and a reporter confirmed that a newer app version restored access to projects and conversations. On multi-user macOS systems, several reporters also isolated a temporary-directory permission collision and verified a narrow workaround. The same visible error on Windows or WSL did not have the same confirmed cause.

This guide separates those branches so you do not repair the wrong layer.

Match the exact error first

Use this guide when Codex Desktop blocks a new or existing conversation with wording like:

ChatGPT can't load config.toml, so this thread can't resume.
Fix config.toml: invalid transport in `mcp_servers.codex_app`

Then check whether codex_app is actually present in the user configuration:

grep -n -C 3 'codex_app' ~/.codex/config.toml

An empty result matters. In the tracked incident, users reported no [mcp_servers.codex_app] table in their file, while Codex still named it. That points away from a user-authored TOML entry and toward an app-managed internal transport.

Do not treat the shared word transport as proof that these failures have the same root cause.

1. Update before editing configuration

Reports on issue 40860 began August 26. The final public report said a newer version fixed the issue, but the issue did not identify one universal affected or fixed build for every platform.

Use the app's supported update path. Then:

1. Fully quit Codex Desktop, not just the affected conversation.

2. Reopen the app.

3. Confirm the installed version in the About dialog.

4. Create one disposable conversation.

5. Reopen one existing conversation.

If both work, stop. Do not edit config.toml after the symptom is gone.

If the update path is unavailable, record the app version, operating system, execution environment, and exact timestamp before continuing. Those facts are more useful than a broad reinstall or state reset.

2. Prove whether the failure is user configuration or app-managed state

Back up the file before inspecting it:

cp ~/.codex/config.toml ~/.codex/config.toml.before-codex-app-check

Then use read-only checks:

grep -n -C 3 'codex_app' ~/.codex/config.toml
codex mcp list

Interpret the results carefully:

• If the table is absent and codex mcp list can read the rest of the file, do not add a guessed command, url, or transport.

• If Codex reports a real TOML line and column, inspect that exact location and follow the configuration syntax branch.

• If a user-authored [mcp_servers.codex_app] table exists, confirm why it exists before changing it. The tracked regression concerned an app-managed entry that users could not find in their file.

Do not publish the complete configuration in an issue. MCP configuration can contain local paths, private endpoints, headers, and environment names.

3. On macOS, check the native-pipe error before changing permissions

The strongest macOS diagnosis came from a two-user A/B test. Codex used the machine-global directory /tmp/codex-browser-use for internal Unix sockets. On macOS, /tmp normally resolves to /private/tmp, so the log path and the inspection path below refer to the same location. User A created the directory with mode 0755; user B could read and traverse it but could not create a socket. The useful log line appeared before the misleading transport message:

Failed to start the Codex app tools native pipe
listen EACCES: permission denied /tmp/codex-browser-use/<uuid>

Check the directory without changing it:

ls -ldeO@ /private/tmp/codex-browser-use
stat -f '%N owner=%Su group=%Sg mode=%Sp' /private/tmp/codex-browser-use
readlink /tmp
test -d /private/tmp/codex-browser-use && test ! -L /private/tmp/codex-browser-use
id

This branch matches only when all of these are true:

• the host is macOS and /tmp resolves to /private/tmp as expected;

• the directory is owned by another operating-system user;

• its mode prevents the current user from creating a socket;

• the logs show the corresponding EACCES native-pipe failure;

• the path is a real directory rather than a symbolic link or another planted filesystem node;

• the app update did not already resolve the problem.

If any condition is missing, stop and collect evidence instead of changing permissions.

4. Apply the narrow macOS workaround only when the evidence matches

Multiple reporters confirmed this non-recursive workaround:

sudo chmod 1777 /private/tmp/codex-browser-use

Mode 1777 is the sticky-directory pattern used for shared temporary directories. It lets users create their own entries while preventing them from deleting entries owned by another user.
It does not stop another local user from pre-creating a name, so keep the path and no-symbolic-link checks below and treat this as a narrow recovery, not a general isolation boundary.

Prefer a lower-privilege recovery when the owner is available: fully quit Codex for every logged-in user, have the directory owner remove the app-created directory only if it is empty and no Codex process is using it, then let the affected user restart Codex and recreate it. If the directory is nonempty, is a symbolic link, has unexpected extended attributes, or cannot be tied to Codex, do not remove it or change its mode. Preserve the evidence for the upstream report.

Important boundaries:

• Use the exact directory path. Do not add -R.

• Confirm test -d succeeds and test ! -L succeeds before running chmod.

• Do not run this on native Windows.

• Do not run it merely because the final error mentions codex_app.

• Do not change ownership of broader temporary, Codex, or home directories.

• Fully quit and restart Codex after the change.

Then verify one new conversation and one existing conversation. If the original native-pipe EACCES is gone but Codex still fails, preserve the new log and stop repeating permission changes.

The upstream design should use a per-user socket directory or validate the shared directory safely. A local workaround is not evidence that world-writable application state should become the permanent architecture.

5. Keep Windows and WSL separate

Windows and WSL users reported the same visible invalid transport message, but issue 40860 did not establish the macOS /tmp directory as their cause. A Windows named pipe and a Unix socket are different boundaries.

On Windows or WSL:

1. Update Codex Desktop and restart it completely.

2. Record whether the selected Agent Environment is Windows Native or WSL.

3. Confirm the Desktop and bundled CLI versions.

4. Check the first error before invalid transport in the Desktop logs.

5. Verify whether a new conversation and an existing conversation fail in the same way.

Do not translate the macOS chmod command into a Windows ACL change without a platform-specific upstream diagnosis. Do not switch environments, delete .codex, regenerate plugin caches, or hand-author an internal MCP server just to make the secondary error disappear.

6. Know when this is a different MCP problem

Three nearby guides own different failures:

• If a Windows path inside a real MCP table breaks TOML parsing, use Codex Stuck Loading on Windows? Fix the MCP Path in config.toml.

• If a long tool call later fails with the aws-lc-rs signature, use Codex MCP Transport Closed After 90 Seconds? Recover Safely.

• If the configuration parses but one server reports an interrupted startup, use Codex MCP Startup Interrupted but Connected? Diagnose It.

The right recovery begins with the earliest specific error, not the last generic one.

Monitor the upstream issue with Aident Loadout

Aident Loadout can check the current issue and official release evidence without giving the agent permission to change GitHub.

Start with:

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

Then ask:

Check Aident Loadout account authentication and Vault status. Search the current capability catalog for the GitHub issue-read Action, inspect its schema, and preflight a request for openai/codex issue 40860. If the request is valid and free, return the issue state, state reason, updated time, labels, title, latest maintainer or reporter resolution evidence, and canonical URL. Distinguish macOS, Windows Native, and WSL evidence. Do not comment, react, edit, label, close, create, or otherwise write to GitHub. Do not read or reveal local configuration values.

Success is measurable: Codex Desktop opens new and existing conversations, the internal pipe starts without the matching native-pipe error, and the monitoring receipt shows a bounded GitHub read with no provider write.

Set up Aident Loadout and monitor the Codex transport fix

Sources

• OpenAI Codex issue 40860: invalid transport in mcp_servers.codex_app, reviewed September 1, 2026.

• OpenAI Codex configuration basics, reviewed September 1, 2026.

• OpenAI Codex MCP documentation, reviewed September 1, 2026.

• OpenAI Codex configuration reference, reviewed September 1, 2026.

Refresh this guide when issue 40860 changes state, OpenAI names the fixed release, Codex moves internal sockets to a per-user directory, the Windows or WSL root cause is confirmed, or official configuration and MCP guidance changes.