Até aqui, o Codex trabalhou com o que estava dentro do repositório: arquivos, comandos, testes e histórico do Git. Neste capítulo você vai aprender a ampliar esse alcance com o MCP, ligando o agente a um banco de dados, à documentação de uma biblioteca, a um navegador de verdade e ao seu sistema de tarefas. Ao final, você saberá declarar servidores no config.toml, decidir em quais deles confiar e confirmar que o agente realmente usou a ferramenta em vez de inventar a resposta.
O que é o MCP
MCP é a sigla em inglês de Model Context Protocol, ou Protocolo de Contexto de Modelo. É um padrão aberto que define como um programa externo oferece capacidades a um agente de inteligência artificial. Quem oferece as capacidades é chamado de servidor MCP. Quem consome é chamado de cliente MCP. O Codex é um cliente.
A vantagem do padrão é a mesma de qualquer protocolo: escreve-se o servidor uma vez e ele passa a funcionar com qualquer cliente compatível. Um servidor que consulta o PostgreSQL serve ao Codex, serve a outros agentes e não precisa de código específico para cada um.
Na prática, um servidor MCP expõe três tipos de coisa. Ferramentas, que são funções que o agente pode chamar com argumentos e que devolvem um resultado, como executar uma consulta ou abrir uma página. Recursos, que são conteúdos que o agente pode ler, como um arquivo de documentação. E prompts prontos, que são modelos de pedido que o servidor sugere. Na prática, o Codex consome principalmente as ferramentas: o suporte a recursos e a prompts varia conforme a versão do cliente, então não conte com eles sem testar.
Como o Codex conversa com um servidor
Quando você inicia uma sessão, o Codex sobe cada servidor MCP declarado na configuração e pergunta quais ferramentas ele oferece. Cada ferramenta chega com nome, descrição e a lista de argumentos que aceita. Esse catálogo entra no contexto do modelo. A partir daí, quando o pedido exige algo que uma ferramenta resolve, o agente chama a ferramenta, recebe o resultado e continua o raciocínio com esse dado em mãos.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
Existem duas formas de conexão. A local, em que o Codex executa um programa na sua máquina e conversa com ele pela entrada e saída padrão. E a remota, em que o Codex fala com um servidor pela rede, por HTTP, normalmente com um token de autenticação. A escolha muda a configuração, mas não muda o modo de uso.
Declarando servidores no config.toml
Os servidores ficam no mesmo arquivo config.toml que você já usa para modelo, nível de raciocínio e perfis. Cada servidor vira uma tabela chamada mcp_servers seguida do nome que você escolher. Esse nome é livre e aparece nos registros da sessão.
[mcp_servers.banco]
command = "npx"
args = [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://codex_leitor@localhost:5432/loja"
]
startup_timeout_sec = 20
[mcp_servers.tarefas]
url = "https://mcp.exemplo.com/mcp"
bearer_token_env_var = "TAREFAS_TOKEN"
No primeiro caso, o Codex executa um comando local com os argumentos indicados. No segundo, ele se conecta a um endereço na rede e busca o token em uma variável de ambiente, em vez de deixar o segredo escrito no arquivo. Vale um aviso: o suporte a servidores remotos por HTTP é recente e, em boa parte das versões do Codex, depende de habilitar o cliente experimental, com a linha experimental_use_rmcp_client igual a verdadeiro no config.toml; confira a documentação da versão que você tem instalada antes de concluir que errou o endereço ou o token. Essa diferença é importante: o config.toml costuma estar em um repositório de configurações pessoais, e credencial dentro dele acaba vazando.
Há também um atalho pela linha de comando. O comando codex mcp add, seguido do nome e do comando do servidor, escreve o bloco para você. O comando codex mcp list mostra o que está declarado, e codex mcp remove apaga. Se você quer um servidor disponível só em certos trabalhos, declare-o dentro de um perfil de configuração e ative com a opção de perfil na hora de abrir a sessão.
Quatro integrações que valem a pena
Consultar um banco de dados
Com um servidor de banco conectado, você pode pedir ao agente que verifique a realidade dos dados antes de escrever código. Por exemplo: descobrir se uma coluna aceita valores nulos, contar quantos registros violariam uma nova restrição, ou conferir o nome exato de uma tabela antes de gerar uma consulta. Isso ataca diretamente um tipo comum de alucinação, que é o modelo supor um esquema plausível e errado.
Use sempre um usuário de banco somente de leitura e apontando para uma cópia de desenvolvimento. Nunca conecte o agente ao banco de produção com permissão de escrita. Duas ressalvas sobre o exemplo mostrado antes: o servidor de referência de PostgreSQL do projeto MCP foi arquivado, então verifique qual servidor está de fato sendo mantido antes de adotá-lo, e fixe a versão do pacote em vez de deixar o npx baixar sempre a mais recente. Mantenha também a senha do banco fora do config.toml, passando-a por variável de ambiente.
Acessar documentação atualizada
Servidores de documentação buscam a referência oficial de uma biblioteca e devolvem o trecho relevante. Isso resolve o problema do conhecimento congelado do modelo, que pode ter aprendido a versão antiga de uma API. Um pedido típico é: consulte a documentação da versão dois da biblioteca e me diga qual é a assinatura atual desta função antes de alterar o código.
Controlar um navegador
Servidores de automação de navegador, como os baseados no Playwright, permitem que o agente abra a aplicação, clique em elementos, preencha formulários e leia o que apareceu na tela. Com isso, o Codex consegue verificar uma correção de interface do mesmo jeito que você verificaria: abrindo a página. Combine com o que você já aprendeu sobre critérios de aceitação. Peça, por exemplo, que ele abra o endereço local, faça login com um usuário de teste e confirme que a mensagem de erro aparece ao enviar o formulário vazio. Use sempre ambiente de teste e credenciais descartáveis, nunca contas reais nem o ambiente de produção, porque tudo o que aparece na tela e os dados digitados passam pelo contexto do modelo.
Integrar com o sistema de tarefas
Servidores para rastreadores de tarefas e de incidentes deixam o agente ler o cartão que descreve a demanda. Em vez de você copiar e colar o texto do chamado, basta dizer: leia a tarefa de número quatrocentos e doze, resuma os critérios de aceitação e proponha um plano. O resto do fluxo continua o mesmo que você já conhece.
Permissões e confiança
Aqui está o ponto mais delicado do capítulo. Um servidor MCP local é um programa comum rodando na sua máquina, iniciado pelo Codex com as suas permissões de usuário. Ele não está contido pelas mesmas restrições de pasta e de rede que se aplicam aos comandos do agente. Instalar um servidor MCP é, em termos de risco, equivalente a instalar qualquer outro software: você está confiando no autor.
Adote quatro cuidados fixos:
- Prefira servidores oficiais da própria ferramenta ou mantidos por projetos conhecidos, e fixe a versão em vez de puxar sempre a mais recente.
- Dê o menor privilégio possível. Usuário somente leitura no banco, token com escopo restrito a um projeto, credencial separada da sua conta pessoal.
- Guarde segredos em variáveis de ambiente e nunca dentro do config.toml versionado.
- Lembre que texto vindo de fora, como o corpo de um chamado ou o conteúdo de uma página, pode conter injeção de prompt. Trate resultado de ferramenta como dado, não como ordem, e continue revisando os diffs.
Como confirmar que a ferramenta foi usada
Um agente pode responder com confiança sem ter consultado nada. Três verificações resolvem isso.
A primeira é olhar a sessão. Quando o Codex chama uma ferramenta MCP, ele mostra a chamada com o nome do servidor, o nome da ferramenta e os argumentos, do mesmo modo que mostra comandos executados. Se você pediu uma consulta ao banco e nenhuma chamada apareceu, a resposta veio da memória do modelo.
A segunda é pedir a prova junto com a resposta. Diga no pedido: informe qual ferramenta você chamou, com quais argumentos, e cole o resultado bruto antes da sua conclusão. É a mesma ideia da pergunta de controle que você já usa para validar explicações de código.
A terceira é conferir o inventário no começo da sessão. Peça a lista de ferramentas disponíveis. Se o servidor não subiu, por erro de comando, token ausente ou tempo esgotado na inicialização, o Codex costuma mostrar um aviso de falha no começo da sessão, mas é fácil perder essa mensagem: as ferramentas daquele servidor simplesmente não aparecem na lista e o agente segue adiante respondendo de memória. Aumentar o tempo de inicialização costuma resolver servidores que baixam pacotes na primeira execução.
Higiene: poucos servidores ligados por vez
Cada ferramenta declarada ocupa espaço no contexto, porque nome, descrição e argumentos são enviados ao modelo. Uma dúzia de servidores ativos consome contexto útil e ainda aumenta a chance de o agente escolher a ferramenta errada. Mantenha ligados apenas os servidores da tarefa atual e organize o resto em perfis: um perfil com banco e navegador para trabalho em aplicação web, outro apenas com documentação para leitura de código. Registre no AGENTS.md quando o agente deve preferir uma ferramenta, com uma linha do tipo: antes de escrever consultas, confira o esquema pelo servidor de banco.
Recapitulando
O MCP é o padrão que permite ao Codex usar ferramentas externas, e o Codex atua como cliente desses servidores. A configuração vive no config.toml, em blocos mcp_servers, com comando local ou endereço remoto mais token vindo de variável de ambiente. As integrações mais úteis são banco de dados em modo leitura, documentação atualizada, controle de navegador para verificar interface e leitura de tarefas. Servidores MCP rodam com as suas permissões, então escolha fontes confiáveis, use o menor privilégio e desconfie de texto externo. E confirme sempre, pelo registro da sessão e pedindo a saída bruta, que a ferramenta foi de fato chamada. Poucos servidores ligados por vez mantêm o contexto limpo e as escolhas do agente previsíveis.
