Docker MCP Gateway Remote Connection - Complete Solutions Guide

📋 System Overview

Initial Problem

• Direct connection attempts failed with "Invalid session ID" errors
• Root cause: Docker MCP Gateway uses Streamable HTTP protocol
• Claude Desktop expects stdio transport
• Network separation between tower PC and mini PC

docker mcp gateway run --port 8080 --transport streaming

npm install -g supergateway

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "npx",
      "args": [
        "supergateway",
        "--streamableHttp", "http://192.168.0.18:8080/mcp",
        "--outputTransport", "stdio"
      ]
    }
  }
}

Tower PC                          Mini PC (192.168.0.18)
--------                          ---------------------
Claude Desktop                    Docker MCP Gateway
     |                                   ^
     |                                   |
     v                                   |
supergateway  <--streamableHttp-->  (port 8080)
   (stdio)         over network

docker mcp gateway run --port 8080 --transport streaming

# Basic tunnel
ssh -L 8080:localhost:8080 [email protected]

# Keep tunnel running in background
ssh -N -f -L 8080:localhost:8080 [email protected]

# With auto-reconnection (requires autossh)
autossh -N -f -L 8080:localhost:8080 [email protected]

npm install -g supergateway

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "npx",
      "args": [
        "supergateway",
        "--streamableHttp", "http://localhost:8080/mcp",
        "--outputTransport", "stdio"
      ]
    }
  }
}

Tower PC                                    Mini PC (192.168.0.18)
--------                                    ---------------------
Claude Desktop                              Docker MCP Gateway:8080
     |                                              ^
     v                                              |
supergateway --> localhost:8080  ===SSH TUNNEL===>  port 8080
   (stdio)      ^                                   |
            (appears local)                   (actually remote)

📊 Comparison of Solutions

🔧 Troubleshooting Guide

Common Issues and Solutions

1. "Invalid session ID" Error

• Ensure Docker MCP Gateway is running with --transport streaming
• Verify supergateway is using --streamableHttp not --sse
• Check the endpoint is /mcp not /sse

2. Connection Refused

• Verify Docker MCP Gateway is running: docker ps | grep mcp
• Check firewall settings on mini PC
• Test connectivity: ping 192.168.0.18
• Test port: telnet 192.168.0.18 8080

3. SSH Tunnel Issues

• Verify SSH access: ssh [email protected]
• Check if tunnel is active: ps aux | grep ssh | grep -v grep
• Kill existing tunnels: pkill -f "ssh -L 8080"
• Test tunnel: curl http://localhost:8080/mcp

4. Verify Which Connection Method is Being Used

Check Claude Desktop logs to see the connection URL:

• If logs show [supergateway] - streamableHttp: http://localhost:8080/mcp → Using SSH tunnel ✅
• If logs show [supergateway] - streamableHttp: http://192.168.0.18:8080/mcp → Direct connection

# Verify SSH tunnel process is running
ps aux | grep ssh | grep 8080
# Should show: ssh -N -f -L 8080:localhost:8080 [email protected]

# Test both connections to compare
curl http://localhost:8080/mcp     # Through SSH tunnel
curl http://192.168.0.18:8080/mcp  # Direct connection

5. Supergateway Not Found

• Verify installation: npm list -g supergateway
• Reinstall if needed: npm install -g supergateway
• Check npm path: npm root -g
• To uninstall: npm uninstall -g supergateway

Debug Commands

# On Mini PC - Check Docker MCP Gateway
docker ps | grep mcp
docker logs [container-name] --tail 50

# On Tower PC - Test connectivity
curl -X POST http://192.168.0.18:8080/mcp \
  -H "Content-Type: application/json" \
  -d '[{"jsonrpc":"2.0","method":"ping","id":0}]'

# Verify SSH tunnel is active (if using Solution 2)
ps aux | grep "ssh -N -f -L 8080:localhost:8080 [email protected]"

# Check Claude Desktop logs
# Look for: [supergateway] - streamableHttp: http://localhost:8080/mcp (SSH tunnel)
# Or: [supergateway] - streamableHttp: http://192.168.0.18:8080/mcp (Direct)

📚 Appendix

A. Key Technologies

• Docker MCP Gateway v2.0.1: Docker's implementation of Model Context Protocol server
• Streamable HTTP: Modern transport protocol for MCP (replaced SSE)
• supergateway: Protocol bridge package (GitHub)
• stdio: Standard input/output transport used by Claude Desktop

B. File Locations

• Claude Desktop Config: Platform-specific location for claude_desktop_config.json
• npm global packages: npm root -g to find location

C. Managing Components

# Remove supergateway
npm uninstall -g supergateway

# Stop Docker MCP Gateway
docker stop [container-name]

# Stop SSH tunnel
pkill -f "ssh -N -f -L 8080:localhost:8080 [email protected]"
# Or kill by process ID
ps aux | grep ssh | grep 8080  # Find the PID
kill [PID]

# Clean npm cache if needed
npm cache clean --force

D. Important Notes