Servidores MCP no Codex CLI: adicione, configure e autentique
Servidores MCP entregam novas ferramentas ao Codex — documentação atualizada, seu banco de dados, seus repositórios GitHub. Este passo a passo roda codex mcp add para um servidor stdio local, troca para um servidor remoto com --url e OAuth, inspeciona as entradas do config.toml por trás de ambos e mostra as checagens que provam que um servidor funciona de verdade.
A versão curta
- O Codex lê servidores MCP de ~/.codex/config.toml (global) ou .codex/config.toml (projeto). Cada entrada é uma tabela [mcp_servers.<name>] com command/args para servidores stdio locais ou url para os remotos.
- codex mcp add context7 -- npx -y @upstash/context7-mcp instala um servidor stdio sem tocar no arquivo; codex mcp add <name> --url https://mcp.example.com/mcp registra um remoto.
- Servidores remotos autenticam no navegador na primeira conexão (o Codex imprime Detected OAuth support e abre a tela de consentimento) ou depois via codex mcp login <name>.
- Verifique com /mcp dentro do TUI ou codex mcp list no shell. O Codex 0.160.1 ainda preserva SYSTEMROOT, TEMP e TMP ao iniciar servidores stdio remotos com variáveis de ambiente remotas.
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
Canal: Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
Canal: Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
Canal: Snyk9:14
Connect Codex to an MCP server — official documentation
Documentação oficial: developers.openai.com/codex
Cada comando, caminho de arquivo e chave de configuração desta página foi verificado contra a documentação oficial do Codex MCP; os vídeos acima são as fontes visuais e factuais, incluindo as telas de consentimento OAuth e o menu MCP do app desktop.
As capturas de tela pertencem aos seus criadores, com links diretos para os timestamps exatos. Nenhum quadro com rosto é usado.
Adicionar servidores MCP ao Codex, passo a passo
Parte 1 — Seu primeiro servidor stdio
- 1
Escolha um servidor na documentação oficial de MCP
Abra developers.openai.com/codex/mcp — a própria documentação do Codex guarda a sintaxe de comando atual, e a CLI e a extensão de IDE compartilham essa configuração. Os docs listam servidores prontos que valem um teste: Context7 para documentação de bibliotecas em tempo real, Figma, GitHub e mais. Há centenas de servidores MCP; para um primeiro teste, escolha algo somente leitura como o Context7.
A página oficial Connect Codex to an MCP server, com a sintaxe do codex mcp add e um exemplo de Context7 pronto para copiar.Ver em 0:20 - 2
Instale com codex mcp add
Copie o exemplo e rode no terminal: codex mcp add context7 -- npx -y @upstash/context7-mcp. Tudo depois do travessão duplo é o comando que lança o processo do servidor. O Codex responde "Added global MCP server 'context7'" — global significa que foi para a sua config no nível de usuário e fica disponível em todo projeto.
Um comando, sem editar arquivo: a CLI confirma que o servidor entrou na config global.Ver em 0:45 - 3
Veja o que a CLI escreveu no config.toml
O codex mcp add é só um gerador para o ~/.codex/config.toml. Abra o arquivo e você encontra [mcp_servers.context7] com command = "npx" e args = ["-y", "@upstash/context7-mcp"]. Entradas também podem ser escritas à mão: adicione uma tabela env para chaves de API, ou defina startup_timeout_sec (padrão 10) e tool_timeout_sec (padrão 60) para servidores lentos. A edição manual é justamente o caminho que os vídeos do Snyk e do Net Ninja no cartão de fontes seguem.
- 4
Abra o Codex e verifique com /mcp
Inicie o codex no seu projeto e digite /mcp. O painel MCP Tools lista cada servidor configurado com status, o comando exato de execução e as ferramentas que expõe — o Context7 mostra query_docs e resolve-library-id. Qualquer coisa faltando aqui significa que a entrada caiu no arquivo errado ou falhou ao iniciar.
O painel /mcp dentro do TUI do Codex: context7 habilitado e as duas ferramentas listadas pelo nome.Ver em 1:05
Parte 2 — Use, depois vá para o remoto
- 5
Faça um prompt que realmente usa o servidor
Ferramentas MCP são chamadas sob demanda, então peça algo que precise delas: "Use o Context7 para checar a documentação atual de setup do Tailwind CSS". O Codex resolve a biblioteca, puxa a docs pelo servidor MCP e cita as fontes na resposta. Ver as chamadas de ferramenta rolando é a prova de que o servidor funciona de ponta a ponta.
A resposta do Codex cita as URLs exatas da documentação do Context7 que ele puxou pelo servidor MCP.Ver em 1:30 - 6
Adicione um servidor remoto com --url
Muitos provedores também hospedam seu servidor MCP remotamente — sem processo local, sem npx. Registre um com codex mcp add context7 --url https://mcp.context7.com/mcp. O Codex detecta suporte a OAuth automaticamente, imprime "Detected OAuth support. Starting OAuth flow..." e abre o navegador para autorizar. No config.toml, a entrada é só url = "https://mcp.context7.com/mcp" sob [mcp_servers.context7].
O fluxo remoto completo em um terminal: o add com --url, a detecção de OAuth, a URL de autorização e o Successfully logged in.Ver em 2:22 - 7
Aprove a tela de consentimento OAuth
O navegador pergunta se o Codex pode acessar sua conta em nome do provedor. Revise os escopos pedidos, clique em Allow e o terminal confirma "Successfully logged in". Para servidores sem fluxo OAuth, autentique à parte com codex mcp login <name>; servidores com token usam bearer_token_env_var apontando para uma variável de ambiente.
A tela de consentimento do Context7: revise os escopos que o Codex pede e Allow.Ver em 2:02 - 8
Limite um servidor a um projeto com .codex/config.toml
Servidores que só fazem sentido num repositório — como o DBHub, um servidor stdio que fala com seu banco de dados — pertencem à config do projeto. Crie uma pasta .codex no repositório, adicione um config.toml com a entrada [mcp_servers.dbhub] e passe sua string de conexão pelo argumento --dsn (ajuste do exemplo Postgres dos docs para MySQL ou o que você rodar). Commite, e os colegas ganham o mesmo servidor; a pasta precisa ser um projeto confiável para carregar.
Um .codex/config.toml de projeto: o DBHub roda via stdio com o DSN do banco do repositório nos args.Ver em 3:30
Parte 3 — Servidores de verdade e controle no dia 2
- 9
Consulte seu banco de dados pelas ferramentas MCP
Com o DBHub configurado, pergunte ao Codex sobre o banco: "Encontre o banco de dados do Petco e explique as tabelas", depois "Qual é o produto mais vendido?". O Codex chama as ferramentas describe_table e execute_sql do servidor, pede permissão antes de rodar SQL e responde com números reais dos seus dados. É o caminho mais rápido para depurar schemas e validar dados num backend.
O Codex rodou a ferramenta execute_sql do dbhub e respondeu com o produto mais vendido e sua receita.Ver em 4:40 - 10
Conecte o GitHub com o servidor MCP remoto dele
O README do github/github-mcp-server documenta o setup para o Codex: adicione uma entrada [mcp_servers.github] com url = "https://api.githubcopilot.com/mcp/" e autentique via OAuth ou exportando um personal access token como variável de ambiente (crie um PAT fine-grained em GitHub Settings, Developer settings, concedendo Administration e Contents). Servidores remote-first como este e o servidor MCP do Figma seguem o mesmo padrão do passo 6.
O guia de instalação do servidor MCP do GitHub: a entrada do Codex CLI mais a nota de autenticação OAuth/PAT.Ver em 5:22 - 11
Reinicie e ponha as ferramentas para trabalhar
Reinicie o codex e repare no banner: "Starting servers (0/3): context7, dbhub, github". Agora uma instrução única como "Forka o repositório openai/codex para a minha conta" basta — o Codex escolhe a ferramenta fork do GitHub, pede aprovação e executa. Sem setup por tarefa: as ferramentas simplesmente fazem parte de toda sessão daqui em diante.
- 12
Gerencie servidores com codex mcp list e o app desktop
codex mcp list imprime cada servidor configurado direto do shell; remover um significa apagar o bloco dele do config.toml e rodar o comando de novo para confirmar. O app desktop e a extensão de IDE leem o mesmo ~/.codex/config.toml, então servidores instalados aqui aparecem na página Settings, MCP servers do app desktop, com toggles liga/desliga.
As configurações de MCP servers do app desktop do Codex: context7, dbhub e github com toggles, além de servidores recomendados.Ver em 7:30
stdio local vs servidores MCP remotos no Codex
Ambos os tipos moram nas mesmas tabelas [mcp_servers.*] e aparecem no mesmo painel /mcp — a diferença é onde o servidor roda e como autentica. Escolha por servidor, não por projeto.
- 1stdio local: o Codex lança um processo por conta própria com command e args — tipicamente npx ou um binário. Roda na sua máquina, então alcança serviços de localhost como um banco de desenvolvimento (foi assim que o DBHub consultou o MySQL no passo a passo), mas você provê o runtime e as atualizações.
- 2Remoto: o Codex conversa com uma url hospedada por streamable HTTP. Nenhum processo para manter vivo e a autenticação é centralizada — OAuth por padrão, ou bearer_token_env_var e http_headers para setups com token. O próprio exemplo dos docs é [mcp_servers.figma] com url = "https://mcp.figma.com/mcp".
- 3stdio executado remotamente: um meio-termo experimental. Definir experimental_environment = "remote" numa entrada stdio move a execução dela para um executor remoto, com env_vars decidindo quais variáveis viajam — incluindo entradas marcadas com source = "remote". É esse caminho que o Codex 0.160.1 endureceu.
- 4Escopo: codex mcp add sempre escreve no ~/.codex/config.toml global; servidores específicos de projeto vão para o .codex/config.toml dentro do repositório (só projetos confiáveis). Global para ferramentas que você quer em todo lugar, projeto para qualquer coisa que carregue credenciais específicas do ambiente.
- 5Controles que valem para ambos: startup_timeout_sec (padrão 10) e tool_timeout_sec (padrão 60) para servidores lentos, enabled/disabled_tools para permitir apenas o que o Codex pode chamar, e required = true se um servidor precisa subir ou o Codex deve se recusar a iniciar.
Um padrão prático: servidores de documentação somente leitura como o Context7 podem ser globais; qualquer coisa que toque credenciais ou dados — DBHub, GitHub com PAT — pertence à config do projeto, onde pode ser revisada e revogada junto com o repositório.
Configurado mas não funciona: os suspeitos de sempre
A maioria das falhas de MCP no Codex é problema de escopo, timeout ou autenticação — nessa ordem. Percorra esta lista antes de mexer no servidor em si.
- 1Servidor não aparece no /mcp: confira qual arquivo você editou. Entradas globais vivem em ~/.codex/config.toml; as de projeto, em .codex/config.toml e só para projetos confiáveis. Rode codex mcp list do shell para ver o que o Codex enxerga de fato.
- 2Servidor dá timeout na inicialização: o startup_timeout_sec padrão é 10 segundos, e um download frio de npx de um pacote grande facilmente passa disso. Pré-instale o pacote ou aumente o startup_timeout_sec da entrada.
- 3Chamadas de ferramenta falham com 401/403: a credencial está ausente ou venceu. Rode codex mcp login <name> para servidores OAuth, ou defina bearer_token_env_var e exporte a variável. Depois de corrigir, o /mcp deve mostrar o servidor como enabled de novo.
- 4Servidor stdio remoto quebra com erros estranhos de Windows: antes do 0.160.1, iniciar um servidor stdio MCP remoto com variáveis de ambiente remotas explicitamente configuradas podia descartar SYSTEMROOT, TEMP e TMP, quebrando o ambiente de partida do executor Windows. Atualize para 0.160.1 ou mais recente.
- 5Servidor sobe mas as respostas vêm erradas ou vazias: muitos servidores hospedados precisam da própria chave de API mesmo com OAuth — o Context7, por exemplo, quer uma chave de API via env. Confira na doc do provedor o nome exato da env e adicione na tabela env da entrada.
Duas alavancas úteis durante o debug: defina required = true num servidor de que você depende para o Codex nunca iniciar sem ele em silêncio, e enabled = false para desligar um sem apagar a config.