Config MCP do Codex: como adicionar servidores MCP ao OpenAI Codex

O Codex é um agente de programação excelente por conta própria, mas só enxerga o que você lhe entrega: seus arquivos, seu shell e tudo o que o modelo já sabe. Os servidores MCP mudam isso. Ao adicionar um, o Codex pode consultar um banco de dados, ler um rastreador de problemas, pesquisar documentação de bibliotecas ou gerar uma imagem a partir do mesmo prompt em que você pede código. O detalhe é que a configuração fica em um arquivo TOML e em algumas flags da CLI, e uma única configuração errada faz o servidor simplesmente nunca aparecer.

Este artigo traz a config MCP do Codex exata para servidores locais e remotos, os comandos que a escrevem por você e correções para os erros que as pessoas mais encontram. As configurações e os padrões abaixo correspondem à documentação do OpenAI Codex a partir de outubro de 2026.

O que o MCP oferece ao Codex

O MCP, o Model Context Protocol, é um padrão aberto que permite a um cliente de IA chamar ferramentas expostas por um programa separado. Esse programa é o servidor. O Codex é o cliente. Cada servidor publica uma lista de ferramentas com nomes, descrições e esquemas de entrada, e o Codex decide, durante uma tarefa, quando vale a pena chamar uma delas.

Sem servidores, o Codex edita arquivos e executa comandos de shell. Com eles, a mesma sessão pode consultar seu banco de dados de staging, buscar uma especificação de design ou perguntar a um índice de documentação como uma biblioteca se comporta na versão mais recente, em vez de adivinhar com base nos dados de treinamento.

Duas formas de conectar

O Codex oferece dois tipos de servidor, e cada configuração que você escreve pertence a um deles.

Os servidores stdio locais iniciam quando o Codex começa e param quando ele é encerrado. Os servidores remotos já estão rodando em outro lugar, então o Codex só precisa do endereço e, normalmente, de uma credencial.

Por que vale a pena usar servidores

• Contexto atualizado. Servidores de documentação devolvem detalhes atuais de API, em vez do que o modelo memorizou meses atrás.
• Dados reais. Servidores de banco de dados e de rastreamento permitem que o Codex consulte uma tabela ou um chamado em vez de inventar um.
• Menos copiar e colar. Você deixa de passar texto entre abas do navegador e o terminal.
• Mídia no fluxo. Servidores de imagem e vídeo permitem que uma sessão de programação produza recursos sem sair do terminal.

💡 Dica: Comece com um ou dois servidores. Cada ferramenta que você expõe soma ao que o modelo lê antes de agir, e uma lista lotada de ferramentas torna as escolhas dele menos precisas.

Onde o Codex guarda as configurações de MCP

O Codex mantém as entradas de MCP no mesmo config.toml que usa para todas as outras configurações. Não há um arquivo separado de MCP para procurar.

O arquivo global

O local padrão é ~/.codex/config.toml. No Windows, isso corresponde a uma pasta .codex dentro do seu perfil de usuário. Os servidores definidos aqui ficam disponíveis em todos os projetos que você abrir. O aplicativo de desktop do ChatGPT, a CLI do Codex e a extensão para IDE leem esse mesmo arquivo, então um servidor que você adiciona uma vez aparece nos três.

O arquivo do projeto

Você também pode colocar um .codex/config.toml dentro de um repositório para limitar os servidores àquele projeto. O Codex só o lê em projetos confiáveis, o que impede que um repositório recém-clonado execute comandos na sua máquina sem que você perceba. Arquivos de projeto servem para servidores que só fazem sentido em uma base de código, como um banco de dados apontando para o schema de desenvolvimento daquele app, e permitem que a equipe compartilhe a configuração pelo controle de versão.

💡 Dica: Nunca faça commit de tokens. Referencie variáveis de ambiente pelo nome, como mostrado abaixo, e mantenha os valores no perfil do seu shell ou em um gerenciador de segredos.

Adicione um servidor pelo terminal

O caminho mais rápido é codex mcp add. Ele escreve a entrada TOML para você, o que elimina erros de digitação nos nomes das tabelas e nas aspas. Use-o primeiro e depois abra o arquivo para ajustar os detalhes.

Servidores stdio locais

Tudo o que vem depois do duplo hífen é o comando que o Codex vai executar:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Copiar prompt

Isso registra um servidor chamado context7, iniciado por meio de npx. Para passar variáveis de ambiente, coloque as flags --env antes do duplo hífen:

codex mcp add postgres --env DATABASE_URL=postgresql://localhost:5432/mydb -- node pg-mcp-server.js

