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
- Persist server configs inside the connection manager. Refactor
McpConnectionManagerso it retains the originalMcpServerConfigplus theuse_rmcp_client/OAuthCredentialsStoreModeflags. Wrap internal state in shared mutability (Arc<RwLock<…>>) so new helper methods can rebuild clients. - Add a
restart_serverpathway. Implementrestart_server(&self, name: &str)that drops the existing client, respawns it using the stored config (including bearer-token resolution), re-runslist_tools, and updates the qualified tool cache. Return a result that callers can surface to users. - Expose the restart in session APIs. Add
Session::restart_mcp_serverand surface it through the tool plumbing (e.g., a new handler undercore/src/tools/handlers/restart_mcp.rsplus aToolSpecentry so models can call it). The tool would accept{ "server": "my-mcp" }and return a success/error message. Optionally gate it behind anexperimental_supported_toolsflag. - (Optional) CLI command. If we want manual control, add an
mcp restart <name>subcommand mirroring the existinglist/get/add/removeoperations, 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.
7 Comments
This is a pain point!
Sorry to bug but @gpeal is this a priority now that you've assigned it? Thanks
this is so needed! 🙏
Any update on this?
Any update on this issue?
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.
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/reconnectcommand that respawns the MCP transport and refreshes tool listings for the current session would be the right recovery path.