MCP connection diagnosis and recovery

Back to the Codex learning hub

Goal and preparation

Lessons and resources mentioned here: MCP setup

Step 1: Inspect configuration before changing timeouts

codex --version
codex mcp get codexLearningDocs
codex mcp list

Check the name, enabled state, transport and URL. Record whether this is a local or remote host, CLI or desktop, and the last restart. If get cannot find the name, inspect the actual config.toml, spelling, user/project scope and custom CODEX_HOME. Desktop, CLI and IDE share settings only on the same Codex host; native Windows and WSL home directories are not interchangeable.

For a parse error, fix quotes, duplicate tables or incorrect value types near the reported line before investigating networking. Preserve a before-copy as described in Configuration and edit only the practice section, keeping the full settings private. If parsing succeeds but the entry is missing, check trusted-project loading, working directory and whether the editor saved the actual file rather than a backup.

Mark authentication not required for a public server that needs none; it is not a skipped login.

Step 2: Reproduce a disabled tool catalog

Obtain a normal read with the previous lesson's question and save the configuration. Change an existing enabled value to false; add enabled = false once only when the key is absent, never duplicating the key or table. Use Restart in desktop MCP settings, restart the IDE extension, or open a fresh CLI session. Merely asking again in the old conversation can reuse earlier content. This exercise deliberately disables your entry; it does not indicate a remote service outage.

[mcp_servers.codexLearningDocs]
url = "https://developers.openai.com/mcp"
enabled = false

/mcp

Use /mcp in the Codex composer on desktop, CLI or IDE; it is not a shell command. After restarting, confirm disabling in a fresh task/session with /mcp, MCP servers settings and actual tool activity. Record that the client did not expose the tool. If you compare surfaces, record each host and configuration location.

The new session should not expose tools from the disabled server, even though get still lists its configuration. Set enabled to true or remove the added false value, restart, then query and verify the official source again. Preserve all three states—normal, disabled and restored—because a final success screenshot alone does not demonstrate that the failure exercise took effect.

Step 3: Separate STDIO startup and HTTP connection

For another STDIO server, inspect command, args and cwd first. Use Get-Command on Windows or command -v on macOS/Linux. This proves the current terminal resolves the program, not that a desktop-launched process inherits the same PATH. Relative paths depend on the working directory; fix missing paths first and check Node versions for servers that require Node.js. A misspelled filename is not repaired by a longer startup timeout.

Get-Command node
node --version

command -v node
node --version

STDIO uses standard input/output for protocol messages, so extra greeting or debug output can interfere. If you maintain the server, follow its official implementation and direct ordinary logs to stderr. Otherwise, report startup evidence to the provider rather than editing third-party package internals. A manually started process waiting silently for input is not necessarily hung, and a live process does not prove MCP initialization.

For HTTP, check scheme, host and full path, including the official /mcp endpoint here. A browser opening the homepage proves only partial reachability, not a successful MCP request, proxy setup or authentication. For TLS errors, inspect system time, organizational proxy and certificate trust with the environment maintainer; disabling certificate checks is not the default repair. Record time and a redacted error before retrying a temporary failure.

Step 4: Authentication, tool filters and timeouts

For an OAuth service, choose Authenticate or inspect codex mcp login --help before logging in with your server name. Account, scopes and callback requirements depend on the provider. If a preregistered client ID is required, register the complete callback displayed by Codex rather than guessing a port or swapping localhost and 127.0.0.1. This login exercise does not apply to the public Docs MCP.

When authentication succeeds but a tool is missing, inspect enabled_tools, disabled_tools and plugin policy. An allow list cannot create a capability the server does not offer, and the deny list applies after the allow list. Get real tool names from the current catalog rather than guessing search or read. Plugin-provided servers have plugin-scoped settings; user configuration does not replace their launch commands. See Plugin troubleshooting.

Startup and tool timeouts apply to different stages: startup_timeout_sec covers initialization and tool_timeout_sec covers an invocation. Verify program, URL and authentication, then try a smaller read to distinguish oversized work. Adjust one server's timeout only when normal work demonstrably needs more time and retest. Optional startup grace and required also affect startup behavior; making every server required is unnecessary. Preserve failures and stop dependent work when an essential service is unavailable.

Finish with a reproducible incident record

# MCP recovery record
Surface / OS / client version:
Host and effective config location (redacted):
Server name / transport:
Failure layer:
Original error (without secrets):
Single change:
New-session tool visibility:
Read-only request and verified source:
Normal / disabled / restored results:
Unrelated settings preserved:
Remaining limitation and next action:

If the exercise breaks configuration, restore its section and recheck instead of replacing the whole file while another task may be editing it. Remove your added codexLearningDocs as in the previous lesson. For OAuth services, logout clears saved authentication and remove deletes configuration; inspect the provider account for remaining grants. Neither reverses data already written to an external system, which needs that provider's recovery process.

Completion means identifying the failing layer, reproducing disable/restore and obtaining fresh read-only tool evidence. A process, file or correct answer alone is insufficient. If connection remains unavailable, mark tool verification incomplete. Product steps follow official documentation, with local configuration and direct MCP checks recorded separately; those do not establish macOS, Linux, IDE, OAuth or physical-phone testing. Continue to Worktree isolation.

Back to the Codex learning hub

Read the full description

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI tools
• Tutorials
• Codex