Uma configuração prática do Docker MCP Toolkit, da primeira chave ativada até a primeira chamada de ferramenta. Ligue o Gateway, crie um perfil, escolha servidores assinados no Catálogo, conecte o Claude Desktop e o Claude Code e depois teste, depure e proteja cada contêiner.
A maioria das configurações de MCP começa do mesmo jeito. Você cola um bloco JSON no Claude Desktop, cola outro um pouco diferente no Claude Code, inicia um terceiro servidor pelo npx e deixa um token de acesso pessoal em texto puro dentro de um arquivo de configuração. Funciona até deixar de funcionar, e aí você passa a procurar em três arquivos o motivo de uma ferramenta ter sumido. O Docker MCP Toolkit substitui essa bagunça por uma única camada gerenciada: servidores que rodam como contêineres, um catálogo que os fornece e um único gateway com o qual o Claude conversa. Este artigo configura as três partes, conecta o Claude Desktop e o Claude Code e mostra como comprovar que cada ferramenta está ativa antes de você depender dela.
O Toolkit fica dentro do Docker Desktop. Ele executa servidores MCP como contêineres isolados, agrupa esses servidores em perfis com nome e expõe cada perfil para os clientes de IA pelo MCP Gateway. O Claude nunca inicia um servidor por conta própria. Ele conversa com um único endpoint, e o gateway encaminha cada requisição para o contêiner certo.
A vantagem prática é a separação. Seu editor, seu aplicativo de chat e seu agente de terminal apontam todos para o mesmo gateway, enquanto os servidores, suas credenciais e seus limites de recursos ficam sob controle do Docker, em vez de serem copiados para a configuração de cada cliente.
Pense no gateway como uma recepção. Toda requisição do Claude chega lá. O gateway escolhe o servidor que deve responder, inicia o contêiner dele quando necessário e devolve o resultado. A cadeia é curta: Claude, depois o gateway, depois o servidor em contêiner.
O gateway é de código aberto sob a licença MIT e é instalado como plugin da CLI do Docker, então docker mcp --help funciona assim que o Toolkit estiver ativo. Por padrão ele usa stdio, o que serve bem a um único cliente. Quando vários clientes precisam do mesmo gateway, execute-o sobre HTTP com streaming:
docker mcp gateway run --port 8080 --transport streaming
A camada de contêineres é o que deixa tudo organizado. Antes do Toolkit, cada servidor precisava do próprio ambiente de execução na sua máquina: Node para um, Python para o próximo, uma versão fixa para um terceiro. Um servidor em contêiner leva o próprio ambiente de execução consigo, então a única coisa que seu notebook precisa é o Docker. Atualizar ou remover um servidor deixa de ser uma tarefa chata de limpeza, porque ele nunca foi instalado no sistema hospedeiro.
Três termos sustentam todo o sistema, e cada comando deste artigo mexe em um deles.
| Peça | O que é | Onde você mexe |
|---|---|---|
| Catálogo | Uma coleção selecionada de servidores MCP empacotados como imagens de contêiner | Aba Catalog, docker mcp catalog ls |
| Perfil | Um grupo com nome de servidores e suas configurações para um projeto ou fluxo de trabalho | Aba Profiles, docker mcp profile list |
| Cliente | O aplicativo de IA que se conecta, como o Claude Desktop ou o Claude Code | Aba Clients, docker mcp client ls |
💡 Dica: um perfil pode atender vários clientes. Configure-o uma vez e todos os aplicativos conectados verão as mesmas ferramentas.
Você precisa de muito pouco, mas cada item importa.
O Toolkit exige o Docker Desktop 4.62 ou posterior, e ele só fica disponível com a chave beta ativada:
Agora aparece uma entrada MCP Toolkit no menu do Docker Desktop. Se você usou uma versão anterior do Toolkit, sua configuração existente é migrada para um perfil chamado default, então nada precisa ser refeito.
Dois clientes do Claude importam aqui. O Claude Desktop se conecta pela aba Clients com um único botão. O Claude Code se conecta pelo terminal com um comando. A documentação do Docker também lista Cursor, Zed e Visual Studio Code, o que ajuda quando sua equipe está dividida entre editores, já que todos conseguem ler o mesmo perfil.
💡 Dica: instale o Claude Code antes de começar se pretende usar o caminho pelo terminal. A verificação de conexão mais adiante neste tutorial depende do comando
claude mcp list.
Um perfil é um espaço de trabalho. Um perfil de pesquisa pode ter um servidor de notas e um servidor de busca, enquanto um perfil de lançamento tem o GitHub e um servidor de monitoramento. Mantê-los separados faz com que o Claude veja apenas as ferramentas que importam para a tarefa do momento.
Três layouts de perfil mostram a ideia:
O mesmo resultado leva dois comandos:
docker mcp profile create --name dev-tools --server catalog://<server-reference>
docker mcp profile list
Substitua o marcador pela referência de um servidor do seu catálogo. Mais três subcomandos cuidam da manutenção:
docker mcp profile server add e remove alteram a lista de servidores.docker mcp profile config <id> --set (ou --get, --del) edita as configurações de um perfil.docker mcp profile tools <id> --enable (ou --disable) controla quais ferramentas o Claude pode chamar.O Docker MCP Catalog reúne centenas de servidores. As próprias páginas do Docker dão a contagem como mais de 200 em um lugar e mais de 300 em outro, o que sugere que ele continua crescendo. Navegue pela aba Catalog, selecione Add to e escolha seu perfil. Servidores marcados como Configuration Required precisam de uma credencial ou de uma configuração antes de funcionar.
O catálogo mistura três tipos de servidor:
mcp no Docker Hub.
💡 Dica: equipes que precisam de mais controle podem criar um catálogo personalizado e importá-lo com
docker mcp catalog pull <oci-reference>, para que as pessoas vejam apenas servidores aprovados.
Comece pequeno. Cada servidor que você adiciona aumenta o número de descrições de ferramentas que o Claude precisa considerar, e um perfil enxuto mantém as escolhas dele mais precisas. Quatro pontos de partida fáceis:
| Objetivo | Servidor para testar | Tipo |
|---|---|---|
| Revisar pull requests | GitHub | Servidor remoto |
| Pesquisar notas da equipe | Notion | Servidor remoto |
| Conferir painéis | Grafana | Parceiro verificado |
| Inspecionar pagamentos | Stripe | Parceiro verificado |
Servidores remotos como o GitHub usam OAuth. O Docker abre uma janela do navegador, você aprova o acesso, e a credencial continua gerenciada pelo Docker em vez de ser colada em JSON. Para servidores que precisam de segredos estáticos, execute docker mcp secret --help para ver as opções, e docker mcp oauth --help para os comandos de autorização. A documentação do Docker acrescenta que requisições que carregam informações sensíveis são bloqueadas.
💡 Dica: nunca cole um token real em uma janela de chat ou em uma configuração compartilhada. Se um servidor pedir um, guarde-o pelo Toolkit.
Depois do reinício, abra o menu Search and tools. Uma entrada chamada MCP_DOCKER deve aparecer na lista e estar ativada. Todos os servidores do seu perfil agora ficam atrás dessa única entrada.
O Claude Code se conecta com um único comando:
docker mcp client connect claude-code --global
claude mcp list
O segundo comando deve imprimir uma linha como MCP_DOCKER: docker mcp gateway run - ✓ Connected. Para vincular um cliente a um só perfil, e não ao conjunto inteiro, o comando de conexão aceita --profile, como em docker mcp client connect vscode --profile my_profile. A forma geral é docker mcp client connect [client-name] --profile [id].
A flag --global aplica a conexão em todo o sistema, em vez de apenas ao projeto atual, o que combina com uma máquina pessoal. Deixe-a de fora quando um único repositório deve ter seu próprio conjunto de ferramentas.
Alguns clientes leem o próprio arquivo JSON e não têm botão de conexão. Adicione o gateway como um servidor stdio:
{
"servers": {
"MCP_DOCKER": {
"command": "docker",
"args": ["mcp", "gateway", "run", "--profile", "my_profile"],
"type": "stdio"
}
}
}
Use o nome da propriedade de nível superior documentado pelo seu cliente, porque alguns esperam mcpServers onde este trecho mostra servers. Uma única entrada substitui o conjunto de blocos de servidor separados que você tinha antes.
Como o gateway mantém suas ferramentas em um só lugar, nada disso precisa ser refeito quando você troca de cliente. Troque o Claude Desktop pelo Claude Code e o mesmo perfil acompanha você.
Execute um prompt que force uma chamada real de ferramenta. O exemplo do próprio Docker funciona bem: "Use the GitHub MCP server to show me my open pull requests." Se o Claude responder com dados da sua conta, a cadeia inteira está funcionando. Para uma visão mais técnica, docker mcp tools ls lista todas as ferramentas que o gateway expõe no momento, e docker mcp client ls mostra quais clientes estão conectados.
Teste em três etapas. Primeiro, peça ao Claude que liste as ferramentas que ele enxerga, o que confirma que o perfil foi carregado. Segundo, chame uma ferramenta somente leitura, como listar pull requests, o que confirma que as credenciais funcionam. Terceiro, e só então, tente uma ação que altere algo, e faça isso em um repositório descartável ou em um espaço de teste, para que um erro de digitação não custe nada.
O gateway precisa de cerca de 15 a 25 segundos para subir. A maioria dos momentos de "está quebrado" é, na verdade, "ainda está acordando". Espere meio minuto antes de mudar qualquer coisa e depois confira esta tabela.
| Sintoma | Causa provável | Correção |
|---|---|---|
MCP_DOCKER ausente no Claude Desktop | O aplicativo não foi reiniciado | Feche o Claude Desktop e abra-o de novo |
| Não conectado logo após a inicialização | O gateway ainda está iniciando | Aguarde e depois execute claude mcp list de novo |
| Servidor mostra Configuration Required | Credencial ausente ou aprovação OAuth pendente | Conclua a configuração na aba Catalog |
| Ferramentas de um servidor estão faltando | Ferramentas desativadas no perfil | Reative-as com docker mcp profile tools |
O Docker aplica proteções por padrão. Cada contêiner de servidor é limitado a 1 CPU e 2 GB de memória, o acesso ao sistema de arquivos permanece desligado até você concedê-lo, e as imagens do namespace mcp são assinadas digitalmente. Dentro de um perfil, uma lista de permissão de ferramentas restringe o que o Claude pode chamar.
Um recurso merece uma decisão deliberada. O Dynamic MCP permite que o Claude pesquise o catálogo e adicione um servidor no meio de uma conversa, usando ferramentas de gerenciamento que o gateway expõe: mcp-find, mcp-add, mcp-config-set, mcp-remove, mcp-exec e um code-mode experimental. Ele fica ativado automaticamente com o Toolkit. Se você quiser um conjunto fixo de ferramentas, desligue-o:
docker mcp feature disable dynamic-tools
Ligue-o de novo depois com docker mcp feature enable dynamic-tools.
O trabalho de configuração gera muito texto para ler: saídas de erro, comandos de perfil, anotações para colegas. O Claude Sonnet 5 fica na coleção Large Language Models da PicassoIA e cuida exatamente disso. Ele lê um pedido simples ou um stack trace, aceita uma captura de tela e devolve comandos ou correções que você pode conferir na documentação do Docker.
Este é o roteiro, da página à resposta:
claude mcp list.low é o padrão e pula o pensamento estendido, então as respostas chegam rápido. Suba para high ou max em um problema emaranhado que abrange vários arquivos.docker mcp exatos e uma frase de contexto."| Configuração | O que faz | Valor sugerido |
|---|---|---|
| Effort | Controla quanto raciocínio acontece antes da resposta | low para consultas, high para depuração |
| Image | Envia uma captura de tela junto com a requisição | Uma janela do Docker Desktop recortada |
| System Prompt | Define papel e tom para a sessão | Um breve briefing de assistente de DevOps |
| Max Tokens | Limita o tamanho da resposta | 8192 |
💡 Dica: o Sonnet 5 não consegue ver sua máquina. Trate os comandos dele como rascunhos e confira cada um na documentação do Docker antes de executar.
Outros modelos da plataforma se encaixam em hábitos diferentes. O Claude Fable 5 é voltado a tarefas de programação mais difíceis, o GPT 5.6 Sol enfrenta código complexo, o Gemini 3.1 Pro lida com perguntas multimodais longas, e o Kimi K2.6 foi feito para trabalho com agentes.
Quando o Claude alcança seus servidores por um único gateway, o próximo passo é dar a esses fluxos algo para analisar. Um servidor do GitHub pode rascunhar as notas de lançamento, um servidor do Notion pode guardar o briefing, e um modelo de imagem pode produzir a foto de cabeçalho na mesma sessão.
Cada foto deste artigo veio do P Image, gerada a partir de prompts longos e específicos que nomeiam a lente, a luz e as texturas da superfície. Para outros estilos, experimente o Flux 2 Pro, o GPT Image 2, o Seedream 4.5 ou o Nano Banana Pro. Quando uma imagem fixa precisar se mover, o Seedance 2.0, o Veo 3.1 e o Kling v3 Video transformam um prompt ou uma única imagem em clipes curtos.
Abra o Picasso IA, escolha um modelo e descreva uma cena como faria ao dar instruções a um fotógrafo: o assunto, o ângulo, a luz, a lente. Gere algumas variações, guarde a que combina com seu artigo e insira-a. A primeira imagem leva um minuto, e a segunda leva menos.
Escolha seu idioma