Copiar prompt

Escolha nomes curtos, em minúsculas e sem espaços. O nome vira o nome da tabela TOML e identifica o servidor em todas as listagens.

Servidores HTTP remotos

Servidores remotos usam --url em vez de um comando no final:

codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN

Copiar prompt

--bearer-token-env-var nomeia a variável de ambiente que guarda o token. O token em si nunca é gravado em disco, apenas o nome da variável, o que é melhor do que colar um segredo em um cabeçalho. Exporte a variável no shell que inicia o Codex:

export GITHUB_PAT_TOKEN="paste-your-token-here"

Copiar prompt

Faça login com OAuth

Alguns servidores hospedados dispensam tokens estáticos e usam OAuth. Adicione o servidor com a URL e depois autentique-se:

codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear

Copiar prompt

login inicia o fluxo OAuth, geralmente no seu navegador, e armazena as credenciais resultantes. Quando um servidor documenta permissões específicas, adicione --scopes seguido de uma lista separada por vírgulas. Para remover as credenciais armazenadas, execute codex mcp logout linear.

Edite o config.toml manualmente

A CLI é rápida, mas os tempos limite, os filtros de ferramentas e as variáveis encaminhadas ficam no próprio arquivo. Cada entrada é uma tabela chamada mcp_servers.<name>, com um sublinhado e o plural.

Uma entrada de servidor local

É isso que o comando context7 mostrado antes produz:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Copiar prompt

Estas são as configurações que um servidor stdio aceita:

env define valores literais, enquanto env_vars encaminha variáveis que já existem no seu shell. Prefira env_vars para qualquer coisa secreta, para que o valor nunca apareça no arquivo:

[mcp_servers.postgres]
command = "node"
args = ["pg-mcp-server.js"]
cwd = "/home/dev/db-tools"
env_vars = ["DATABASE_URL"]

[mcp_servers.postgres.env]
LOG_LEVEL = "info"

Copiar prompt

Uma entrada de servidor remoto

Entradas remotas trocam command por url:

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_TOKEN"

Copiar prompt

Quando um serviço pede um cabeçalho personalizado em vez de um token bearer, use as duas tabelas de cabeçalhos. A segunda mantém os segredos fora do arquivo:

[mcp_servers.docs]
url = "https://docs.example.com/mcp"

[mcp_servers.docs.http_headers]
X-Team = "platform"

[mcp_servers.docs.env_http_headers]
X-Api-Token = "DOCS_API_TOKEN"

Copiar prompt

Tempos limite e filtros de ferramentas

Os dois tipos de servidor aceitam as mesmas configurações opcionais:

Uma entrada ajustada fica assim. Substitua os nomes das ferramentas pelos que /mcp lista para o seu servidor:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled_tools = ["tool_one", "tool_two"]

Copiar prompt

Uma lista de permissões é a escolha mais segura para servidores que podem gravar ou apagar dados. Use disabled_tools quando você confia em um servidor e quer bloquear apenas uma ou duas ferramentas arriscadas. Use required = true em execuções automatizadas, nas quais um servidor ausente deve interromper o trabalho de forma explícita, em vez de deixar o Codex continuar sem os dados.

💡 Dica: Defina enabled = false em vez de apagar uma entrada que você só precisa de vez em quando. As configurações permanecem no lugar, e você muda uma linha para reativá-la.

Confirme que o Codex enxerga o seu servidor

Adicionar um servidor não prova nada até que o Codex liste as ferramentas dele. Faça as duas verificações sempre.

Use /mcp dentro do Codex

Em uma sessão interativa, digite /mcp. O Codex mostra os servidores conectados e as ferramentas que cada um expõe. Se o seu servidor estiver ausente, ou aparecer sem ferramentas, nada mais importa até que isso seja resolvido. Reinicie a sessão depois de editar o arquivo para que o Codex leia as novas configurações.

Inspecione pelo shell

A família codex mcp gerencia tudo sem abrir um editor:

Adicione --json a list ou get quando um script precisar ler a saída. Quando o servidor aparecer, dê ao Codex uma tarefa que só esse servidor possa responder, como pedir a assinatura atual de uma função de biblioteca indexada pelo seu servidor de documentação.

Corrija os erros que você vai encontrar

A maioria das falhas se resume a um punhado de causas. Passe por elas nesta ordem.

O servidor nunca inicia

• Tempo limite de inicialização. A primeira execução de npx -y baixa o pacote, e 10 segundos costumam ser pouco. Aumente startup_timeout_sec para 30 ou mais.
• Comando não encontrado. O Codex inicia command por conta própria, então o programa precisa estar no PATH do shell que iniciou o Codex. Um caminho absoluto elimina a dúvida.
• Inicializadores do Windows. npx é um script no Windows, e um início direto pode falhar. Execute-o por meio de cmd:

