fix(mcp): merge custom env with os.environ for MCPServerStdio (#1296)

When users set env={"FOO": "bar"} on an MCPServerStdio, the subprocess
was spawned with only those vars — missing PATH, HOME, etc. This caused
the MCP server process to fail during initialization (TimeoutError).

Now always merges user env on top of os.environ so custom vars take
precedence while the subprocess still inherits the standard environment.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: zzstoatzz

src/marvin/_internal/integrations/mcp.py

@@ -102,12 +102,21 @@ async def start_servers(self, actor: "Actor") -> list[MCPServer]:
                 continue
 
             try:
-                # Set environment variables for stdio servers if not already set
-                if isinstance(server, MCPServerStdio) and server.env is None:
-                    logger.debug(
-                        f"[MCPManager] Server {server_repr} has no env set. Setting env=dict(os.environ)."
-                    )
-                    server.env = dict(os.environ)
+                # Ensure stdio servers inherit the full environment,
+                # merging any user-specified env vars on top of os.environ.
+                # Without this, a server with env={"FOO": "bar"} would lose
+                # PATH, HOME, etc., causing the subprocess to fail.
+                if isinstance(server, MCPServerStdio):
+                    if server.env is None:
+                        logger.debug(
+                            f"[MCPManager] Server {server_repr} has no env set. Setting env=dict(os.environ)."
+                        )
+                        server.env = dict(os.environ)
+                    else:
+                        logger.debug(
+                            f"[MCPManager] Server {server_repr} has custom env. Merging with os.environ."
+                        )
+                        server.env = {**os.environ, **server.env}
 
                 await self.exit_stack.enter_async_context(server)
                 self.active_servers.append(server)

tests/agents/test_mcp_integration.py

@@ -1,3 +1,4 @@
+import os
 from unittest.mock import AsyncMock, MagicMock, patch
 
 from pydantic_ai.mcp import MCPServer
@@ -267,6 +268,59 @@ async def mock_start_servers(self, actor):
             # Cleanup
             await cleanup_thread_mcp_servers()
 
+    async def test_mcp_manager_merges_env_with_os_environ(self):
+        """MCPServerStdio with custom env should still inherit os.environ.
+
+        Regression test: when a user sets env={"FOO": "bar"} on an MCPServerStdio,
+        the subprocess needs PATH, HOME, etc. to function. The manager should
+        merge user env on top of os.environ, not use it as-is.
+        """
+        from pydantic_ai.mcp import MCPServerStdio
+
+        custom_env = {"HUE_BRIDGE_IP": "192.168.1.100", "HUE_BRIDGE_USERNAME": "test"}
+        server = MCPServerStdio(command="echo", args=["hello"], env=custom_env)
+        agent = MagicMock(spec=Agent)
+        agent.name = "TestAgent"
+        agent.get_mcp_servers.return_value = [server]
+
+        manager = MCPManager()
+
+        # Patch enter_async_context to avoid actually starting the server
+        manager.exit_stack.enter_async_context = AsyncMock()
+
+        with patch.dict(
+            os.environ, {"PATH": "/usr/bin", "HOME": "/home/test"}, clear=True
+        ):
+            await manager.start_servers(agent)
+
+        # The server's env should have both os.environ and custom vars
+        assert server.env is not None
+        assert server.env["PATH"] == "/usr/bin"
+        assert server.env["HOME"] == "/home/test"
+        # Custom vars should take precedence
+        assert server.env["HUE_BRIDGE_IP"] == "192.168.1.100"
+        assert server.env["HUE_BRIDGE_USERNAME"] == "test"
+
+    async def test_mcp_manager_sets_env_when_none(self):
+        """MCPServerStdio with env=None should get os.environ."""
+        from pydantic_ai.mcp import MCPServerStdio
+
+        server = MCPServerStdio(command="echo", args=["hello"])
+        assert server.env is None
+
+        agent = MagicMock(spec=Agent)
+        agent.name = "TestAgent"
+        agent.get_mcp_servers.return_value = [server]
+
+        manager = MCPManager()
+        manager.exit_stack.enter_async_context = AsyncMock()
+
+        with patch.dict(os.environ, {"PATH": "/usr/bin"}, clear=True):
+            await manager.start_servers(agent)
+
+        assert server.env is not None
+        assert server.env["PATH"] == "/usr/bin"
+
     async def test_mcp_manager_tracks_started_servers_by_id(self):
         """MCPManager should track servers by id to avoid restarting the same server."""
         manager = MCPManager()