MCP no OpenAI Codex: codex mcp add para servidores remotos, o config.toml para remotos e stdio, OAuth com codex mcp login e como testar as ferramentas.

Em resumo: o Codex lê seus servidores MCP de ~/.codex/config.toml, e a CLI edita esse arquivo por você. Para um servidor remoto, um comando basta: codex mcp add unifapi --url https://mcp.unifapi.com. Rode codex mcp list para confirmar que ele foi registrado, e codex mcp login unifapi se o login OAuth não abriu no primeiro uso. A extensão de IDE do Codex lê o mesmo arquivo, então um servidor adicionado uma vez fica disponível no terminal e no VS Code.

O Codex, o coding agent da OpenAI, suporta o Model Context Protocol na CLI e na extensão de IDE. A configuração é um único arquivo TOML, o que o torna um dos clientes mais fáceis de configurar e também um dos mais fáceis de errar sem perceber: um servidor adicionado na tabela errada, ou um servidor stdio declarado como URL, falha em silêncio até você pedir uma ferramenta. Este guia usa o servidor MCP da UnifAPI (https://mcp.unifapi.com, dados públicos ao vivo de plataformas sociais e da stack de SEO) como exemplo prático, e os passos são os mesmos para qualquer servidor remoto.

O que você precisa

A CLI do Codex (npm install -g @openai/codex ou brew install codex) ou a extensão do Codex no VS Code, Cursor ou Windsurf. Ambas leem ~/.codex/config.toml.
Um Codex com login feito (codex login). O MCP funciona com login via ChatGPT e com chave de API.
Para a UnifAPI: uma conta UnifAPI quando o prompt de OAuth abrir, e créditos de workspace antes da primeira chamada cobrável. Navegar pelo catálogo é grátis.

Adicione um servidor remoto com codex mcp add

Um servidor remoto (streamable HTTP) é uma URL. Registre-o:

codex mcp add unifapi --url https://mcp.unifapi.com

Confira se ele foi gravado:

codex mcp list
codex mcp get unifapi

codex mcp list imprime todos os servidores configurados com seu transporte e status de autenticação. Na primeira vez que o Codex inicia uma sessão com um servidor protegido por OAuth, ele abre o login no seu browser. Se isso não aconteceu, ou se você está em uma máquina sem browser, dispare o login você mesmo:

codex mcp login unifapi
# headless: print the URL instead of opening a browser
codex mcp login unifapi --no-browser

O login OAuth só é oferecido para servidores streamable HTTP; um servidor stdio não tem etapa de login. O token é armazenado no seu keyring (ou no arquivo de credenciais que o Codex usa como alternativa) e reutilizado entre sessões. codex mcp logout unifapi o apaga, e codex mcp remove unifapi remove o servidor.

O config.toml por trás disso

Tudo o que a CLI gravou é TOML puro em [mcp_servers.<name>]. Para a UnifAPI, a entrada tem uma linha:

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

Dois campos opcionais importam para outros servidores remotos:

[mcp_servers.example]
url = "https://mcp.example.com"
# Read a static bearer token from this environment variable instead of OAuth
bearer_token_env_var = "EXAMPLE_TOKEN"
# Extra headers, literal or sourced from the environment
http_headers = { "X-Client" = "codex" }
env_http_headers = { "X-Tenant" = "EXAMPLE_TENANT" }

A UnifAPI aceita bearer_token_env_var com uma chave de API de workspace, mas OAuth é o caminho recomendado: nada para colar em um dotfile, e o token é somente leitura.

Um servidor stdio local usa command e args em vez de url. Os dois formatos são exclusivos; uma tabela que mistura os dois é rejeitada:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Projects"]
env = { "NODE_OPTIONS" = "--max-old-space-size=512" }

Servidores por projeto

O Codex mescla um .codex/config.toml de projeto (na raiz do repositório, quando o projeto é confiável) por cima da sua config do home. Coloque um servidor lá quando só um repo precisa dele, e commite o arquivo para que o time receba as mesmas ferramentas. codex mcp login resolve nomes a partir da configuração mesclada, então um servidor OAuth com escopo de projeto faz login do mesmo jeito.

Confirme que as ferramentas carregam

Inicie uma sessão em um projeto e peça algo que só o servidor pode responder:

Use o servidor MCP unifapi para listar as operações disponíveis para o Reddit.

Você deve ver uma chamada à ferramenta list_operations antes da resposta. Na extensão de IDE, os servidores MCP e suas ferramentas aparecem no painel de configurações da extensão; um servidor com status vermelho ali geralmente significa que falta o token OAuth (codex mcp login) ou que a URL está errada (codex mcp get).

Dependendo do seu modo de aprovação (codex --ask-for-approval, ou o modo que você escolheu na IDE), o Codex pode perguntar antes de cada chamada de ferramenta. Para um servidor somente leitura como a UnifAPI, é seguro liberar as chamadas para a sessão; a única coisa que uma chamada pode gastar são créditos de workspace, e get_operation mostra o preço por registro antes de call_api rodar.

Uma primeira tarefa que vale os créditos

O servidor MCP da UnifAPI expõe um catálogo grande por meio de três ferramentas: list_operations para descoberta, get_operation para o schema e um exemplo de chamada, e call_api para executar uma operação. O Codex se dá bem com esse formato porque é o mesmo ciclo que ele usa com uma CLI: procurar o comando, ler a ajuda, rodar. Um primeiro prompt delimitado:

Usando as ferramentas MCP unifapi, puxe os 20 posts públicos mais recentes da conta do X que você encontrar para "OpenAI Developers" e me dê uma tabela com post, curtidas, reposts e o tema em uma linha. Chame list_operations e get_operation antes de call_api.

A cobrança é por registro de dados públicos, em créditos de workspace ($0.001 cada; um crédito para a maioria dos registros, pisos maiores publicados no catálogo). Os tokens do modelo ficam no seu plano da OpenAI. Um workspace novo não tem créditos até a primeira recarga, que vem com um bônus único, então faça uma recarga no console da UnifAPI antes do primeiro call_api.

Para trabalho no formato de tarefa, os agents de plataforma e o agent de SEO dão ao Codex um prompt pronto e a lista de operações de que ele vai precisar.

Solução de problemas

Sintoma	O que fazer
`codex mcp list` mostra o servidor, mas as ferramentas nunca aparecem	Inicie uma nova sessão; os servidores são carregados no início da sessão. Na IDE, recarregue a janela
"OAuth login is only supported for streamable HTTP servers"	A tabela tem `command` em vez de `url`; servidores stdio não têm etapa de login
O login no browser nunca conclui	Rode `codex mcp login unifapi --no-browser`, abra a URL impressa em qualquer browser e cole o callback de volta no terminal
`call_api` retorna `insufficient_credits`	O workspace ainda não tem créditos; faça uma recarga no console e rode o mesmo prompt de novo
O servidor desaparece em um repositório	Um `.codex/config.toml` de projeto está sobrescrevendo sua config do home; `codex mcp get <name>` mostra de qual arquivo a entrada veio
As chamadas de ferramenta são recusadas	Seu modo de aprovação está bloqueando; aprove para a sessão ou afrouxe o modo para este projeto

Fontes verificadas

Escrito em 14 de outubro de 2026 com base na referência de configuração de MCP da CLI do Codex e nos subcomandos codex mcp da versão atual (add, list, get, login, logout, remove), além da documentação para desenvolvedores da OpenAI sobre MCP no Codex. Os nomes dos campos no config.toml vêm do schema da própria CLI.

O que ler a seguir

Configuração de MCP - as instruções do conector hospedado para todos os clientes.

Como adicionar um servidor MCP ao Claude - conectores, claude_desktop_config.json e claude mcp add.

Configuração de MCP no Cursor - mcp.json e links de instalação com um clique.

Design das ferramentas de catálogo do MCP - por que o servidor expõe três ferramentas em vez de uma por endpoint.