Guia de Configuração Docker MCP

PT

Guia para configurar servidores MCP (Model Context Protocol) baseados em Docker com AIOS.

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

Pré-requisitos

Antes de configurar Docker MCP, certifique-se de ter:

Docker Desktop instalado e em execução
Node.js 18+ instalado
Projeto AIOS inicializado
Chaves de API para os serviços MCP desejados (EXA, Apify, etc.)

Instalação

Passo 1: Instalar Docker MCP Toolkit


# Instalar o Docker MCP Toolkit
docker mcp install
 
# Verificar instalação
docker mcp --version

Passo 2: Inicializar Configuração MCP


# Criar estrutura MCP global
aios mcp setup

Isso cria:

~/.aios/mcp/ - Diretório de configuração MCP
~/.aios/mcp/global-config.json - Arquivo de configuração principal
~/.aios/mcp/servers/ - Configurações de servidores individuais
~/.aios/credentials/ - Armazenamento seguro de credenciais

Passo 3: Adicionar Servidores MCP


# Adicionar servidores a partir de templates
aios mcp add context7
aios mcp add exa
aios mcp add github

Configuração

Arquitetura MCP

AIOS usa Docker MCP Toolkit como a infraestrutura MCP principal:


┌─────────────────────────────────────────────────────────┐
│                    Claude Code                           │
│                         │                                │
│    ┌────────────────────┼────────────────────┐          │
│    │                    │                    │          │
│    ▼                    ▼                    ▼          │
│ playwright      docker-gateway           native tools   │
│ (direto)        (container MCPs)         (Read, Write)  │
│                         │                                │
│              ┌──────────┼──────────┐                    │
│              ▼          ▼          ▼                    │
│            EXA     Context7     Apify                   │
│         (busca)    (docs)     (scraping)               │
└─────────────────────────────────────────────────────────┘

Direto no Claude Code (global ~/.claude.json)

MCP	Propósito
playwright	Automação de navegador, screenshots, testes web
desktop-commander	Operações de container Docker via docker-gateway

Dentro do Docker Desktop (via docker-gateway)

MCP	Propósito
EXA	Busca web, pesquisa, análise de empresas/concorrentes
Context7	Consulta de documentação de bibliotecas
Apify	Web scraping, Actors, extração de dados de redes sociais

Arquivos de Configuração

global-config.json:


{
  "version": "1.0",
  "servers": {
    "context7": {
      "type": "sse",
      "url": "https://mcp.context7.com/sse",
      "enabled": true
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "${EXA_API_KEY}"
      },
      "enabled": true
    }
  },
  "defaults": {
    "timeout": 30000,
    "retries": 3
  }
}

MCPs Disponíveis

Context7 (Consulta de Documentação)


# Adicionar Context7
aios mcp add context7
 
# Uso
mcp__context7__resolve-library-id
mcp__context7__query-docs

Usar para:

Consulta de documentação de bibliotecas
Referência de API para pacotes/frameworks
Obter documentação atualizada para dependências

EXA (Busca Web)


# Adicionar EXA
aios mcp add exa
 
# Definir chave de API
export EXA_API_KEY="your-api-key"
 
# Uso
mcp__exa__web_search_exa
mcp__exa__get_code_context_exa

Usar para:

Buscas web por informações atuais
Pesquisa e consulta de documentação
Pesquisa de empresas e concorrentes
Encontrar exemplos de código online

Apify (Web Scraping)


# Adicionar Apify
aios mcp add apify
 
# Definir token de API
export APIFY_TOKEN="your-token"
 
# Uso
mcp__docker-gateway__search-actors
mcp__docker-gateway__call-actor

Usar para:

Web scraping para redes sociais (Instagram, TikTok, LinkedIn)
Extrair dados de sites de e-commerce
Coleta automatizada de dados de qualquer site
Navegação web habilitada para RAG para contexto de IA

GitHub (Integração de API)


# Adicionar GitHub
aios mcp add github
 
# Definir token
export GITHUB_TOKEN="your-token"

Usar para:

Operações de API do GitHub
Gerenciamento de repositório
Manipulação de PR e issues

Playwright (Automação de Navegador)


# Adicionar Playwright
aios mcp add puppeteer

Usar para:

Automação de navegador
Capturar screenshots de páginas web
Interagir com sites
Web scraping e testes

Comandos CLI

Comandos de Configuração


# Inicializar configuração MCP global
aios mcp setup
 
# Forçar recriação (fazer backup do existente)
aios mcp setup --force

Gerenciamento de Servidores


# Adicionar servidor a partir de template
aios mcp add <server-name>
 
# Adicionar com configuração customizada
aios mcp add custom-server --config='{"command":"npx","args":["-y","package"]}'
 
