feat: make connection to Stdio MCP servers work on notebooks by redirecting errlog (#3037)

* feat: make connection to Stdio MCP servers work on notebooks by redirecting errlog

* revert changes to streamablehttp_client

* more

Author: anakin87

integrations/mcp/src/haystack_integrations/tools/mcp/mcp_tool.py

@@ -4,7 +4,10 @@
 
 import asyncio
 import concurrent.futures
+import io
 import json
+import sys
+import tempfile
 import threading
 import warnings
 from abc import ABC, abstractmethod
@@ -435,7 +438,17 @@ async def connect(self) -> list[types.Tool]:
         logger.debug(f"PROCESS: Connecting to stdio server with command: {self.command}")
 
         server_params = StdioServerParameters(command=self.command, args=self.args, env=self.env)
-        stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
+
+        # In notebook environments, sys.stderr is a custom object without a real file descriptor, which causes MCP stdio
+        # connection to fail. We detect this and set the MCP server's errlog to a temp file instead.
+        errlog = sys.stderr
+        try:
+            sys.stderr.fileno()
+        except (io.UnsupportedOperation, AttributeError, OSError):
+            errlog = tempfile.NamedTemporaryFile(mode="w", suffix="-mcp-stderr.log", delete=False)
+            logger.warning("MCP server stderr redirected to {path}", path=errlog.name)
+
+        stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params, errlog=errlog))
         return await self._initialize_session_with_transport(stdio_transport, f"stdio server (command: {self.command})")
 
 

integrations/mcp/tests/test_mcp_tool.py

@@ -1,5 +1,7 @@
+import io
 import json
 import os
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from haystack.components.agents import Agent
@@ -13,6 +15,7 @@
     MCPTool,
     StdioServerInfo,
 )
+from haystack_integrations.tools.mcp.mcp_tool import StdioClient
 
 from .mcp_memory_transport import InMemoryServerInfo
 from .mcp_servers_fixtures import calculator_mcp, echo_mcp
@@ -197,6 +200,42 @@ def test_mcp_tool_serde_with_state_mapping(self, mcp_tool_cleanup):
         assert new_tool._inputs_from_state == {"state_a": "a"}
         assert new_tool._outputs_to_state == {"result": {"source": "output"}}
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "fileno_side_effect,fileno_return_value,notebook_environment",
+        [
+            (io.UnsupportedOperation("fileno"), None, True),
+            (None, 2, False),
+        ],
+    )
+    async def test_stdio_client_stderr_handling(self, fileno_side_effect, fileno_return_value, notebook_environment):
+        """Test that StdioClient uses sys.stderr in terminals and falls back to a file in notebooks."""
+        client = StdioClient(command="echo", args=["hello"])
+
+        mock_stderr = MagicMock()
+        mock_stderr.fileno.side_effect = fileno_side_effect
+        mock_stderr.fileno.return_value = fileno_return_value
+
+        with (
+            patch.object(client, "exit_stack") as mock_stack,
+            patch("haystack_integrations.tools.mcp.mcp_tool.stdio_client") as mock_stdio_client,
+            patch("haystack_integrations.tools.mcp.mcp_tool.sys") as mock_sys,
+            patch.object(client, "_initialize_session_with_transport", new_callable=AsyncMock) as mock_init,
+        ):
+            mock_sys.stderr = mock_stderr
+            mock_stack.enter_async_context = AsyncMock(return_value=(MagicMock(), MagicMock()))
+            mock_init.return_value = []
+
+            await client.connect()
+
+            _, kwargs = mock_stdio_client.call_args
+            errlog = kwargs["errlog"]
+            if notebook_environment:
+                assert errlog is not mock_stderr
+                assert hasattr(errlog, "write")
+            else:
+                assert errlog is mock_stderr
+
     @pytest.mark.skipif("OPENAI_API_KEY" not in os.environ, reason="OPENAI_API_KEY not set")
     @pytest.mark.integration
     def test_pipeline_warmup_with_mcp_tool(self):