[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp"]

Copiar prompt

• Saída poluída. Um servidor stdio deve escrever apenas mensagens do protocolo na saída padrão. Um banner de inicialização ou um print de depuração na stdout quebra o handshake, então envie os logs para o stderr.
• Falhas silenciosas. Adicione required = true durante os testes para que um servidor inoperante interrompa a sessão com um erro que você consiga ler.

Variáveis e autenticação falham

• Variáveis não exportadas. bearer_token_env_var e env_vars leem o ambiente do processo que iniciou o Codex. Uma variável definida em outra aba do terminal, ou em um aplicativo de desktop aberto pelo dock sem o perfil do seu shell, não será vista. Verifique com echo $GITHUB_PAT_TOKEN.
• Tokens recusados. Um erro 401 geralmente indica token expirado ou permissões ausentes. Para servidores OAuth, execute codex mcp logout <name> e depois codex mcp login <name> para obter uma sessão nova.
• Arquivo de projeto ignorado. Um .codex/config.toml em um projeto não confiável é pulado. Confie no projeto ou mova a entrada para o arquivo global.
• Ferramentas lentas. Se uma consulta longa é interrompida ao completar um minuto, aumente tool_timeout_sec acima do padrão de 60 segundos.

Conecte o Codex às ferramentas do PicassoIA

Sessões de programação muitas vezes precisam de imagens: uma imagem de destaque para uma landing page, um mockup de produto, um clipe curto para um README. O PicassoIA oferece seus modelos de geração por meio de uma API para desenvolvedores e de conexões MCP, então a mesma configuração do Codex pode solicitar mídia sem sair do terminal.

Estes são os fatos que vale conhecer antes de configurar:

• A URL base da API é https://api.picassoia.com/v1, e as credenciais começam com pia_sk_.
• Quatro modelos estão disponíveis pela API e pelo MCP: PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video e Seedance 2.5 Lite, que gera vídeo com áudio.
• Os trabalhos são assíncronos. Você cria uma predição, consulta o status dela e depois busca o resultado.
• Cada conta pode executar cinco previsões ao mesmo tempo, compartilhadas entre credenciais e conexões MCP, e os prompts podem chegar a 4.000 caracteres.
• As conexões MCP são gerenciadas em picassoia.com/en/mcp/accounts depois que você faz login, e o endereço do servidor aparece ali, e não no site público.

Quando tiver o endereço, o lado do Codex segue o padrão visto antes. Se a página fornecer uma URL remota, registre-a com codex mcp add picassoia --url <address> e adicione uma variável de token bearer caso ela peça um. Se ela fornecer um comando para executar localmente, use o formato stdio. Os requisitos de plano para acesso à API e ao MCP estão listados na página de preços, então confira-os antes de montar um fluxo de trabalho em cima disso.

Teste um modelo primeiro

Antes de automatizar qualquer coisa, teste um prompt manualmente para saber como é uma boa solicitação:

1. Abra a página do PicassoIA Image.
2. Escreva um prompt que informe o assunto, o cenário, a direção da luz e uma lente, como 35mm ou 85mm.
3. Gere a imagem e depois ajuste um detalhe por vez: o ângulo, a hora do dia ou a textura da superfície.
4. Envie a imagem vencedora para o PicassoIA Image Editor Pro quando precisar de correções pontuais em vez de refazer tudo.

Os modelos de chat também ajudam no trabalho de configuração. Cole um erro confuso em GPT 5.6 Sol ou Claude Sonnet 5 e pergunte a qual configuração TOML ele se refere. Ambos estão listados no PicassoIA para tarefas de programação, e uma segunda opinião custa pouco antes de você editar o arquivo.

Gere sua primeira imagem hoje

Agora você tem tudo para uma config MCP do Codex funcionando: os locais dos arquivos, os comandos da CLI, as configurações para os dois tipos de servidor, uma rotina de verificação e uma lista curta de correções. Adicione um servidor, confirme-o com /mcp e dê ao Codex uma tarefa real.

Se você quer colocar isso para trabalhar com imagens, abra o PicassoIA Image e escreva seu primeiro prompt. Descreva uma cena como um fotógrafo faria, com a luz, a lente e as texturas, e depois compare o resultado com uma versão do mesmo conceito no PicassoIA Video. Veja o catálogo completo em picassoia.com/en/all-models e descubra o que o Picasso IA pode criar para você.