Codex RescueCodex troubleshooting

Codex MCP & configuration troubleshooting

Fix Codex MCP startup failures, missing tools and invalid config.toml errors. Find configuration locations and check server setup step by step.

A missing MCP tool is not always a failed server. Configuration syntax, file location and startup errors require different checks. These guides help you establish which configuration Codex reads and where the connection fails.

MCP and configuration failures need a precise boundary: did Codex fail to parse its own config file, fail to start a configured server, or start the server without showing tools in the active session? Those stages lead to different checks. Start with the config path used by the current CLI, desktop app or extension; Windows and WSL homes should not be conflated. When the parser gives a line and column, fix that document first. A correct TOML file still cannot guarantee that an external MCP server starts, authenticates or exposes tools.

The complete guide list below covers syntax, file location, server startup, missing tools and a removed server. Choose by the exact message or last known successful stage. Back up configuration before editing it, and avoid posting secrets from environment variables or provider settings. After a targeted edit, restart or refresh only the client that needs to reread the configuration, then confirm the intended tool rather than relying on the absence of an error banner.

What to check first

  • Locate the configuration used by the current Codex client.
  • Check syntax before changing server settings.
  • Distinguish startup failures from tools that need a refreshed session.

MCP & Configuration troubleshooting guides

Back to all Codex error messages →

Reached a usage limit instead? Check Codex usage limits and reset times.

Last updated: