gh-technicalpickles-pickled-claude-plugins-plugins-debugging-tools/skills/mcpproxy-debug/references/connection-failures.md

Connection Failures - Detailed Diagnosis

When to use this reference: Server shows connected: false or has connection errors in status API.

This reference provides step-by-step workflows for diagnosing why an MCP server won't connect through MCPProxy.

Systematic Diagnosis Workflow

Step 1: Check Server-Specific Logs

Server-specific logs contain the most revealing information, especially stderr output from the failing server.

# List all server logs (most recent first)
ls -lhrt ~/Library/Logs/mcpproxy/server-*.log | tail -10

# Check specific server log (last 50 lines)
tail -50 ~/Library/Logs/mcpproxy/server-SERVER_NAME.log

# Find errors in server log
grep -i "error\|failed\|stderr" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -20

# Focus on stderr (most revealing)
grep "stderr" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -20

What to look for:

• Error messages in stderr output
• Stack traces indicating crashes
• Missing dependencies or packages
• Permission errors
• Network connection failures

Step 2: Identify Error Patterns

Most connection failures follow recognizable patterns. Match the error message to the pattern below.

Common Error Patterns

Pattern: "unexpected argument found"

Example stderr:

error: unexpected argument '--local-timezone' found

Root cause: Package manager (uvx/npx) received server arguments before package name.

Commands affected: uvx, npx, yarn dlx, bunx

How it happens:

// WRONG - Arguments passed to uvx instead of the package
{
  "command": "uvx",
  "args": ["--local-timezone", "America/New_York"]
}

// Package manager sees: uvx --local-timezone America/New_York
// And thinks: "--local-timezone is not a uvx option!"

Fix:

// CORRECT - Package name first, then its arguments
{
  "command": "uvx",
  "args": [
    "mcp-server-time",           // Package name FIRST
    "--local-timezone",          // Then package's arguments
    "America/New_York"
  ]
}

Verification:

# After fixing config, check server log for successful connection
tail -20 ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | grep -i "connected\|ready"

Pattern: "the input device is not a TTY"

Example stderr:

the input device is not a TTY

Root causes:

Cause 1: Using -it with Docker

MCPProxy communicates via stdio pipes, not terminal TTY sessions. Using -it with Docker tries to allocate a TTY, which fails in pipe mode.

// WRONG - Docker with -it flags
{
  "command": "docker",
  "args": ["run", "-it", "--rm", "image:tag"]
}

Fix:

// CORRECT - Only -i for stdin pipe
{
  "command": "docker",
  "args": ["run", "-i", "--rm", "image:tag"]
}

Cause 2: Docker Isolation on Docker-based Server

MCPProxy's Docker isolation feature wraps commands in Docker containers. When the command itself is Docker, you get Docker-in-Docker, which causes TTY issues.

// WRONG - Docker isolation wrapping a Docker command
{
  "command": "docker",
  "args": ["run", "-i", "--rm", "image:tag"],
  "isolation": {
    "enabled": true  // This wraps Docker in Docker!
  }
}

Fix:

// CORRECT - Disable isolation for Docker commands
{
  "command": "docker",
  "args": ["run", "-i", "--rm", "image:tag"],
  "isolation": {
    "enabled": false
  }
}

Why this happens: MCPProxy auto-detects Docker commands and should skip isolation, but explicit configuration is more reliable.

Verification:

# Check if isolation was applied
grep -i "docker isolation" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -5

# Verify no Docker containers running for this server
docker ps | grep mcpproxy-SERVER_NAME

Pattern: "context deadline exceeded"

Example error:

last_error: "context deadline exceeded"
status: "error"

Root cause: Server failed to initialize within timeout (usually 30 seconds).

Common reasons:

1. Underlying error hidden - Check stderr for the real error:

   grep "stderr" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -20
   

2. Missing package name (uvx/npx) - Look for "unexpected argument":

   grep "unexpected argument" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log
   

3. Docker TTY issue - Look for "not a TTY":

   grep "TTY" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log
   

4. Docker image pull failed:

   grep -i "pull\|not found" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log
   

5. Server crashed during startup:

   grep -i "stack trace\|panic\|exception" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log
   

6. Missing environment variables:

   grep -i "missing\|required.*variable" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log
   

7. Network issues (HTTP servers):

   grep -i "connection refused\|timeout" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log
   

Investigation workflow:

