From 61a1d9b4de9132933c4e726f4bcab99a22f7e9e5 Mon Sep 17 00:00:00 2001 From: Dean Schmigelski Date: Wed, 4 Jun 2025 15:00:50 +0300 Subject: [PATCH 1/3] chore: enhance error messaging when MCP tools are used without session initialization --- src/strands/tools/mcp/mcp_client.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/strands/tools/mcp/mcp_client.py b/src/strands/tools/mcp/mcp_client.py index c6890945..25b5c4e4 100644 --- a/src/strands/tools/mcp/mcp_client.py +++ b/src/strands/tools/mcp/mcp_client.py @@ -41,6 +41,11 @@ "image/webp": "webp", } +CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE = ( + "the client session is not running. Please ensure the agent is used within " + "the MCP client context manager ('with mcp_client:')" +) + class MCPClient: """Represents a connection to a Model Context Protocol (MCP) server. @@ -145,7 +150,7 @@ def list_tools_sync(self) -> List[MCPAgentTool]: """ self._log_debug_with_thread("listing MCP tools synchronously") if not self._is_session_active(): - raise MCPClientInitializationError("the client session is not running") + raise MCPClientInitializationError(CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE) async def _list_tools_async() -> ListToolsResult: return await self._background_thread_session.list_tools() @@ -180,7 +185,7 @@ def call_tool_sync( """ self._log_debug_with_thread("calling MCP tool '%s' synchronously with tool_use_id=%s", name, tool_use_id) if not self._is_session_active(): - raise MCPClientInitializationError("the client session is not running") + raise MCPClientInitializationError(CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE) async def _call_tool_async() -> MCPCallToolResult: return await self._background_thread_session.call_tool(name, arguments, read_timeout_seconds) From fb1eba97e4178c6535f7acf9784b39d3211aff86 Mon Sep 17 00:00:00 2001 From: Dean Schmigelski Date: Wed, 4 Jun 2025 15:32:06 +0300 Subject: [PATCH 2/3] Update src/strands/tools/mcp/mcp_client.py Co-authored-by: Mackenzie Zastrow <3211021+zastrowm@users.noreply.github.com> --- src/strands/tools/mcp/mcp_client.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/strands/tools/mcp/mcp_client.py b/src/strands/tools/mcp/mcp_client.py index 25b5c4e4..01d6edb1 100644 --- a/src/strands/tools/mcp/mcp_client.py +++ b/src/strands/tools/mcp/mcp_client.py @@ -42,7 +42,7 @@ } CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE = ( - "the client session is not running. Please ensure the agent is used within " + "the client session is not running. Ensure the agent is used within " "the MCP client context manager ('with mcp_client:')" ) From 95a822136d4042b8f7d218d5ce6f6205cd1b525a Mon Sep 17 00:00:00 2001 From: Dean Schmigelski Date: Mon, 9 Jun 2025 17:40:25 +0300 Subject: [PATCH 3/3] update error message with link to Troubleshooting section in docs --- src/strands/tools/mcp/mcp_client.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/strands/tools/mcp/mcp_client.py b/src/strands/tools/mcp/mcp_client.py index 01d6edb1..a2298813 100644 --- a/src/strands/tools/mcp/mcp_client.py +++ b/src/strands/tools/mcp/mcp_client.py @@ -43,7 +43,8 @@ CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE = ( "the client session is not running. Ensure the agent is used within " - "the MCP client context manager ('with mcp_client:')" + "the MCP client context manager. For more information see: " + "https://strandsagents.com/latest/user-guide/concepts/tools/mcp-tools/#mcpclientinitializationerror" )