This guide helps you diagnose and resolve connection issues between mcp_use and MCP servers.

Understanding MCP Connections

MCP servers can use different connection types, each with unique failure modes:

  • Stdio: Communication through stdin/stdout
  • HTTP: RESTful API communication
  • WebSocket: Real-time bidirectional communication

Common Connection Errors

Server Not Found

Error: FileNotFoundError: [Errno 2] No such file or directory: 'command'

Diagnosis:

import shutil

# Check if command exists
command = "npx"  # or your server command
if shutil.which(command):
    print(f"✅ {command} found at: {shutil.which(command)}")
else:
    print(f"❌ {command} not found in PATH")

Solutions:

# Install Node.js and npm
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

# Install MCP server globally
npm install -g @playwright/mcp

Connection Timeout

Error: TimeoutError: Server connection timed out after 30 seconds

Diagnosis:

import asyncio
import time

async def test_server_startup():
    start_time = time.time()
    try:
        client = MCPClient.from_config_file("config.json")
        await asyncio.wait_for(client.create_all_sessions(), timeout=10)
        elapsed = time.time() - start_time
        print(f"✅ Sessions created in {elapsed:.2f}s")
    except asyncio.TimeoutError:
        elapsed = time.time() - start_time
        print(f"❌ Session creation timed out after {elapsed:.2f}s")

# Run test
await test_server_startup()

Solutions:

  1. Increase timeout:

    agent = MCPAgent(
        llm=llm,
        client=client,
        timeout=60,  # Increase from default 30s
        server_startup_timeout=45
    )
    
  2. Check server logs:

    import logging
    logging.basicConfig(level=logging.DEBUG)
    
    # This will show detailed server startup logs
    client = MCPClient.from_config_file("config.json", debug=True)
    
  3. Test server manually:

    # Test Node.js server
    timeout 30 npx @playwright/mcp@latest
    
    # Test Python server
    timeout 30 mcp-server-filesystem /workspace
    

Permission Denied

Error: PermissionError: [Errno 13] Permission denied

Diagnosis:

# Check file permissions
ls -la /path/to/server/executable

# Check directory permissions
ls -ld /path/to/workspace/directory

# Check current user
whoami
id

Solutions:

  1. Fix file permissions:

    # Make server executable
    chmod +x /path/to/mcp-server
    
    # Fix directory permissions
    chmod 755 /workspace/directory
    
    # Change ownership if needed
    chown $USER:$USER /workspace/directory
    
  2. Use accessible directories:

    {
      "mcpServers": {
        "filesystem": {
          "command": "mcp-server-filesystem",
          "args": ["/home/$USER/workspace"]  // Use home directory
        }
      }
    }
    
  3. Run with appropriate user:

    # Don't run as root unless necessary
    sudo -u $USER python your_script.py
    

Server Crash on Startup

Error: ConnectionError: Server process exited with code 1

Diagnosis:

import subprocess
import json

def test_server_manually(config_file):
    with open(config_file) as f:
        config = json.load(f)

    for name, server_config in config["mcpServers"].items():
        print(f"\nTesting server: {name}")
        command = [server_config["command"]] + server_config.get("args", [])

        try:
            result = subprocess.run(
                command,
                capture_output=True,
                text=True,
                timeout=10
            )
            print(f"Return code: {result.returncode}")
            if result.stdout:
                print(f"Stdout: {result.stdout}")
            if result.stderr:
                print(f"Stderr: {result.stderr}")
        except Exception as e:
            print(f"Error: {e}")

# Test all servers
test_server_manually("config.json")

Solutions:

  1. Check server dependencies:

    # For Playwright server
    npx playwright install
    
    # For filesystem server
    pip install --upgrade mcp-server-filesystem
    
  2. Validate server arguments:

    {
      "mcpServers": {
        "filesystem": {
          "command": "mcp-server-filesystem",
          "args": [
            "/existing/directory",  // Make sure this exists
            "--readonly=false"      // Valid argument format
          ]
        }
      }
    }
    
  3. Check environment variables:

    {
      "mcpServers": {
        "playwright": {
          "command": "npx",
          "args": ["@playwright/mcp@latest"],
          "env": {
            "DISPLAY": ":0",           // Required for GUI apps
            "HOME": "/home/user",      // Sometimes needed
            "PATH": "/usr/local/bin:/usr/bin:/bin"
          }
        }
      }
    }
    

