🔗 O que MCP resolve
MCP padroniza como um agente descobre e chama ferramentas de fora. O servidor anuncia o que sabe fazer; o agente chama com argumentos e recebe um retorno estruturado. A diferença prática em relação a "escreva um script": o agente vê o resultado de cada chamada e ajusta na hora, em vez de descobrir o erro só no fim.
💡 Antes de escrever um servidor, procure um pronto
A maioria dos aplicativos populares já tem servidor MCP publicado. Escrever o seu é trabalho de dias; conectar um pronto é um comando. Audite antes de usar, com o mesmo critério de skill de terceiro (módulo 2.1).
✓ Caso para MCP
- ✓Software com API própria (Blender, DAW, CAD)
- ✓Banco de dados que você consulta muito
- ✓Serviço interno com muitas operações
- ✓Qualquer coisa em que o retorno guia o próximo passo
✗ Caso para skill ou script
- ✗Procedimento que só usa arquivos e terminal
- ✗Tarefa de uma vez só
- ✗Regra de estilo ou de processo
- ✗Coisa que a linha de comando já resolve
⚙️ Conectar um servidor MCP no Codex
O CLI tem um grupo de comandos para isso. Servidores locais recebem o comando de execução depois de --; servidores remotos usam --url. Variáveis de ambiente vão em --env e só valem para servidores locais. A documentação do Codex traz os detalhes da sua versão.
Copie e rode
Adicionar, listar e inspecionar um servidor MCP local
# servidor local (stdio): tudo depois de -- é o comando que sobe o servidor
codex mcp add <NOME> --env <CHAVE>=<VALOR> -- <COMANDO> <ARGS>
# servidor remoto (HTTP)
codex mcp add <NOME> --url https://<HOST>/<CAMINHO>
# conferir
codex mcp list
codex mcp get <NOME>
# remover quando não usar mais
codex mcp remove <NOME>Copie e rode
Exemplo concreto: conectar o Blender MCP (servidor Python instalado via uv/pipx)
# 1. instale o servidor conforme o README do projeto
# https://github.com/ahujasid/blender-mcp
# 2. registre no Codex (ajuste o comando ao que o README indicar)
codex mcp add blender -- uvx blender-mcp
# 3. abra o Blender e ative o complemento do lado do aplicativo
# (o servidor fala com o Blender aberto; sem o Blender rodando, as chamadas falham)
codex mcp list✓ Servidor local (stdio)
- ✓Aplicativo que roda na sua máquina (Blender, editor, banco local)
- ✓Precisa de acesso a arquivos ou processos seus
- ✓Latência mínima, sem rede
- ✓Você controla a versão do servidor
✗ Servidor remoto (--url)
- ✗Serviço da equipe, compartilhado entre pessoas
- ✗Exige autenticação e sai da sua máquina
- ✗Depende de rede: trate queda como caso esperado
- ✗Não use --env: variáveis só valem para stdio
| Sintoma | Causa | Ação |
|---|---|---|
| Ferramentas não aparecem | Servidor não subiu | `codex mcp get |
| Sobe e cai | Dependência ou versão | Rode o comando do servidor isolado no terminal; leia o stderr |
| Conecta mas falha toda chamada | App alvo fechado | Abra o aplicativo e ative o complemento do lado dele |
| Pede permissão a cada chamada | Política de aprovação | Aprovação a pedido é o certo aqui; não passe para "never" |
🏎️ Uma tarefa longa de verdade
O truque de tarefas longas é pedir marcos: pontos em que o agente para, mostra evidência e continua. Assim você corrige cedo. Um jogo de corrida 3D tem marcos naturais: cena modelada, assets exportados, pista carregada no jogo, controles respondendo.
Copie e rode
Tarefa longa com marcos: jogo de corrida 3D usando Blender por MCP
Use o servidor MCP do Blender (Blender já está aberto) e o código desta pasta.
Resultado: um protótipo jogável de corrida no navegador, com uma pista 3D modelada no Blender, um veículo controlável e colisão com as bordas da pista.
Marcos (pare e me mostre a evidência em cada um antes de seguir):
M1. Cena do Blender com a pista modelada. Evidência: render de topo em ./art/m1-pista.png e lista de objetos da cena.
M2. Assets exportados em glTF para ./public/models/. Evidência: `ls -la` da pasta e tamanho de cada arquivo.
M3. Pista carregada na engine do jogo, câmera posicionada. Evidência: screenshot do jogo rodando.
M4. Veículo controlável com colisão. Evidência: screenshot + como rodar localmente.
Escopo: não instale dependências novas sem me perguntar. Não altere nada fora de ./art, ./public/models e ./src/game.
Tempo esperado: isto pode levar de 20 a 60 minutos. Se algo travar por mais de 5 minutos na mesma etapa, pare e me diga o que travou.⚠️ Tempo longo não é sinal de progresso
Uma tarefa que roda 45 minutos pode estar tentando a mesma chamada falha desde o minuto 4. A cláusula "se travar 5 minutos na mesma etapa, pare e me diga" transforma silêncio em relatório.
🔁 Retomar: permissões, reinícios, "continue"
Tarefas com MCP pedem permissão quando tocam algo novo e às vezes o aplicativo reinicia. A regra é a mesma do módulo 1.3: volte à mesma conversa e mande continuar. Com marcos, a retomada é ainda mais barata, porque o estado está registrado em evidências no disco.
Copie e rode
Retomar uma tarefa longa deixando o estado explícito
continue.
Antes de agir: confira o que já existe no disco (./art, ./public/models, ./src/game), me diga qual foi o último marco concluído com evidência real e qual é o próximo passo. Não refaça marcos já concluídos.Quando o servidor MCP cai
Confirme as duas pontas
Aplicativo aberto? Complemento ativo? `codex mcp list` mostra o servidor?
Teste uma chamada barata
"liste os objetos da cena" antes de retomar a tarefa pesada.
Retome na mesma conversa
"continue" com o pedido de conferir o disco primeiro.
Se o contexto sumiu
Cole o contrato original e a lista de marcos concluídos. Custa um prompt, não 40 minutos.
💡 Uma conversa por tarefa longa, com pin
Tarefa de MCP compartilhando conversa com outra tarefa faz "continue" retomar a errada. Pin na criação (módulo 1.1) resolve.
🧭 Escolher entre MCP, skill e computer use
| Situação | Caminho | Por quê |
|---|---|---|
| App com MCP pronto, uso recorrente | MCP | Retorno estruturado, ciclo curto, sem screenshot |
| App sem API, uso único | Computer use | Setup zero; a fragilidade não importa numa vez |
| App sem API, uso semanal | Computer use uma vez, depois ferramenta | Mapeie com a tela, gere a linha de comando, rode barato |
| Procedimento seu, ferramentas que já existem | Skill | Não falta capacidade, falta método |
| App com API mas sem MCP | Script + skill | Mais simples que escrever um servidor |
🧪 Prática: conectar um MCP e rodar uma tarefa com marcos
Roteiro (40 min)
Escolha um servidor
Blender se você modela; ou um MCP de banco de dados, de navegador, do seu serviço interno. Prefira um que você consegue verificar.
Conecte e liste
`codex mcp add ... && codex mcp list`. Depois pergunte ao agente quais ferramentas ele vê.
Chamada barata primeiro
Uma operação de leitura. Se falhar aqui, não adianta delegar a tarefa grande.
Tarefa com 3 marcos
Escreva o contrato com evidência por marco e a cláusula de travamento de 5 minutos.
Confira cada marco
Abra as evidências. Libere o próximo só depois.
Limpe
`codex mcp remove` se foi um teste. Servidor conectado é superfície de ataque parada.
Copie e rode
Chamada barata de verificação, antes de qualquer tarefa pesada
Usando o servidor MCP <NOME>: faça a operação de leitura mais simples que ele oferece e me mostre o retorno bruto. Não modifique nada.🧪 Teste rápido do módulo
Três perguntas. Clique numa opção para ver a resposta.
1. Por que uma tarefa longa via MCP converge melhor que um script único?
2. O servidor MCP conecta mas toda chamada falha. Primeira hipótese:
3. Você opera a mesma busca num site sem API toda semana. Melhor caminho:
📋 Resumo do módulo
Próximo módulo:
2.3 - Cota, custo e orquestração