ConnectionError
mcp.transport.stdio.ConnectionError
Stack trace
Traceback (most recent call last):
File "mcp/server.py", line 142, in start_transport
transport.connect()
File "mcp/transport/stdio.py", line 58, in connect
raise ConnectionError("Failed to connect stdio transport")
mcp.transport.stdio.ConnectionError: Failed to connect stdio transport Why it happens
This error occurs when the MCP server cannot open or maintain the standard input/output transport channel, often due to subprocess launch failures, incorrect environment setup, or resource limits preventing pipe creation.
Detection
Monitor MCP server logs for ConnectionError exceptions during stdio transport setup and implement health checks that verify subprocess communication channels are active.
Causes & fixes
Subprocess for MCP stdio transport failed to start due to missing executable or permissions
Ensure the MCP subprocess executable exists, has correct permissions, and the environment PATH includes its location.
Operating system resource limits prevent creation of new pipes or file descriptors
Increase OS limits for open files and processes (e.g., ulimit on Unix systems) to allow MCP to create necessary stdio pipes.
Environment variables required for MCP stdio transport are missing or misconfigured
Verify and set all required environment variables before starting MCP server to ensure proper stdio transport initialization.
Code: broken vs fixed
import os
from mcp.transport.stdio import StdioTransport
transport = StdioTransport()
transport.connect() # This line raises ConnectionErrorimport os
from mcp.transport.stdio import StdioTransport
os.environ['MCP_EXECUTABLE_PATH'] = '/usr/local/bin/mcp_subprocess' # Set required env var
transport = StdioTransport()
transport.connect() # Fixed: subprocess path and env set
print("MCP stdio transport connected successfully")Workaround
Catch the ConnectionError exception, then attempt to restart the MCP subprocess manually or fallback to an alternative transport method if available.
Prevention
Implement robust subprocess startup checks and environment validation before MCP server launch to ensure stdio transport can connect reliably every time.