fix(mcp): skip MCPClient cleanup during interpreter finalization (#2144)

Co-authored-by: minorun365 <minorun365@users.noreply.github.com>

Author: minorun365

src/strands/tools/mcp/mcp_client.py

@@ -12,6 +12,7 @@
 import contextvars
 import json
 import logging
+import sys
 import threading
 import uuid
 from asyncio import AbstractEventLoop
@@ -343,6 +344,15 @@ def stop(self, exc_type: BaseException | None, exc_val: BaseException | None, ex
         """
         self._log_debug_with_thread("exiting MCPClient context")
 
+        # Skip cleanup during interpreter finalization. On Python 3.14+, joining a
+        # non-daemon thread at shutdown raises PythonFinalizationError; even though
+        # our background thread is a daemon and will be reclaimed automatically,
+        # the join call itself produces noisy tracebacks on stderr when the GC
+        # reaches Agent.__del__ during finalization. See issue #2143.
+        if sys.is_finalizing():
+            self._log_debug_with_thread("interpreter is finalizing, skipping MCPClient cleanup")
+            return
+
         # Only try to signal close future if we have a background thread
         if self._background_thread is not None:
             # Signal close future if event loop exists

tests/strands/tools/mcp/test_mcp_client.py

@@ -594,6 +594,33 @@ def test_stop_closes_event_loop():
     assert client._background_thread_event_loop is None
 
 
+def test_stop_skips_cleanup_during_interpreter_finalization():
+    """Test that stop() is a no-op when the interpreter is finalizing.
+
+    On Python 3.14+, threading.Thread.join() raises PythonFinalizationError at
+    shutdown. The background thread is a daemon and is reclaimed automatically,
+    so stop() should skip join() and event loop cleanup to avoid noisy
+    tracebacks surfaced via Agent.__del__ during GC. See issue #2143.
+    """
+    client = MCPClient(MagicMock())
+
+    mock_thread = MagicMock()
+    mock_event_loop = MagicMock()
+    client._background_thread = mock_thread
+    client._background_thread_event_loop = mock_event_loop
+
+    with patch("strands.tools.mcp.mcp_client.sys.is_finalizing", return_value=True):
+        # Must not raise, and must not touch the thread or event loop.
+        client.stop(None, None, None)
+
+    mock_thread.join.assert_not_called()
+    mock_event_loop.close.assert_not_called()
+    # State is intentionally left alone during finalization — the interpreter
+    # is going away and cleanup is unnecessary.
+    assert client._background_thread is mock_thread
+    assert client._background_thread_event_loop is mock_event_loop
+
+
 def test_mcp_client_state_reset_after_timeout():
     """Test that all client state is properly reset after timeout."""