Protocol-Specific Issues

Stdio Connection Issues

Problem: Server starts but communication fails.

Diagnosis:

async def test_stdio_communication():
    import subprocess
    import json

    # Start server process
    process = subprocess.Popen(
        ["npx", "@playwright/mcp@latest"],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True
    )

    # Send initialization message
    init_msg = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {"capabilities": {}}
    }

    try:
        process.stdin.write(json.dumps(init_msg) + "\n")
        process.stdin.flush()

        # Read response with timeout
        import select
        ready, _, _ = select.select([process.stdout], [], [], 5)

        if ready:
            response = process.stdout.readline()
            print(f"✅ Server responded: {response}")
        else:
            print("❌ No response from server")

    finally:
        process.terminate()

await test_stdio_communication()

Solutions:

  1. Ensure server supports stdio mode
  2. Check for buffer flushing issues
  3. Verify JSON-RPC message format

HTTP Connection Issues

Problem: Cannot connect to HTTP-based MCP server.

Diagnosis:

import aiohttp
import asyncio

async def test_http_server(url="http://localhost:8000"):
    async with aiohttp.ClientSession() as session:
        try:
            async with session.get(f"{url}/health") as response:
                print(f"✅ HTTP server responding: {response.status}")
                text = await response.text()
                print(f"Response: {text}")
        except Exception as e:
            print(f"❌ HTTP connection failed: {e}")

await test_http_server()

Solutions:

  1. Verify server is listening on correct port
  2. Check firewall settings
  3. Ensure HTTP server is properly configured

WebSocket Connection Issues

Problem: WebSocket connection fails or drops.

Diagnosis:

import websockets
import asyncio

async def test_websocket(uri="ws://localhost:8000/ws"):
    try:
        async with websockets.connect(uri) as websocket:
            print("✅ WebSocket connected")

            # Send ping
            await websocket.send("ping")
            response = await asyncio.wait_for(websocket.recv(), timeout=5)
            print(f"Response: {response}")

    except Exception as e:
        print(f"❌ WebSocket failed: {e}")

await test_websocket()

Solutions:

  1. Check WebSocket server implementation
  2. Verify network connectivity
  3. Handle connection drops gracefully

Network and Firewall Issues

Port Conflicts

Problem: Server cannot bind to port.

Diagnosis:

# Check what's using port 8000
lsof -i :8000
netstat -tulpn | grep 8000

# Find available ports
python -c "import socket; s=socket.socket(); s.bind(('',0)); print(s.getsockname()[1]); s.close()"

Solutions:

  1. Use different port in configuration
  2. Stop conflicting services
  3. Use port range for multiple servers

Firewall Blocking

Problem: Firewall blocking server connections.

Diagnosis:

# Check firewall status
sudo ufw status
sudo iptables -L

# Test connection
telnet localhost 8000
nc -zv localhost 8000

Solutions:

# Open port in firewall
sudo ufw allow 8000
sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT

# Or disable firewall for testing
sudo ufw disable

Docker and Container Issues

Container Networking

Problem: MCP servers not accessible from container.

Solutions:

# Expose necessary ports
EXPOSE 8000

# Install required dependencies
RUN apt-get update && apt-get install -y nodejs npm

# Set proper networking
CMD ["python", "main.py", "--host", "0.0.0.0"]
# docker-compose.yml
version: '3.8'
services:
  mcp-use:
    build: .
    ports:
      - "8000:8000"
    network_mode: "host"  # For localhost server access

Volume Mounting

Problem: Servers cannot access mounted files.

Solutions:

# Mount with proper permissions
docker run -v /host/workspace:/container/workspace:rw myapp

# Check mounted volume permissions
docker exec -it container ls -la /container/workspace

Advanced Debugging

Connection Logging

Enable detailed connection logging:

import logging

# Configure logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Enable specific loggers
logging.getLogger("mcp_use").setLevel(logging.DEBUG)
logging.getLogger("asyncio").setLevel(logging.INFO)

# Create client with debug mode
client = MCPClient.from_config_file("config.json", debug=True)

Network Traffic Analysis

Monitor network traffic for HTTP/WebSocket servers:

# Monitor network traffic
sudo tcpdump -i lo port 8000 -A