# 1. Check if process even started
grep "Starting connection\|Docker isolation setup" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -5

# 2. Check stderr for the real error
grep "stderr" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -20

# 3. If Docker isolation enabled, check container logs
docker ps -a | grep mcpproxy-SERVER_NAME
docker logs CONTAINER_ID

# 4. Check Docker command being executed
grep "docker_run_args" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -3

Fix: Address the underlying error found in stderr.

Pattern: "database is locked"

Example error:

ERROR: database is locked

Root cause: Another mcpproxy instance is running and has locked ~/.mcpproxy/config.db.

Fix:

# Kill all mcpproxy instances
pkill mcpproxy

# Wait for processes to clean up
sleep 2

# Verify no mcpproxy processes remain
ps aux | grep mcpproxy | grep -v grep

# Restart mcpproxy
open /Applications/mcpproxy.app  # macOS
# OR
mcpproxy &  # Linux/headless

Prevention: Always use pkill mcpproxy before starting a new instance.

Pattern: "transport error" / "EOF"

Example error:

last_error: "transport error: EOF"

Root cause: Server process exited unexpectedly or closed stdio pipes.

Investigation:

# Check if server crashed
grep -i "exit\|crash\|terminated" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -10

# Look for error messages before EOF
grep -B 20 "EOF" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -30

# Check stderr for crash details
grep "stderr" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -20

Common causes:

• Missing dependencies in Docker image
• Server code bug causing crash
• Memory/resource limits hit (Docker isolation)
• Permission errors accessing files

Fix: Depends on stderr output. Often requires fixing server code or Docker image.

Step 3: Docker Isolation Checks

If Docker isolation is enabled and server is failing:

# Check if isolation is active for this server
grep -i "docker isolation enabled\|docker isolation setup" ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | tail -5

# List running containers
docker ps | grep mcpproxy

# Check container status
docker ps -a | grep mcpproxy-SERVER_NAME

# View container logs
docker logs CONTAINER_NAME

# Check Docker context (for Colima users)
docker context show

If Docker isolation is interfering:

1. See references/docker-isolation-guide.md for detailed Docker troubleshooting
2. Consider disabling isolation for this server (add "isolation": {"enabled": false})

Step 4: Configuration Verification

Verify the server configuration is correct:

# View server config (pretty-printed)
cat ~/.mcpproxy/mcp_config.json | python3 -m json.tool | grep -A 20 '"name": "SERVER_NAME"'

# Check for common mistakes:
# - uvx/npx: Package name is first argument?
# - Docker: Using -i not -it?
# - Docker servers: isolation disabled?
# - Quarantined: "quarantined": false?

For detailed configuration patterns, see references/configuration-patterns.md.

Step 5: Test Server Command Manually

Test if the server command works outside MCPProxy:

# For uvx servers
uvx mcp-server-name --arg value

# For Docker servers (remove -i for manual testing)
docker run --rm -it image:tag

# For npx servers
npx mcp-server-name --arg value

What to look for:

• Does the command fail with same error?
• Is the package/image available?
• Are arguments correct?

Debugging Checklist

Use this checklist systematically:

• Checked server-specific log for errors
• Examined stderr output (most revealing)
• Matched error to common patterns above
• Verified command syntax (uvx: package name first, Docker: -i not -it)
• Checked Docker isolation status (disabled for Docker commands?)
• Verified configuration file is valid JSON
• Tested command manually outside MCPProxy
• Triggered config reload (touch config file or restart mcpproxy)
• Waited 30 seconds for connection to initialize
• Checked main.log for global errors

If all checks pass and server still won't connect, see references/debugging-examples.md for real-world case studies.

Success Verification

After fixing the issue:

# 1. Check server status via API
curl -s "http://127.0.0.1:8080/api/v1/servers?apikey=YOUR_KEY" | python3 -m json.tool | grep -A 10 '"name": "SERVER_NAME"'

# Look for:
# "connected": true
# "status": "ready"
# "tool_count": > 0

# 2. Check server log for successful connection
tail -20 ~/Library/Logs/mcpproxy/server-SERVER_NAME.log | grep -i "connected\|ready\|discovered"

# 3. Verify tools are available
curl -s "http://127.0.0.1:8080/api/v1/tools?apikey=YOUR_KEY" | python3 -m json.tool | grep "SERVER_NAME:"

If connected: true and tool_count > 0, the issue is resolved.