Skip to content

docker-gateway-tutorial.md

Latest commit

 

History

History
336 lines (236 loc) · 7.01 KB

docker-gateway-tutorial.md

File metadata and controls

336 lines (236 loc) · 7.01 KB

Docker Gateway MCP Tutorial

EN | PT

Tutorial for setting up docker-gateway with MCP servers running inside Docker containers.

Version: 1.0.0 Last Updated: 2026-01-28

What is Docker Gateway?

Docker Gateway is an MCP server that acts as a bridge between Claude Code and multiple MCP servers running inside Docker containers.

Key Benefit: No Extra Token Cost

When MCPs run inside docker-gateway, their tool definitions are encapsulated in the container. This means:

Configuration Token Cost Tool Definitions in Context
Direct in ~/.claude.json Each MCP adds tokens Yes, all tool schemas visible
Inside docker-gateway No extra cost Encapsulated in container

Why? Claude Code only sees the docker-gateway tools (mcp-add, mcp-find, etc.), not the individual tools of each MCP inside. The actual tools are called through the gateway.

Prerequisites

  • Docker Desktop 4.37+ installed and running
  • Claude Code CLI installed
  • API keys for desired MCP services

Step 1: Initialize Docker MCP Toolkit

# Initialize the catalog system
docker mcp catalog init

# Verify initialization
docker mcp catalog ls

Expected output:

docker-mcp: Docker MCP Catalog

The catalog contains 313+ MCP servers available to enable.

Step 2: Browse Available Servers

# List all available servers
docker mcp catalog show docker-mcp

# Search for specific server
docker mcp catalog show docker-mcp | grep -i apify
docker mcp catalog show docker-mcp | grep -i exa

Step 3: Enable MCP Servers

# Enable servers you want to use
docker mcp server enable apify-mcp-server
docker mcp server enable exa
docker mcp server enable context7

# List enabled servers
docker mcp server ls

Step 4: Configure API Keys

Method 1: Using Docker MCP Secrets (may have bugs)

# Set secrets
docker mcp secret set APIFY_TOKEN "your-apify-token"
docker mcp secret set EXA_API_KEY "your-exa-api-key"

Method 2: Edit Catalog File Directly (recommended workaround)

Due to a known bug (Dec 2025), secrets may not be passed to containers correctly.

Workaround: Edit ~/.docker/mcp/catalogs/docker-mcp.yaml directly:

# Find your MCP entry and add env values
apify-mcp-server:
  env:
    - name: APIFY_TOKEN
      value: 'apify_api_xxxxxxxxxxxxx'
    - name: TOOLS
      value: 'actors,docs,apify/rag-web-browser'

exa:
  env:
    - name: EXA_API_KEY
      value: 'your-exa-api-key-here'

⚠️ Security note: This exposes credentials in a local file. Set proper file permissions:

chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml

Step 5: Configure Claude Code

Add docker-gateway to ~/.claude.json:

{
  "mcpServers": {
    "docker-gateway": {
      "type": "stdio",
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

Or use the Claude CLI:

claude mcp add docker-gateway -s user -- docker mcp gateway run

Step 6: Verify Setup

# Check tools available through gateway
docker mcp tools ls

# Expected output shows gateway tools + enabled server tools
# Example: 58 tools (7 gateway + 51 from enabled servers)

In Claude Code:

# List MCP status
claude mcp list

# Should show:
# docker-gateway: docker mcp gateway run - ✓ Connected

Using Docker Gateway

Available Gateway Tools

Tool Description
mcp-add Add MCP server to current session
mcp-find Search servers in catalog
mcp-remove Remove MCP server from session
mcp-exec Execute tool from enabled server
mcp-config-set Configure MCP server settings
code-mode Create combined JavaScript tools
mcp-create-profile Save current gateway state

Accessing Tools from Enabled Servers

Once servers are enabled, their tools are available through the gateway:

# Apify tools (via docker-gateway)
mcp__docker-gateway__search-actors
mcp__docker-gateway__call-actor
mcp__docker-gateway__apify-slash-rag-web-browser

# EXA tools (via docker-gateway)
mcp__docker-gateway__web_search_exa
mcp__docker-gateway__company_research

# Context7 tools (via docker-gateway)
mcp__docker-gateway__resolve-library-id
mcp__docker-gateway__query-docs

Complete Example Configuration

~/.claude.json

{
  "mcpServers": {
    "desktop-commander": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"]
    },
    "docker-gateway": {
      "type": "stdio",
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}

Result

User MCPs (4 servers):
├── desktop-commander  ✓ connected
├── docker-gateway     ✓ connected  (58 tools inside)
├── playwright         ✓ connected
└── n8n-mcp           ✓ connected

Inside docker-gateway:
├── apify-mcp-server   (7 tools)
├── exa                (8 tools)
├── context7           (2 tools)
└── + gateway tools    (7 tools)

Troubleshooting

Gateway Not Starting

# Check Docker is running
docker info

# Check gateway logs
docker mcp gateway run --verbose

Tools Showing as "(N prompts)" Instead of "(N tools)"

This indicates authentication failure. Use the workaround:

# Edit catalog directly with hardcoded credentials
nano ~/.docker/mcp/catalogs/docker-mcp.yaml

Server Not Found

# Update catalog
docker mcp catalog update

# Verify server exists
docker mcp catalog show docker-mcp | grep -i "server-name"

Reset Everything

# Disable all servers
docker mcp server reset

# Reset catalog
docker mcp catalog reset

# Reinitialize
docker mcp catalog init

Best Practices

1. Use docker-gateway for API-based MCPs

Put these inside docker-gateway (no host access needed):

  • Apify (web scraping APIs)
  • EXA (search APIs)
  • Context7 (documentation APIs)
  • Any cloud/SaaS integrations

2. Keep host-access MCPs direct

Keep these in ~/.claude.json directly:

  • desktop-commander (needs host file/terminal access)
  • playwright (needs host browser)
  • filesystem MCPs

3. Secure your credentials

# Set restrictive permissions
chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml
chmod 700 ~/.docker/mcp/

# Never commit these files
echo "~/.docker/mcp/" >> ~/.gitignore_global

Related Documentation

Docker Gateway MCP Tutorial v1.0.0 - AIOX Framework