Skip to content

docker-gateway.md

Latest commit

 

History

History
335 lines (274 loc) · 6.93 KB

docker-gateway.md

File metadata and controls

335 lines (274 loc) · 6.93 KB

🌐 Docker MCP Gateway Deep Dive

Understanding the magic behind Docker's MCP Gateway - the centralized orchestrator for all your MCP servers.

What is the Docker MCP Gateway?

The Docker MCP Gateway is a special MCP server that acts as a proxy/orchestrator for multiple MCP servers. Think of it as a "meta-server" that:

  • Aggregates multiple MCP servers into one connection
  • Manages Docker containers on-demand
  • Handles authentication and secrets
  • Provides unified access to all tools

Architecture Overview

       Claude/Cursor/LM Studio
                ↓
         [Single Connection]
                ↓
        Docker MCP Gateway
                ↓
    ┌───────────┬────────────┬───────────┐
    ↓           ↓            ↓           ↓
 Dice MCP   Weather MCP  Database MCP  [More...]

Key Benefits

1. Simplified Configuration

Without Gateway:

  • Configure each server individually
  • Manage multiple connections
  • Update each client separately

With Gateway:

  • One configuration entry
  • Single connection point
  • Centralized management

2. Dynamic Container Management

Containers run only when needed:

# Before tool use
$ docker ps
CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES
# (empty)

# During tool use
$ docker ps  
CONTAINER ID   IMAGE              COMMAND                  STATUS
ab3f5c7d9e2f   dice-mcp-server   "python dice_server.py"  Up 1 second

# After tool use
$ docker ps
# (empty again)

3. Centralized Secret Management

# Set secrets once, use everywhere
docker mcp secret set API_KEY="abc123"

# All servers can access via environment variables
os.environ.get("API_KEY")

Transport Modes

Standard I/O (Local)

Default mode for local clients:

docker mcp gateway run --transport stdio
  • Direct process communication
  • No network overhead
  • Maximum security
  • Perfect for desktop apps

Server-Sent Events (Network)

For remote access and automation:

docker mcp gateway run --transport sse --port 8811
  • HTTP/HTTPS transport
  • Access from anywhere
  • Integration with n8n, Make, Zapier
  • Web-based clients

Running the Gateway

As Part of Docker Desktop

Automatically managed when MCP Toolkit is enabled:

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "~/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--registry=/mcp/registry.yaml",
        "--transport=stdio"
      ]
    }
  }
}

Standalone Container

Run independently for production:

# Pull the gateway image
docker pull docker/mcp-gateway

# Run with SSE transport
docker run -d \
  --name mcp-gateway \
  -p 8811:8811 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.docker/mcp:/mcp \
  docker/mcp-gateway \
  --transport sse \
  --port 8811

Catalog System

Structure

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  server-name:
    description: "What it does"
    title: "Display Name"
    type: server
    image: server-image:latest
    tools:
      - name: tool1
      - name: tool2
    secrets:
      - name: API_KEY
        env: SERVER_API_KEY

Multiple Catalogs

# Load multiple catalogs
docker mcp gateway run \
  --catalog=/mcp/catalogs/docker-mcp.yaml \
  --catalog=/mcp/catalogs/custom.yaml \
  --catalog=/mcp/catalogs/team.yaml

Registry Management

The registry tracks installed servers:

registry:
  dice:
    ref: ""
  weather:
    ref: ""
  database:
    ref: ""

Manage via CLI:

# List registered servers
docker mcp server list

# Add to registry
docker mcp server add my-server

# Remove from registry  
docker mcp server remove my-server

Remote Access Setup

Local Network Access

# Start gateway with network transport
docker run -d \
  --name mcp-gateway \
  -p 0.0.0.0:8811:8811 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.docker/mcp:/mcp \
  docker/mcp-gateway \
  --transport sse

# Access from local network
http://192.168.1.100:8811

n8n Integration

As shown in the video:

  1. Start gateway with SSE transport
  2. In n8n, add MCP node
  3. Configure endpoint: http://YOUR_IP:8811
  4. Select available tools
  5. Build automation workflows!

Security Considerations

  • Use HTTPS in production
  • Implement authentication
  • Restrict network access
  • Use Docker secrets for sensitive data

Advanced Configuration

Custom Port

docker mcp gateway run --transport sse --port 9000

Custom Config Path

docker mcp gateway run \
  --config=/custom/path/config.yaml \
  --registry=/custom/path/registry.yaml

Environment Variables

docker run -e DEBUG=true \
  -e LOG_LEVEL=debug \
  docker/mcp-gateway

Performance Optimization

Container Caching

First run pulls image, subsequent runs are instant:

# Pre-pull images for faster first run
docker pull dice-mcp-server
docker pull weather-mcp-server

Resource Limits

# In catalog definition
registry:
  heavy-server:
    image: heavy-mcp:latest
    resources:
      limits:
        memory: "512M"
        cpu: "0.5"

Monitoring & Debugging

View Gateway Logs

# If running as container
docker logs mcp-gateway

# If via Docker Desktop
docker logs $(docker ps | grep mcp-gateway | awk '{print $1}')

List Active Connections

# See what's currently running
docker ps | grep mcp

Debug Mode

docker mcp gateway run --transport stdio --debug

Troubleshooting

Gateway Won't Start

  • Check Docker daemon is running
  • Verify socket permissions
  • Ensure no port conflicts (for SSE mode)

Servers Not Available

  • Verify catalog syntax
  • Check registry entries
  • Ensure Docker images exist

Connection Issues

  • Check firewall rules
  • Verify network settings
  • Test with curl: curl http://localhost:8811/health

Best Practices

  1. Use catalogs for organization

    • docker-mcp.yaml for official
    • custom.yaml for personal
    • team.yaml for shared

  2. Secure production deployments

    • Use TLS/HTTPS
    • Implement auth middleware
    • Run on private networks

  3. Monitor resource usage

    • Set container limits
    • Clean up unused images
    • Monitor logs for errors

Future Possibilities

As mentioned in the video:

  • Cloud-hosted gateways
  • Multi-user support
  • Tool marketplace
  • Enterprise features
  • Kubernetes integration

Related Resources

"The Docker MCP Gateway is like USB-C for AI tools" - NetworkChuck