Como conectar seu primeiro servidor MCP no Codex (2026)
O Codex é um cliente MCP - ele não tem modo servidor. A forma mais rápida de adicionar um servidor: codex mcp add <name> -- <command> pela CLI, ou Settings → MCP servers → Add server no app Desktop / menu de engrenagem na extensão do IDE. A configuração fica em ~/.codex/config.toml, dentro de [mcp_servers.<name>]. Eu vou te guiar pelos três métodos usando o exemplo neutro context7, tirado direto da própria documentação da OpenAI - não é um produto que eu esteja empurrando.
- Os comandos, as flags e a sintaxe do config.toml abaixo foram conferidos com a documentação oficial em learn.chatgpt.com/codex/extend/mcp no momento em que escrevi (08/2026); a CLI do Codex evolui mais rápido que a documentação, então rode codex mcp add --help para checar a sua versão instalada antes de depender de qualquer coisa disto.
O que significa "conectar um servidor MCP" no Codex
O MCP (Model Context Protocol) é um padrão aberto que permite a um agente chamar ferramentas/dados externos por uma única interface compartilhada, em vez de uma integração isolada por ferramenta. No Codex, "conectar um servidor MCP" significa dizer ao Codex qual comando (ou URL) inicia o servidor, além de qualquer variável de ambiente ou token que ele precise para rodar.
A primeira coisa para lembrar: o Codex atua apenas como cliente MCP - ele chama servidores externos, mas não se transforma em um servidor MCP que outras ferramentas acessam. Nenhuma documentação confirma um modo servidor para o Codex. Se você ainda é novo no conceito de MCP (não específico do Codex), comece por o que é MCP e como funciona e depois volte aqui.
Três formas de adicionar um servidor
O Codex te dá três caminhos para adicionar um servidor, nenhum mais "correto" que o outro - escolha conforme o seu fluxo de trabalho:
| Método | O que você faz | Ideal quando |
|---|---|---|
CLI - codex mcp add | Um comando no terminal | Servidores STDIO, rápido, sem troca de contexto |
| App Desktop | Settings → MCP servers → Add server | STDIO e HTTP remoto, sem editar TOML manualmente |
| Extensão do IDE | Menu de engrenagem → MCP servers → Add server | Trabalhando dentro do VS Code/IDE, sem terminal separado |
Os três gravam no mesmo lugar: config.toml. A referência completa fica na documentação oficial do MCP no Codex. As seções abaixo cobrem em detalhe os métodos por CLI e por edição direta - os dois mais rápidos se você já se sente à vontade no terminal.
Método 1 - adicionar um servidor pela CLI (STDIO)
O comando principal tem um único formato:
codex mcp add <server-name> -- <server-launch-command>Um exemplo real, tirado direto da própria documentação da OpenAI - context7 (busca de documentação de bibliotecas/frameworks com reconhecimento de versão), executado via npx:
codex mcp add context7 -- npx -y @upstash/context7-mcpEu uso este exemplo em vez do servidor de um fornecedor comercial porque ele é neutro - ninguém está enfiando o próprio produto como o seu exemplo de primeira execução. A maioria dos guias de Codex-MCP de terceiros usa o próprio servidor como demo, o que funciona, mas também significa que você está testando o caminho feliz do produto deles, e não necessariamente uma linha de base limpa. Se um servidor precisar de variáveis de ambiente (chaves de API, tokens…), adicione-as com a flag --env, repetida uma vez por variável:
codex mcp add my-server --env API_KEY=xxx --env REGION=us -- npx -y some-mcp-serverDepois de adicionar, confira de duas formas:
codex mcp list- lista os servidores configurados.- Digite
/mcpdentro de uma sessão TUI do Codex - mostra quais servidores estão ativos naquela sessão.
Se o servidor não aparecer, quase sempre é um -- digitado errado (o hífen duplo que separa as flags do próprio codex mcp add do comando de fato do servidor) - verifique isso antes de supor que o servidor em si está quebrado.
Método 2 - editar o config.toml diretamente
Para um controle mais explícito, ou se você quiser versionar a configuração do MCP junto com um projeto, edite o arquivo diretamente. Um servidor STDIO fica assim:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.context7.env]
API_KEY = "your-value-here"Um servidor Streamable HTTP (remoto) usa um conjunto diferente de chaves - url em vez de command/args, por exemplo um servidor do Figma:
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_TOKEN"
http_headers = { "X-Client" = "codex" }O bearer_token_env_var aponta para o nome de uma variável de ambiente que guarda o token de verdade - você define essa variável na sua máquina, não escreve o token direto no arquivo. O ~/.codex/config.toml é o arquivo global, aplicado a todos os projetos. Para projetos marcados como confiáveis, o Codex também lê um arquivo .codex/config.toml dentro do próprio diretório do projeto - útil se você quiser a configuração de MCP por repositório versionada no controle de versão.
Adicionando um servidor remoto (Streamable HTTP)
O caminho confirmado para servidores HTTP hoje são as Settings do Desktop ou o menu de engrenagem da extensão do IDE: informe um nome, escolha STDIO ou HTTP, cole a URL. Esse caminho está claramente documentado.
Aqui vale a ressalva: alguns guias de terceiros (não a documentação oficial) mostram uma sintaxe como codex mcp add <name> --url <url> para adicionar um servidor HTTP direto pela CLI. A documentação oficial da OpenAI, no momento em que escrevo, não confirma essa flag --url na seção de sintaxe da CLI. Não presuma que ela existe - rode codex mcp add --help para checar se a versão exata da CLI que você tem instalada oferece suporte antes de contar com isso. No pior caso, editar o config.toml à mão (Método 2 acima) funciona independentemente do que a sua versão instalada da CLI suporta, já que não depende da existência de uma flag específica.
Algumas chaves de ajuste fino valem tanto para STDIO quanto para HTTP, declaradas dentro do mesmo bloco [mcp_servers.<name>]: startup_timeout_sec, tool_timeout_sec, enabled (liga/desliga o servidor) e enabled_tools/disabled_tools (lista de permissão/bloqueio de quais ferramentas aquele servidor pode expor).
Codex vs. Claude Code - a configuração de MCP não é a mesma
Este site cobre tanto o Claude Code quanto o Codex, então vale dizer sem rodeios: não leve os hábitos de uma ferramenta direto para a outra.
| Aspecto | Codex | Claude Code |
|---|---|---|
| Formato de configuração | TOML - config.toml | JSON - .mcp.json |
| Comando para adicionar (STDIO) | codex mcp add <name> -- <command> | claude mcp add <name> -- <command> |
| Comando para adicionar (HTTP) | Nenhuma flag de CLI confirmada - use as configurações do Desktop/IDE | claude mcp add --transport http <name> <url> -H "Authorization: Bearer TOKEN" |
| Escopo | Global (~/.codex/config.toml) mais um arquivo opcional por projeto, sem flag de escopo explícita | Flag -s explícita: local (padrão) / project / user |
Quer ver o mesmo servidor real (GitHub) configurado do outro lado? Leia como conectar o servidor MCP do GitHub ao Claude Code - um exemplo concreto entre ferramentas, não teoria.
Confirme que funcionou
A checagem mais rápida: digite /mcp na TUI para ver quais servidores estão ativos na sessão atual. Os modos de falha mais comuns:
- Variável de ambiente faltando - o servidor precisa de
API_KEY, mas você esqueceu o--envou o bloco.envno TOML. command/argserrados - um nome de pacote digitado errado, ou um-yfaltando ao rodar vianpx.- Token HTTP não definido - a variável indicada por
bearer_token_env_varnunca foi definida na sua máquina, então o servidor falha na autenticação mesmo com a sintaxe correta.
Uma frase para deixar o limite claro: um servidor MCP dá ao Codex novas ferramentas para chamar (ler um arquivo do Figma, consultar um banco de dados…). A camada de skills do AgentKit (agentkit.best, kit pago - diferente do AgentKit da OpenAI) é uma camada separada por cima, empacotando fluxos de trabalho prontos - não é a mesma coisa que conectar um servidor MCP, e você não precisa de uma para usar a outra.
Perguntas frequentes (FAQ)
O Codex é um servidor MCP ou apenas um cliente?
Apenas um cliente. O Codex chama servidores MCP externos para obter mais ferramentas/dados; nenhuma documentação confirma que o próprio Codex roda como um servidor MCP que outras ferramentas acessam.
Qual é o comando exato para adicionar um servidor MCP?
codex mcp add <server-name> -- <launch-command>, por exemplo codex mcp add context7 -- npx -y @upstash/context7-mcp. Adicione variáveis de ambiente com --env KEY=VALUE, repetido por variável.
Onde o Codex guarda a configuração de MCP?
Em ~/.codex/config.toml (global, aplicado a todos os projetos), dentro de [mcp_servers.<name>]. Para projetos confiáveis, o Codex também lê um arquivo .codex/config.toml dentro do diretório do projeto.
Qual é a diferença entre STDIO e Streamable HTTP?
O STDIO roda o servidor como um processo local via command/args (por exemplo, iniciado através do npx). O Streamable HTTP chama um servidor remoto por url, autenticado com bearer_token_env_var ou um cabeçalho personalizado - nada para instalar localmente.
Posso adicionar um servidor remoto direto pela CLI?
Não confirmado. Alguns guias de terceiros mostram uma flag --url, mas a documentação oficial do Codex não a lista no momento em que escrevo. O caminho confirmado hoje são as Settings do Desktop ou o menu de engrenagem do IDE; para checar se a sua CLI oferece suporte, rode codex mcp add --help.
A configuração de MCP do Codex é igual à do Claude Code?
Não. O Codex usa TOML (config.toml) sem flag de escopo explícita; o Claude Code usa JSON (.mcp.json) com uma flag -s local/project/user explícita. O mesmo padrão MCP por baixo, mecânicas de configuração diferentes - não copie a sintaxe de uma ferramenta direto para a outra.
Conclusão
Escolha a CLI para uma adição rápida de STDIO, o Desktop/IDE quando precisar de um servidor HTTP remoto e não tiver certeza se a sua CLI já suporta aquela flag, e edite o config.toml diretamente quando quiser a configuração por projeto sob controle de versão. Quer estender o Codex além do MCP? Veja Codex Skills (SKILL.md) - um caminho de extensão paralelo, não um substituto do MCP. Novo no Codex em geral? Comece por o que é o OpenAI Codex.