Skip to content

Build and run agents you can see, understand and trust.

fix(mcp): allow reconnecting stateful clients (#2308)

Solaris-starcd72cac57baf
diff --git a/src/agentscope/mcp/_mcp_client.py b/src/agentscope/mcp/_mcp_client.py
index 688e6e27b..761d5265c 100644
--- a/src/agentscope/mcp/_mcp_client.py
+++ b/src/agentscope/mcp/_mcp_client.py
@@ -164,15 +164,7 @@ class MCPClient(BaseModel):
self._initialize_client()
def _initialize_client(self) -> None:
- """Pre-build the stdio client context manager.
-
- Only the stdio transport is materialised at construction time —
- ``StdioServerParameters`` carry process-launch details that are
- cheap to bind upfront. HTTP transports are built lazily inside
- :meth:`connect` (or per-call inside :meth:`_get_client_gen` for
- stateless mode), since each ``streamable_http_client`` /
- ``sse_client`` is a one-shot context manager.
- """
+ """Pre-build the stdio client context manager."""
if self.mcp_config.type == "stdio_mcp":
config = self.mcp_config
self._client = stdio_client(
@@ -233,10 +225,15 @@ class MCPClient(BaseModel):
"Call close() before reconnecting.",
)
- # Create HTTP client if needed
- if self._client is None and self.mcp_config.type == "http_mcp":
- self._client = self._create_http_client()
+ # Transports are one-shot context managers. Recreate them before every
+ # connection so connect() -> close() -> connect() starts a fresh one.
+ if self._client is None:
+ if self.mcp_config.type == "http_mcp":
+ self._client = self._create_http_client()
+ else:
+ self._initialize_client()
+ assert self._client is not None
self._stack = AsyncExitStack()
try:
@@ -251,6 +248,7 @@ class MCPClient(BaseModel):
except Exception:
await self._stack.aclose()
self._stack = None
+ self._client = None
raise
async def close(self, ignore_errors: bool = True) -> None:
@@ -288,6 +286,7 @@ class MCPClient(BaseModel):
str(e),
)
finally:
+ self._client = None
self._stack = None
self._session = None
self._is_connected = False
diff --git a/tests/mcp_client_reconnect_test.py b/tests/mcp_client_reconnect_test.py
new file mode 100644
index 000000000..cebe5d397
--- /dev/null
+++ b/tests/mcp_client_reconnect_test.py
@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+"""Tests for reconnecting stateful MCP clients."""
+from types import TracebackType
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+from agentscope.mcp import HttpMCPConfig, MCPClient, StdioMCPConfig
+
+
+class _OneShotTransport:
+ """Minimal transport context manager that cannot be entered twice."""
+
+ def __init__(self) -> None:
+ self.enter_count = 0
+
+ async def __aenter__(self) -> tuple[object, object]:
+ self.enter_count += 1
+ if self.enter_count > 1:
+ raise AssertionError("transport context manager was reused")
+ return object(), object()
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc: BaseException | None,
+ traceback: TracebackType | None,
+ ) -> bool:
+ return False
+
+
+class _FakeSession:
+ """Small ClientSession stand-in for lifecycle-only tests."""
+
+ def __init__(self, read_stream: object, write_stream: object) -> None:
+ self.read_stream = read_stream
+ self.write_stream = write_stream
+
+ async def __aenter__(self) -> "_FakeSession":
+ """Enter the fake session context."""
+ return self
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc: BaseException | None,
+ traceback: TracebackType | None,
+ ) -> bool:
+ """Leave the fake session context."""
+ return False
+
+ async def initialize(self) -> None:
+ """Initialize the fake session."""
+ return None
+
+
+class MCPClientReconnectTest(IsolatedAsyncioTestCase):
+ """Stateful MCP transports must be recreated for every connection."""
+
+ async def test_stdio_client_can_reconnect_after_close(self) -> None:
+ """A stdio client must get a new transport after close()."""
+ transports: list[_OneShotTransport] = []
+
+ def create_transport(_parameters: Any) -> _OneShotTransport:
+ """Create and retain a one-shot transport for assertions."""
+ transport = _OneShotTransport()
+ transports.append(transport)
+ return transport
+
+ with patch(
+ "agentscope.mcp._mcp_client.stdio_client",
+ side_effect=create_transport,
+ ), patch(
+ "agentscope.mcp._mcp_client.ClientSession",
+ _FakeSession,
+ ):
+ client = MCPClient(
+ name="reconnect_stdio",
+ is_stateful=True,
+ mcp_config=StdioMCPConfig(command="unused"),
+ )
+
+ await client.connect()
+ await client.close()
+ await client.connect()
+ await client.close()
+
+ self.assertEqual(len(transports), 2)
+ self.assertTrue(all(_.enter_count == 1 for _ in transports))
+
+ async def test_failed_connect_can_be_retried(self) -> None:
+ """A failed connection must discard its one-shot transport."""
+ transports: list[_OneShotTransport] = []
+
+ def create_transport(_parameters: Any) -> _OneShotTransport:
+ """Create and retain a one-shot transport for assertions."""
+ transport = _OneShotTransport()
+ transports.append(transport)
+ return transport
+
+ class _FailOnceSession(_FakeSession):
+ """Fail the first initialization, then allow a retry."""
+
+ attempts = 0
+
+ async def initialize(self) -> None:
+ _FailOnceSession.attempts += 1
+ if _FailOnceSession.attempts == 1:
+ raise RuntimeError("initialization failed")
+
+ with patch(
+ "agentscope.mcp._mcp_client.stdio_client",
+ side_effect=create_transport,
+ ), patch(
+ "agentscope.mcp._mcp_client.ClientSession",
+ _FailOnceSession,
+ ):
+ client = MCPClient(
+ name="retry_after_failed_connect",
+ is_stateful=True,
+ mcp_config=StdioMCPConfig(command="unused"),
+ )
+
+ with self.assertRaisesRegex(RuntimeError, "initialization failed"):
+ await client.connect()
+ await client.connect()
+ await client.close()
+
+ self.assertEqual(len(transports), 2)
+ self.assertTrue(all(_.enter_count == 1 for _ in transports))
+
+ async def test_http_client_can_reconnect_after_close(self) -> None:
+ """An HTTP client must get a new transport after close()."""
+ transports: list[_OneShotTransport] = []
+
+ def create_transport() -> _OneShotTransport:
+ """Create and retain a one-shot transport for assertions."""
+ transport = _OneShotTransport()
+ transports.append(transport)
+ return transport
+
+ with patch.object(
+ MCPClient,
+ "_create_http_client",
+ side_effect=create_transport,
+ ), patch(
+ "agentscope.mcp._mcp_client.ClientSession",
+ _FakeSession,
+ ):
+ client = MCPClient(
+ name="reconnect_http",
+ is_stateful=True,
+ mcp_config=HttpMCPConfig(url="http://unused"),
+ )
+
+ await client.connect()
+ await client.close()
+ await client.connect()
+ await client.close()
+
+ self.assertEqual(len(transports), 2)
+ self.assertTrue(all(_.enter_count == 1 for _ in transports))