codex mcp list && codex mcp --help
Follow a practical setup path, understand the permission boundary and leave with a configuration you can review and adapt.
Check the configuration entry first
Begin by confirming that Codex can see the expected server entry. A typo in the server name, command, URL or configuration table can look like a server failure.
codex mcp list
codex mcp --helpSeparate startup from tool discovery
A server may start but expose no usable tools, or it may fail before initialisation. Test the launch command when appropriate, then inspect active tools from inside the Codex terminal interface.
- Command not found: verify the executable and PATH.
- Startup timeout: inspect the server before raising limits.
- No tools: confirm that the server exposes tools for the transport.
- Authentication required: complete the supported login flow.
Check environment variables safely
Local servers often rely on tokens or settings from the environment that launches Codex. Confirm that variable names match the configuration without printing secret values.
Reduce the setup
Temporarily disable unrelated servers and test one connection. A smaller configuration makes naming conflicts, timeouts and overlapping tools easier to diagnose.
Do not solve an authentication error by placing a live secret directly in a repository file.
Download this guide’s configuration.
Review the endpoint, package, credentials and permission settings before using it in a trusted environment.
Frequently asked questions
The server may not expose tools for the selected transport, authentication may be incomplete or initialization may not have finished correctly.
First inspect the server command, logs and dependencies. Increase the timeout only when the server is healthy but genuinely needs more time.
Provider endpoints, authentication requirements and supported options can change. Confirm current details before connecting a sensitive service.