Fix child process cleanup in stdio termination

When terminating MCP servers, child processes were being orphaned
because only the parent process was killed. This caused resource
leaks and prevented proper cleanup, especially with tools like npx
that spawn child processes for the actual server implementation.

This was happening on both POSIX and Windows systems - however
because of implementation details, resolving this is non-trivial
and requires introducing psutil to introduce cross-platform
utilities for dealing with children and process trees.

This addresses critical issues where MCP servers using process
spawning tools would leave zombie processes running after client
shutdown.

resolves #850
resolves #729

Author: felixweinberger

pyproject.toml

@@ -32,6 +32,7 @@ dependencies = [
     "pydantic-settings>=2.5.2",
     "uvicorn>=0.23.1; sys_platform != 'emscripten'",
     "jsonschema>=4.20.0",
+    "psutil>=5.9.0,<6.0.0",
 ]
 
 [project.optional-dependencies]
@@ -110,6 +111,9 @@ members = ["examples/servers/*"]
 [tool.uv.sources]
 mcp = { workspace = true }
 
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+
 [tool.pytest.ini_options]
 log_cli = true
 xfail_strict = true

src/mcp/client/stdio/__init__.py

@@ -6,6 +6,9 @@
 
 import anyio
 import anyio.lowlevel
+import anyio.to_thread
+import psutil
+from anyio.abc import Process
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from anyio.streams.text import TextReceiveStream
 from pydantic import BaseModel, Field
@@ -14,6 +17,7 @@
 from mcp.shared.message import SessionMessage
 
 from .win32 import (
+    FallbackProcess,
     create_windows_process,
     get_windows_executable_command,
 )
@@ -180,7 +184,7 @@ async def stdin_writer():
             # MCP spec: stdio shutdown sequence
             # 1. Close input stream to server
             # 2. Wait for server to exit, or send SIGTERM if it doesn't exit in time
-            # 3. Send SIGKILL if still not exited
+            # 3. Send SIGKILL if still not exited (forcibly kill on Windows)
             if process.stdin:
                 try:
                     await process.stdin.aclose()
@@ -193,18 +197,9 @@ async def stdin_writer():
                 with anyio.fail_after(2.0):
                     await process.wait()
             except TimeoutError:
-                # Process didn't exit from stdin closure, escalate to SIGTERM
-                try:
-                    process.terminate()
-                    with anyio.fail_after(2.0):
-                        await process.wait()
-                except TimeoutError:
-                    # Process didn't respond to SIGTERM, force kill it
-                    process.kill()
-                    await process.wait()
-                except ProcessLookupError:
-                    # Process already exited, which is fine
-                    pass
+                # Process didn't exit from stdin closure, use our termination function
+                # that handles child processes properly
+                await _terminate_process_with_children(process)
             except ProcessLookupError:
                 # Process already exited, which is fine
                 pass
@@ -245,6 +240,70 @@ async def _create_platform_compatible_process(
     if sys.platform == "win32":
         process = await create_windows_process(command, args, env, errlog, cwd)
     else:
-        process = await anyio.open_process([command, *args], env=env, stderr=errlog, cwd=cwd)
+        process = await anyio.open_process(
+            [command, *args],
+            env=env,
+            stderr=errlog,
+            cwd=cwd,
+            start_new_session=True,
+        )
 
     return process
+
+
+async def _terminate_process_with_children(process: Process | FallbackProcess, timeout: float = 2.0) -> None:
+    """
+    Terminate a process and all its children using psutil.
+
+    This provides consistent behavior across platforms and properly
+    handles process trees without shell commands.
+
+    Platform behavior:
+    - On Unix: psutil.terminate() sends SIGTERM, allowing graceful shutdown
+    - On Windows: psutil.terminate() calls TerminateProcess() which is immediate
+      and doesn't allow cleanup handlers to run. This can cause ResourceWarnings
+      for subprocess.Popen objects that don't get to clean up.
+    """
+    pid = getattr(process, "pid", None)
+    if pid is None:
+        popen = getattr(process, "popen", None)
+        if popen:
+            pid = getattr(popen, "pid", None)
+
+    if not pid:
+        # Process has no PID, cannot terminate
+        return
+
+    try:
+        parent = psutil.Process(pid)
+        children = parent.children(recursive=True)
+
+        # First, try graceful termination for all children
+        for child in children:
+            try:
+                child.terminate()
+            except psutil.NoSuchProcess:
+                pass
+
+        # Then, also terminate the parent process
+        try:
+            parent.terminate()
+        except psutil.NoSuchProcess:
+            return
+
+        # Wait for processes to exit gracefully, force kill any that remain
+        all_procs = children + [parent]
+        _, alive = await anyio.to_thread.run_sync(lambda: psutil.wait_procs(all_procs, timeout=timeout))
+        for proc in alive:
+            try:
+                proc.kill()
+            except psutil.NoSuchProcess:
+                pass
+
+        # Wait a bit more for force-killed processes
+        if alive:
+            await anyio.to_thread.run_sync(lambda: psutil.wait_procs(alive, timeout=0.5))
+
+    except psutil.NoSuchProcess:
+        # Process already terminated
+        pass

src/mcp/client/stdio/win32.py

@@ -115,6 +115,11 @@ def kill(self) -> None:
         """Kill the subprocess immediately (alias for terminate)."""
         self.terminate()
 
+    @property
+    def pid(self) -> int:
+        """Return the process ID."""
+        return self.popen.pid
+
 
 # ------------------------
 # Updated function