Skip to content

docker-gateway-tutorial.md

Latest commit

 

History

History
336 lines (236 loc) · 7.75 KB

docker-gateway-tutorial.md

File metadata and controls

336 lines (236 loc) · 7.75 KB
Raw

Tutorial Docker Gateway MCP

PT | EN

Tutorial para configurar docker-gateway com servidores MCP rodando dentro de containers Docker.

Versão: 1.0.0 Última Atualização: 2026-01-28

O que é Docker Gateway?

Docker Gateway é um servidor MCP que atua como uma ponte entre o Claude Code e múltiplos servidores MCP rodando dentro de containers Docker.

Benefício Principal: Sem Custo Extra de Tokens

Quando MCPs rodam dentro do docker-gateway, suas definições de ferramentas ficam encapsuladas no container. Isso significa:

Configuração Custo de Tokens Definições de Tools no Contexto
Direto no ~/.claude.json Cada MCP adiciona tokens Sim, todos os schemas visíveis
Dentro do docker-gateway Sem custo extra Encapsulado no container

Por quê? O Claude Code só vê as ferramentas do docker-gateway (mcp-add, mcp-find, etc.), não as ferramentas individuais de cada MCP interno. As ferramentas reais são chamadas através do gateway.

Pré-requisitos

  • Docker Desktop 4.37+ instalado e rodando
  • Claude Code CLI instalado
  • Chaves de API para os serviços MCP desejados

Passo 1: Inicializar Docker MCP Toolkit

# Inicializar o sistema de catálogo
docker mcp catalog init

# Verificar inicialização
docker mcp catalog ls

Saída esperada:

docker-mcp: Docker MCP Catalog

O catálogo contém 313+ servidores MCP disponíveis para habilitar.

Passo 2: Navegar Servidores Disponíveis

# Listar todos os servidores disponíveis
docker mcp catalog show docker-mcp

# Buscar servidor específico
docker mcp catalog show docker-mcp | grep -i apify
docker mcp catalog show docker-mcp | grep -i exa

Passo 3: Habilitar Servidores MCP

# Habilitar servidores que você quer usar
docker mcp server enable apify-mcp-server
docker mcp server enable exa
docker mcp server enable context7

# Listar servidores habilitados
docker mcp server ls

Passo 4: Configurar Chaves de API

Método 1: Usando Docker MCP Secrets (pode ter bugs)

# Definir secrets
docker mcp secret set APIFY_TOKEN "seu-token-apify"
docker mcp secret set EXA_API_KEY "sua-chave-exa"

Método 2: Editar Arquivo de Catálogo Diretamente (workaround recomendado)

Devido a um bug conhecido (Dez 2025), secrets podem não ser passados corretamente para os containers.

Workaround: Edite ~/.docker/mcp/catalogs/docker-mcp.yaml diretamente:

# Encontre a entrada do seu MCP e adicione os valores de env
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: 'sua-chave-exa-aqui'

⚠️ Nota de segurança: Isso expõe credenciais em um arquivo local. Defina permissões adequadas:

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

Passo 5: Configurar Claude Code

Adicione docker-gateway ao ~/.claude.json:

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

Ou use o CLI do Claude:

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

Passo 6: Verificar Configuração

# Verificar ferramentas disponíveis através do gateway
docker mcp tools ls

# Saída esperada mostra ferramentas do gateway + servidores habilitados
# Exemplo: 58 tools (7 gateway + 51 dos servidores habilitados)

No Claude Code:

# Listar status dos MCPs
claude mcp list

# Deve mostrar:
# docker-gateway: docker mcp gateway run - ✓ Connected

Usando Docker Gateway

Ferramentas do Gateway Disponíveis

Ferramenta Descrição
mcp-add Adicionar servidor MCP à sessão atual
mcp-find Buscar servidores no catálogo
mcp-remove Remover servidor MCP da sessão
mcp-exec Executar ferramenta de servidor habilitado
mcp-config-set Configurar servidor MCP
code-mode Criar ferramentas JavaScript combinadas
mcp-create-profile Salvar estado atual do gateway

Acessando Ferramentas dos Servidores Habilitados

Uma vez habilitados, as ferramentas dos servidores ficam disponíveis através do gateway:

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

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

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

Exemplo de Configuração Completa

~/.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"]
    }
  }
}

Resultado

User MCPs (4 servidores):
├── desktop-commander  ✓ conectado
├── docker-gateway     ✓ conectado  (58 ferramentas dentro)
├── playwright         ✓ conectado
└── n8n-mcp           ✓ conectado

Dentro do docker-gateway:
├── apify-mcp-server   (7 ferramentas)
├── exa                (8 ferramentas)
├── context7           (2 ferramentas)
└── + ferramentas do gateway (7 ferramentas)

Solução de Problemas

Gateway Não Inicia

# Verificar se Docker está rodando
docker info

# Verificar logs do gateway
docker mcp gateway run --verbose

Ferramentas Mostrando "(N prompts)" ao Invés de "(N tools)"

Isso indica falha de autenticação. Use o workaround:

# Editar catálogo diretamente com credenciais hardcoded
nano ~/.docker/mcp/catalogs/docker-mcp.yaml

Servidor Não Encontrado

# Atualizar catálogo
docker mcp catalog update

# Verificar se servidor existe
docker mcp catalog show docker-mcp | grep -i "nome-do-servidor"

Resetar Tudo

# Desabilitar todos os servidores
docker mcp server reset

# Resetar catálogo
docker mcp catalog reset

# Reinicializar
docker mcp catalog init

Melhores Práticas

1. Use docker-gateway para MCPs baseados em API

Coloque estes dentro do docker-gateway (não precisam de acesso ao host):

  • Apify (APIs de web scraping)
  • EXA (APIs de busca)
  • Context7 (APIs de documentação)
  • Qualquer integração cloud/SaaS

2. Mantenha MCPs com acesso ao host diretos

Mantenha estes no ~/.claude.json diretamente:

  • desktop-commander (precisa acesso a arquivos/terminal do host)
  • playwright (precisa acesso ao browser do host)
  • MCPs de filesystem

3. Proteja suas credenciais

# Definir permissões restritivas
chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml
chmod 700 ~/.docker/mcp/

# Nunca commitar estes arquivos
echo "~/.docker/mcp/" >> ~/.gitignore_global

Documentação Relacionada

Tutorial Docker Gateway MCP v1.0.0 - AIOX Framework