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

Real-World MCPProxy Debugging Examples

This file contains detailed walkthroughs of actual debugging sessions, providing concrete examples of how to diagnose and fix MCPProxy issues.

Example 1: Buildkite Server - Docker Isolation Conflict

Date: October 2025 Symptom: Buildkite MCP server failing to connect with "the input device is not a TTY" error Server Type: Docker-based MCP server (ghcr.io/buildkite/buildkite-mcp-server:latest)

Initial Configuration

{
  "name": "buildkite",
  "protocol": "stdio",
  "command": "docker",
  "args": [
    "run",
    "--pull=always",
    "-q",
    "-i",
    "--rm",
    "-e",
    "BUILDKITE_API_TOKEN",
    "ghcr.io/buildkite/buildkite-mcp-server:latest",
    "stdio"
  ],
  "env": {
    "BUILDKITE_API_TOKEN": "${keyring:buildkite_token}"
  },
  "enabled": true,
  "quarantined": false
}

Diagnostic Process

1. Ran diagnostic script:

   ~/.claude/skills/mcpproxy-debug/scripts/diagnose_server.sh buildkite
   

2. Key findings from stderr:

   "the input device is not a TTY"
   

3. Pattern recognition: This error typically indicates:

   • Either -it flags being used (but config showed -i only)
   • OR Docker isolation wrapping a Docker command (Docker-in-Docker)

4. Checked Docker isolation status:

   • Global docker_isolation.enabled was true
   • Server had no explicit isolation override
   • MCPProxy was wrapping the Docker command in another container

Root Cause

Docker isolation was enabled globally, and MCPProxy was attempting to run:

docker run [isolation-wrapper-args] docker run [server-args] ...

This creates a Docker-in-Docker situation where the inner Docker command can't allocate a TTY because it's running inside a container.

Solution

Added explicit isolation disable to the server configuration:

{
  "name": "buildkite",
  "protocol": "stdio",
  "command": "docker",
  "args": [
    "run",
    "--pull=always",
    "-q",
    "-i",
    "--rm",
    "-e",
    "BUILDKITE_API_TOKEN",
    "ghcr.io/buildkite/buildkite-mcp-server:latest",
    "stdio"
  ],
  "env": {
    "BUILDKITE_API_TOKEN": "${keyring:buildkite_token}"
  },
  "isolation": {
    "enabled": false
  },
  "enabled": true,
  "quarantined": false
}

Verification

After restarting mcpproxy:

1. Process inspection:

   ps aux | grep mcpproxy
   

   Confirmed the buildkite server was now running directly:

   docker run --cidfile ... --pull=always -q -i --rm -e BUILDKITE_API_TOKEN ghcr.io/buildkite/buildkite-mcp-server:latest stdio
   

2. Connection verification:

   ~/.claude/skills/mcpproxy-debug/scripts/diagnose_server.sh buildkite
   

   Output showed:

   Successfully connected and initialized
   server_name: "buildkite-mcp-server"
   server_version: "0.7.2"
   tool_count: 28
   

3. No more TTY errors in recent logs

Key Lessons

1. Docker isolation auto-skip may fail: The intended automatic skip for Docker commands didn't work in this case
2. Always explicitly disable isolation for Docker commands: Best practice to prevent Docker-in-Docker issues
3. Stderr is the most revealing: The "TTY" error in stderr immediately pointed to the issue
4. The diagnostic script is highly effective: Automated pattern detection caught the problem immediately

Applicable to Other Servers

This same issue and solution applies to any Docker-based MCP server:

• ghcr.io/github/github-mcp-server
• ghcr.io/sooperset/mcp-atlassian:latest
• Any custom Docker image serving MCP

Template solution:

{
  "name": "any-docker-mcp-server",
  "command": "docker",
  "args": ["run", "-i", "--rm", "-e", "ENV_VAR", "image:tag"],
  "isolation": {
    "enabled": false
  }
}

Example 2: API Key Mismatch After Restart

Symptom: API calls return "Invalid or missing API key" after restarting mcpproxy

Diagnostic Process

1. Check config file API key:

   grep '"api_key"' ~/.mcpproxy/mcp_config.json
   

   Result: "api_key": "d380462e333f25a1c61bad1d5d3f673277d5167dcdba18954effc7d6f0401c37"

2. API call with config key fails:

   curl -H "X-API-Key: d380462e333f25a1c61bad1d5d3f673277d5167dcdba18954effc7d6f0401c37" \
     http://127.0.0.1:8080/api/v1/servers
   

   Result: {"success": false, "error": "Invalid or missing API key"}

3. Check logs for API key source:

   grep -i "api.*key" ~/Library/Logs/mcpproxy/main.log | tail -10
   

   Result: API key authentication enabled | {"source": "environment variable", "api_key_prefix": "9fc1****ee1c"}

Root Cause

The MCPPROXY_API_KEY environment variable was set (likely by the tray app), which takes precedence over the config file. The actual API key was 9fc15eb0... (different from config).

Solution

Use the environment variable key or unset the environment variable:

Option 1: Use the actual key from logs

# Extract from log prefix
grep "api_key_prefix" ~/Library/Logs/mcpproxy/main.log | tail -1

Option 2: Unset environment variable to use config file

unset MCPPROXY_API_KEY
pkill mcpproxy
open /Applications/mcpproxy.app

Key Lesson

Always check both environment variables and config file when debugging API authentication. Environment variables take precedence.

Pattern: Missing Package Name in uvx/npx

Error: unexpected argument '--some-flag' found

Example:

// WRONG
{"command": "uvx", "args": ["--local-timezone", "America/New_York"]}

// CORRECT
{"command": "uvx", "args": ["mcp-server-time", "--local-timezone", "America/New_York"]}

Diagnostic: Check stderr in server logs for "unexpected argument" errors, then verify args array has package name first.

Pattern: Context Deadline Exceeded

Error: MCP initialize failed: transport error: context deadline exceeded

Common Causes:

1. Missing package name (uvx/npx) - check stderr for "unexpected argument"
2. Docker TTY issue - check stderr for "not a TTY"
3. Server crashed on startup - check stderr for stack traces
4. Environment variables missing - check stderr for "missing" or "required"

Diagnostic Workflow:

# 1. Check stderr for actual error
grep "stderr" ~/Library/Logs/mcpproxy/server-{SERVER_NAME}.log | tail -20

# 2. Check if server started at all
grep "Starting connection" ~/Library/Logs/mcpproxy/server-{SERVER_NAME}.log | tail -5

# 3. Check Docker container if isolation enabled
docker ps | grep mcpproxy
docker logs CONTAINER_ID