# Monitor with netstat
watch -n 1 'netstat -tulpn | grep 8000'

# Use curl for HTTP testing
curl -v http://localhost:8000/health

Process Monitoring

Monitor server processes:

import psutil
import subprocess

def monitor_server_process(command_name):
    for proc in psutil.process_iter(['pid', 'name', 'cmdline']):
        try:
            if command_name in proc.info['name'] or \
               any(command_name in arg for arg in proc.info['cmdline']):
                print(f"Found process: PID={proc.info['pid']}")
                print(f"Command: {' '.join(proc.info['cmdline'])}")
                print(f"Status: {proc.status()}")
                print(f"Memory: {proc.memory_info().rss / 1024 / 1024:.1f}MB")
                return proc.info['pid']
        except (psutil.NoSuchProcess, psutil.AccessDenied):
            pass

    print(f"No process found for: {command_name}")
    return None

# Monitor specific server
pid = monitor_server_process("npx")

Recovery Strategies

Automatic Retry

Implement connection retry logic:

import asyncio
from typing import Optional

class ResilientMCPClient:
    def __init__(self, config_file: str, max_retries: int = 3):
        self.config_file = config_file
        self.max_retries = max_retries
        self._client: Optional[MCPClient] = None

    async def connect_with_retry(self):
        for attempt in range(self.max_retries):
            try:
                self._client = MCPClient.from_config_file(self.config_file)
                await self._client.create_all_sessions()
                print(f"✅ Connected on attempt {attempt + 1}")
                return self._client
            except Exception as e:
                print(f"❌ Attempt {attempt + 1} failed: {e}")
                if attempt < self.max_retries - 1:
                    wait_time = 2 ** attempt  # Exponential backoff
                    print(f"Retrying in {wait_time}s...")
                    await asyncio.sleep(wait_time)
                else:
                    raise

    async def ensure_connected(self):
        if not self._client:
            return await self.connect_with_retry()

        # Test connection
        try:
            # Test if sessions are active
            active_sessions = self._client.get_all_active_sessions()
            if len(active_sessions) > 0:
                return self._client
        except:
            print("Connection lost, reconnecting...")
            return await self.connect_with_retry()

# Usage
resilient_client = ResilientMCPClient("config.json", max_retries=3)
client = await resilient_client.ensure_connected()

Health Checks

Implement server health monitoring:

import asyncio
from datetime import datetime, timedelta

class ServerHealthMonitor:
    def __init__(self, client: MCPClient, check_interval: int = 30):
        self.client = client
        self.check_interval = check_interval
        self.last_check = datetime.now()
        self.is_healthy = True

    async def health_check(self):
        try:
            # Check if we have active sessions
            active_sessions = self.client.get_all_active_sessions()
            self.is_healthy = len(active_sessions) > 0
            self.last_check = datetime.now()
            return self.is_healthy
        except Exception as e:
            print(f"Health check failed: {e}")
            self.is_healthy = False
            return False

    async def start_monitoring(self):
        while True:
            await self.health_check()
            if not self.is_healthy:
                print("⚠️ Server unhealthy, attempting reconnection...")
                try:
                    await self.client.close_all_sessions()
                    await self.client.create_all_sessions()
                    await self.health_check()
                except Exception as e:
                    print(f"Reconnection failed: {e}")

            await asyncio.sleep(self.check_interval)

# Usage
monitor = ServerHealthMonitor(client, check_interval=30)
asyncio.create_task(monitor.start_monitoring())

Getting Help

If connection issues persist:

  1. Collect diagnostic information:

    # System info
    uname -a
    python --version
    node --version
    
    # Network info
    ip addr show
    netstat -tulpn
    
    # Process info
    ps aux | grep mcp
    
  2. Create minimal reproduction:

    # Simplest possible test case
    async def minimal_test():
        client = MCPClient.from_dict({
            "mcpServers": {
                "test": {
                    "command": "echo",
                    "args": ["hello"]
                }
            }
        })
        await client.create_all_sessions()
    
    await minimal_test()
    
  3. Report with details:

    • Operating system and version
    • Python and Node.js versions
    • Complete error messages
    • Server configuration (remove sensitive data)
    • Steps to reproduce

Most connection issues are environment-related. Always test server commands manually before using them with mcp_use.