Add tool support for restarting individual MCP servers

Open 💬 7 comments Opened Oct 8, 2025 by CaliLuke

Summary

Developers who iterate on custom MCP servers need a way to restart a single server without tearing down the entire Codex CLI session. Today Codex spawns MCP servers once during McpConnectionManager::new and never revisits them, so the only option is to stop and relaunch the whole CLI. Exposing a restart capability would keep feedback loops tight when testing server changes.

Proposed design

  1. Persist server configs inside the connection manager. Refactor McpConnectionManager so it retains the original McpServerConfig plus the use_rmcp_client/OAuthCredentialsStoreMode flags. Wrap internal state in shared mutability (Arc<RwLock<…>>) so new helper methods can rebuild clients.
  2. Add a restart_server pathway. Implement restart_server(&self, name: &str) that drops the existing client, respawns it using the stored config (including bearer-token resolution), re-runs list_tools, and updates the qualified tool cache. Return a result that callers can surface to users.
  3. Expose the restart in session APIs. Add Session::restart_mcp_server and surface it through the tool plumbing (e.g., a new handler under core/src/tools/handlers/restart_mcp.rs plus a ToolSpec entry so models can call it). The tool would accept { "server": "my-mcp" } and return a success/error message. Optionally gate it behind an experimental_supported_tools flag.
  4. (Optional) CLI command. If we want manual control, add an mcp restart <name> subcommand mirroring the existing list/get/add/remove operations, calling the same backend helper.

Acceptance criteria

  • Restarting a configured MCP server does not require quitting Codex; the tool/API respawns the child process and refreshes tool listings.
  • Errors (unknown server, restart failure, etc.) bubble back to the agent so users see what went wrong.
  • Documentation calls out the new capability for MCP authors.

Happy to help refine or prototype once we have consensus.

View original on GitHub ↗

7 Comments

aehlke · 8 months ago

This is a pain point!

aehlke · 8 months ago

Sorry to bug but @gpeal is this a priority now that you've assigned it? Thanks

yahelroro0196 · 5 months ago

this is so needed! 🙏

swapnilkha · 4 months ago

Any update on this?

gehariharan · 3 months ago

Any update on this issue?

notdenied · 2 months ago

Even built-in MCP server (codex apps) may not start due to network error or anything else. Having a way to restart a concrete server / all servers seems very useful.

Kaexburli · 26 days ago

This would directly solve a real operational case for us.

We have long-running debugging sessions with multiple MCP servers. If one remote MCP endpoint is unavailable at Codex startup and later comes back, the current session can remain stuck with stale/offline tool metadata. Restarting the whole Codex session works, but loses valuable context.

A per-server restart / reload / reconnect command that respawns the MCP transport and refreshes tool listings for the current session would be the right recovery path.