Troubleshoot: MCP Connection Refused or Timeout Errors

When MCP Server starts successfully but cannot connect, or timeout errors occur, this guide helps troubleshoot network-level issues.

Symptoms

• MCP Server starts but tools cannot be called
• "Connection refused" error
• "Timeout" or "ETIMEDOUT" error
• Unstable connection

Troubleshooting Steps

Step 1: Check Port Usage

# macOS/Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000

Step 2: Check Firewall

macOS Firewall

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

Step 3: Check Network Policy

Proxy Settings

echo $HTTP_PROXY
echo $HTTPS_PROXY
unset HTTP_PROXY  # Test without proxy

Step 4: Check Server Listen Address

Ensure server listens on 127.0.0.1 or localhost, not 0.0.0.0

Step 5: Test Connection

curl http://localhost:3000/health
nc -zv localhost 3000

Quick Reference

Error	Cause	Solution
Connection refused	Port not listening	Check service status
ETIMEDOUT	Network timeout	Check network/proxy
ECONNRESET	Connection reset	Check server logs

Next Steps

• Python Environment Issues
• Node.js Environment Issues
• Filesystem Configuration