TimeoutError
mcp.client.TimeoutError
Stack trace
Traceback (most recent call last):
File "app.py", line 42, in <module>
client.connect()
File "/usr/local/lib/python3.9/site-packages/mcp/client.py", line 128, in connect
raise TimeoutError("Connection to MCP server timed out after 10 seconds")
mcp.client.TimeoutError: Connection to MCP server timed out after 10 seconds Why it happens
The MCP client attempts to connect to the MCP server but does not receive a response within the configured timeout window. This can happen due to network latency, server unavailability, firewall blocking, or incorrect server address configuration.
Detection
Monitor connection attempts and catch TimeoutError exceptions; log the duration and server endpoint to identify recurring timeout patterns before the application crashes.
Causes & fixes
Network latency or unstable internet connection causing delayed responses
Increase the client's connection timeout setting to allow more time for the server to respond.
MCP server is down or unreachable due to firewall or network restrictions
Verify server availability and network/firewall rules; whitelist MCP server IP and port if necessary.
Incorrect MCP server hostname or IP address configured in the client
Double-check and correct the MCP server address configuration in the client setup.
Client uses default low timeout value unsuitable for high-latency environments
Explicitly set a higher timeout value in the MCP client connection parameters.
Code: broken vs fixed
from mcp import Client
client = Client(server_url="http://mcp.example.com")
client.connect() # This line raises TimeoutError after default 10s timeoutimport os
from mcp import Client
# Set environment variable for MCP server URL
os.environ["MCP_SERVER_URL"] = "http://mcp.example.com"
client = Client(server_url=os.environ["MCP_SERVER_URL"], timeout=30) # Increased timeout to 30 seconds
client.connect()
print("Connected successfully to MCP server")Workaround
Wrap the connect call in try/except TimeoutError, then retry the connection a few times with exponential backoff before failing.
Prevention
Configure the MCP client with appropriate timeout values based on network conditions and implement retry logic with backoff to handle transient connectivity issues gracefully.