Terminate stdio MCP servers on shutdown to avoid process leaks (#19753)

## Why

Several bug reports describe thread shutdown (including subagent
threads) leaving stdio MCP server processes behind. These reports all
point at the same lifecycle gap: Codex launches stdio MCP servers, but
the session-level shutdown path does not explicitly close MCP clients or
terminate the server process tree.

Fixes #12491
Fixes #12976
Fixes #18881
Fixes #19469

## History

This is best understood as a regression/coverage gap in MCP session
lifecycle management, not as stdio MCP cleanup being absent all along.
#10710 added process-group cleanup for stdio MCP servers, but that
cleanup only runs when the `RmcpClient`/transport is dropped. The older
reports (#12491 and #12976) came after that cleanup existed, which
suggests the remaining problem was that some higher-level shutdown paths
kept the MCP manager alive or replaced it without explicitly draining
clients. The newer reports (#18881 and #19469) exposed the same family
around manager replacement and shutdown.

## What changed

- Added an explicit stdio MCP process handle in `codex-rmcp-client` so
local MCP servers terminate their process group and executor-backed MCP
servers call the executor process terminator.
- Added `RmcpClient::shutdown()` and manager-level MCP shutdown draining
so session shutdown, channel-close fallback, MCP refresh, and connector
probing stop owned MCP clients.
- Added regression coverage that starts a stdio MCP server, begins an
in-flight blocking tool call, shuts down the client, and asserts the
server process exits.

## Verification

- `cargo test -p codex-rmcp-client`
- `cargo test -p codex-mcp`
- `just fix -p codex-rmcp-client`
- `just fix -p codex-mcp`
- `just fix -p codex-core`

- Manual before/after validation with a temporary repro script:
- Pre-fix binary from `HEAD^` (`fed0a8f4fa`): reproduced the leak with
surviving MCP server and child PIDs, `survivors=[77583, 77592]`,
`leaked=true`.
- Post-fix binary from this branch (`67e318148b`): verified both MCP
processes were gone after interrupting `codex exec`, `survivors=[]`,
`leaked=false`.
This commit is contained in:
Eric Traut authored and GitHub committed 2026-04-28 09:29:57 -07:00
1 parent 087c9c1f1f
commit 4e0cf945b7
10 files changed
+356 -32

No files matched your search

@@ -71,6 +71,7 @@ pub struct McpConnectionManager {
clients: HashMap<String, AsyncManagedClient>,
server_origins: HashMap<String, String>,
elicitation_requests: ElicitationRequestManager,
startup_cancellation_token: CancellationToken,
}
impl McpConnectionManager {
@@ -85,6 +86,7 @@ impl McpConnectionManager {
approval_policy.value(),
permission_profile.get().clone(),
),
startup_cancellation_token: CancellationToken::new(),
}
}
@@ -92,6 +94,24 @@ impl McpConnectionManager {
!self.clients.is_empty()
}
/// Drain all MCP clients from this manager and return a future that stops
/// them and terminates their stdio server processes.
pub fn begin_shutdown(&mut self) -> impl std::future::Future<Output = ()> + Send + 'static {
self.startup_cancellation_token.cancel();
let clients = std::mem::take(&mut self.clients);
self.server_origins.clear();
async move {
for client in clients.into_values() {
client.shutdown().await;
}
}
}
/// Stop all MCP clients owned by this manager and terminate stdio server processes.
pub async fn shutdown(&mut self) {
self.begin_shutdown().await;
}
pub fn server_origin(&self, server_name: &str) -> Option<&str> {
self.server_origins.get(server_name).map(String::as_str)
}
@@ -221,6 +241,7 @@ impl McpConnectionManager {
clients,
server_origins,
elicitation_requests: elicitation_requests.clone(),
startup_cancellation_token: cancel_token.clone(),
};
tokio::spawn(async move {
let outcomes = join_set.join_all().await;
@@ -609,6 +630,13 @@ impl McpConnectionManager {
}
}
impl Drop for McpConnectionManager {
fn drop(&mut self) {
self.startup_cancellation_token.cancel();
self.clients.clear();
}
}
async fn emit_update(
submit_id: &str,
tx_event: &Sender<Event>,