# Remover servidor
aios mcp remove <server-name>
 
# Habilitar/desabilitar servidores
aios mcp enable <server-name>
aios mcp disable <server-name>

Status e Listagem


# Listar servidores configurados
aios mcp list
 
# Mostrar status detalhado
aios mcp status
 
# Sincronizar para o projeto
aios mcp sync

Variáveis de Ambiente

Definindo Variáveis

macOS/Linux:


export EXA_API_KEY="your-api-key"
export GITHUB_TOKEN="your-github-token"
export APIFY_TOKEN="your-apify-token"

Windows (PowerShell):


$env:EXA_API_KEY = "your-api-key"
$env:GITHUB_TOKEN = "your-github-token"
$env:APIFY_TOKEN = "your-apify-token"

Variáveis Persistentes

Adicione ao seu perfil de shell (~/.bashrc, ~/.zshrc, ou ~/.profile):


export EXA_API_KEY="your-api-key"
export GITHUB_TOKEN="your-github-token"
export APIFY_TOKEN="your-apify-token"

Armazenamento Seguro de Credenciais


# Adicionar credencial
aios mcp credential set EXA_API_KEY "your-api-key"
 
# Obter credencial
aios mcp credential get EXA_API_KEY
 
# Listar credenciais (mascaradas)
aios mcp credential list

Solução de Problemas

Problemas Comuns

Problema	Solução
Permissão negada	Execute o terminal como Administrador (Windows) ou use sudo
Servidor não iniciando	Verifique comando e args, verifique se o pacote está instalado
Variável de ambiente não encontrada	Defina a variável ou use armazenamento de credenciais
Erros de timeout	Aumente o timeout na configuração
Conexão recusada	Verifique a URL e acesso à rede

Bug de Secrets do Docker MCP (Dez 2025)

Problema: O armazenamento de secrets do Docker MCP Toolkit (docker mcp secret set) e interpolação de template ([{...]}) NÃO funcionam corretamente. Credenciais não são passadas para os containers.

Sintomas:

docker mcp tools ls mostra “(N prompts)” em vez de “(N tools)”
Servidor MCP inicia mas falha na autenticação
Saída verbose mostra -e ENV_VAR sem valores

Solução alternativa: Edite ~/.docker/mcp/catalogs/docker-mcp.yaml diretamente:


{ mcp-name }:
  env:
    - name: API_TOKEN
      value: 'actual-token-value-here'

Exemplo - Apify:


apify-mcp-server:
  env:
    - name: TOOLS
      value: 'actors,docs,apify/rag-web-browser'
    - name: APIFY_TOKEN
      value: 'apify_api_xxxxxxxxxxxxx'

Nota: Isso expõe credenciais em um arquivo local. Proteja as permissões do arquivo e nunca faça commit deste arquivo.

Correções Comuns


# Resetar configuração global
aios mcp setup --force
 
# Limpar cache
rm -rf ~/.aios/mcp/cache/*
 
# Verificar configuração
aios mcp status --verbose
 
# Testar servidor manualmente
npx -y @modelcontextprotocol/server-github

Governança MCP

Importante: Todo gerenciamento de infraestrutura MCP é tratado exclusivamente pelo Agente DevOps (@devops / Felix).

Operação	Agente	Comando
Buscar catálogo MCP	DevOps	`*search-mcp`
Adicionar servidor MCP	DevOps	`*add-mcp`
Listar MCPs habilitados	DevOps	`*list-mcps`
Remover servidor MCP	DevOps	`*remove-mcp`
Configurar Docker MCP	DevOps	`*setup-mcp-docker`

Outros agentes (Dev, Architect, etc.) são consumidores de MCP, não administradores. Se for necessário gerenciamento de MCP, delegue para @devops.

Prioridade de Seleção de Ferramentas

Sempre prefira ferramentas nativas do Claude Code sobre servidores MCP:

Tarefa	USE ISSO	NÃO ISSO
Ler arquivos	`Read` tool	docker-gateway
Escrever arquivos	`Write` / `Edit` tools	docker-gateway
Executar comandos	`Bash` tool	docker-gateway
Buscar arquivos	`Glob` tool	docker-gateway
Buscar conteúdo	`Grep` tool	docker-gateway
Listar diretórios	`Bash(ls)` ou `Glob`	docker-gateway

Quando Usar docker-gateway

Use docker-gateway apenas quando:

Usuário explicitamente diz “use docker” ou “use container”
Usuário explicitamente menciona “Desktop Commander”
Tarefa especificamente requer operações de container Docker
Acessando MCPs rodando dentro do Docker (EXA, Context7)
Usuário pede para executar algo dentro de um container Docker

Documentação Relacionada

Guia de Configuração Docker MCP do Synkra AIOS v4.0