Conectores MCP (Model Context Protocol): Adicionando conexões externas ao Codex

📚 Navegação da Série: Anterior [19 Sistema de memórias Chronicle] explicou como fazer o Codex memorizar dados entre conversas — ou seja, alimentar a memória interna. Esta parte muda de direção e foca nas conexões externas: por padrão, o Codex acessa apenas arquivos locais e a linha de comando, sem conseguir interagir com bancos de dados, Figma ou documentações externas. O MCP serve como a interface de conexão unificada para associar ferramentas e fontes de dados ao agente. Próxima parte [21 Subagentes (Subagents)] detalhará como dividir tarefas complexas entre agentes em paralelo.

Veja um erro comum que cometi ao configurar o MCP pela primeira vez.

As minhas referências vinham do Claude Code, por isso tinha a seguinte sintaxe em mente: para adicionar um servidor, eu rodava claude mcp add --scope user xxx, onde o --scope determinava o contexto do projeto. Ao iniciar no Codex, executei uma instrução semelhante contendo a opção --scope, e o terminal acusou erro de parâmetro não reconhecido. Achei que fosse incompatibilidade de versão e atualizei o app; mudei a sintaxe de várias formas, mas o erro persistia.

Após perder tempo, verifiquei a documentação oficial: o Codex não utiliza a opção --scope. Ele unifica todas as configurações de servidores MCP no arquivo config.toml, e o escopo de atuação é definido pela localização do arquivo — se salvo na pasta global ~/.codex/config.toml, as conexões aplicam-se a toda a máquina; se na pasta .codex/config.toml do projeto, aplicam-se apenas àquela pasta. Tentar aplicar a lógica do Claude Code no terminal do Codex gerava conflitos de sintaxe.

Apresento esta experiência para poupar seu tempo de configuração: o protocolo MCP em si é idêntico em ambas as ferramentas, mas a forma de configurá-lo no Codex adota regras próprias. Esta parte explica o funcionamento das integrações e guiará a conexão de um servidor de teste.

Ao ler esta parte, você obterá:

• A definição do MCP e o papel que ele desempenha ao estender as capacidades do Codex
• A diferença entre as duas formas de servidor (STDIO local e HTTP remoto), com tabela comparativa
• Como adicionar servidores de duas formas: via comando codex mcp add ou editando o config.toml, e como definir escopos locais e globais
• Como usar as propriedades enabled, disabled_tools e default_tools_approval_mode para restringir ferramentas e regras de aprovação
• Um laboratório prático: conectando e testando o servidor de documentação Context7 em poucos minutos

⚠️ As menções abaixo a comandos específicos, opções de configuração e valores padrão são baseadas na documentação oficial do Codex; nomes de pacotes e modelos que mudam com atualizações devem seguir o que for exibido localmente.

---

01 O papel do MCP nas capacidades do Codex

O Codex atua localmente gerenciando arquivos, alterando códigos e executando comandos de terminal. Toda a atividade ocorre localmente. Por padrão, ele não consegue consultar especificações de telas no Figma, buscar a documentação de APIs na internet ou interagir com páginas vivas de forma autônoma. Para acessar esses dados, você precisaria realizar cópias de textos ou capturas de tela manuais.

Analogia: Um adaptador multientradas para seu celular. Smartphones atuais costumam trazer apenas uma entrada física (ex: USB-C), impedindo a conexão simultânea de cartões de memória, cabos HDMI ou pen drives. A solução é usar um adaptador — um cabo que se conecta à porta única e disponibiliza conexões USB, HDMI e slots de leitura. O MCP (Model Context Protocol, protocolo de contexto do modelo) funciona como este adaptador para o Codex: uma única integração que disponibiliza conexões para múltiplos servidores de dados e APIs.

A documentação define o recurso de forma simples:

O Model Context Protocol (MCP) conecta o modelo a ferramentas e contextos externos. Use-o para alimentar o Codex com documentações de APIs ou integrá-lo com editores de design como o Figma.

A principal característica é tratar-se de um padrão aberto. O protocolo não é uma especificação proprietária da OpenAI, mas sim uma convenção de mercado. Isso permite escrever um servidor MCP que funcione tanto no Codex quanto em outros editores de código (como Claude Code ou Cursor). O Codex herda esse suporte, mudando apenas a sintaxe de configuração (ver seção 03).

O Codex lê o campo instructions (diretrizes) fornecido pelo servidor MCP durante a inicialização, tratando-o como o 'manual de uso' daquela conexão — incluindo regras de rotina, limites de chamadas e termos de formatação que o servidor exige.

Quando adotar o MCP? A indicação de uso é simples: se você se perceber copiando dados de documentações, APIs ou ferramentas externas de forma repetida para alimentar a conversa com a IA, crie uma conexão via servidor MCP.

Exemplos de cenários:

• "Ajustar estilos baseando-se em telas do Figma": o agente consulta as especificações de design do projeto diretamente via API do Figma, sem capturas manuais.
• "Reescrever código usando a versão mais recente de uma biblioteca": o Codex busca as referências direto da documentação viva, evitando o uso de padrões de código obsoletos da memória.
• "Interagir com páginas e obter capturas de tela locais": o agente aciona comandos do navegador automaticamente, sem intervenção do usuário.

💡 Resumo em uma frase: O Codex interage apenas com dados locais por padrão; o protocolo MCP funciona como uma interface unificada para conectar o agente a APIs de design, documentações de bibliotecas e serviços de internet.

A imagem ilustra a arquitetura: o Codex atua em seu limite padrão consumindo comandos e arquivos locais; o conector MCP funciona como um HUB central, integrando servidores externos do GitHub, bancos de dados ou Figma ao agente.

---

02 STDIO local e HTTP remoto

Existem dois tipos de servidores MCP. Compreender o funcionamento de cada um ajuda a mapear as chaves de configuração.

Analogia: Eletrodomésticos locais vs. serviços integrados na nuvem. Aparelhos como ventiladores ou luminárias são conectados diretamente na tomada local de sua residência — operando localmente; serviços inteligentes como assistentes de voz dependem de conexão com servidores de nuvem externa para rodar. Servidores MCP seguem a mesma divisão — ou executam processos na sua própria máquina ou conectam-se a serviços hospedados na internet.

Mapeamento dos tipos de servidores:

Tipo de Servidor	Local de Execução	Mecanismo de Inicialização	Cenário Recomendado
STDIO (Processo local)	Executa na sua máquina local de trabalho	Chamado por comando na CLI (ex: npx ...)	Ações locais de leitura de arquivos, automação de navegadores locais e banco de dados locais
Streamable HTTP (Serviço remoto)	Hospedado em um endereço IP ou domínio externo	Conectado via URL de internet	APIs corporativas, conexões de nuvem e documentações externas, com autenticação

Alguns pontos de atenção na configuração:

A execução de servidores STDIO depende de comandos na CLI. O Codex inicia o executável em segundo plano chamando a instrução configurada (ex: npx -y @upstash/context7-mcp). Isso exige que sua máquina possua os runtimes instalados (como Node.js para rodar instruções npx). Parâmetros adicionais e variáveis de ambiente são passados via --env ou tabelas dedicadas.

Servidores HTTP conectam-se a domínios externos e suportam duas formas de autenticação:

• Bearer token: aponta o nome de uma variável de ambiente que armazena a chave de autenticação;
• OAuth (autorização externa): exige rodar o comando codex mcp login <nome-do-servidor> no terminal para passar pelo fluxo de validação do provedor.

Serviços como integrações do Figma ou documentações corporativas usam conexões HTTP, sem exigir instalações locais na máquina.

Diferença de suporte: interfaces mais antigas de mercado aceitam formatos baseados em SSE (Server-Sent Events), contudo o Codex foca o suporte nativo nos modelos STDIO e Streamable HTTP.

Veja a representação dos fluxos de conexão na imagem abaixo:

A imagem representa que o Codex lê comandos e arquivos em seu limite local, integrando o acesso a APIs de nuvem e servidores de desenvolvimento externos via canais STDIO (chamando processos locais) ou HTTP (chamando URLs autenticadas).

💡 Resumo em uma frase: O MCP aceita servidores STDIO (processos chamados por comandos locais no terminal) e Streamable HTTP (conexões com endereços web protegidos por Bearer tokens ou OAuth).

---

03 Adicionando servidores: linha de comando ou config.toml

A parametrização do MCP no Codex reside única e exclusivamente no arquivo config.toml.

A documentação confirma:

O Codex reúne a parametrização do MCP no arquivo config.toml geral de usuário em ~/.codex/config.toml ou no escopo local do projeto em .codex/config.toml (para diretórios marcados como confiáveis).

A ausência de parâmetros como --scope faz o Codex delegar o escopo da regra baseado na pasta em que o arquivo de configuração é salvo:

Mapeamento do arquivo	Escopo de atuação	Uso recomendado
Global (~/.codex/config.toml)	Todos os diretórios do sistema	Ferramentas de uso geral em múltiplos projetos
Local (<projeto>/.codex/config.toml)	Apenas na pasta do projeto ativo (requer marcar diretório como confiável)	Conectores dedicados ao repositório ou de desenvolvimento local

A parametrização é unificada: os comandos de terminal (CLI) e a extensão de IDE (VS Code) utilizam o mesmo arquivo de configuração, aplicando as conexões em ambos os ambientes automaticamente.

Lembre-se: chaves locais do .codex/config.toml são carregadas apenas se o diretório do projeto estiver na lista de confiáveis do Codex, mitigando o risco de scripts maliciosos de repositórios públicos ativarem conexões de rede locais.

Método 1: via linha de comando (CLI)

Adicione conexões locais STDIO com o utilitário codex mcp add, usando os caracteres -- antes do comando de inicialização:

codex mcp add <nome-do-servidor> --env VAR1=VALOR1 -- <comando_de_inicializacao>

Exemplo para conectar o servidor de documentação Context7:

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

A instrução npx -y @upstash/context7-mcp inicia o script. A opção -y indica ao npx para instalar pacotes sem pedir confirmação. Use codex mcp --help no terminal para verificar as opções de gerenciamento. Conexões HTTP baseadas em OAuth exigem executar codex mcp login <nome-do-servidor> após a inclusão.

Para verificar os servidores MCP ativos na conversa atual do terminal, digite:

/mcp

Método 2: via edição do config.toml

Para maior controle sobre parâmetros ou regras de permissão, edite a tabela [mcp_servers.<nome-do-servidor>] no arquivo de configurações.

Estrutura de servidor STDIO no arquivo (equivalente ao Context7):

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

Onde command indica o executável e args os parâmetros de inicialização. Propriedades como env (variáveis de ambiente locais), cwd (diretório de trabalho do processo) e env_vars (variáveis a serem compartilhadas com o processo) podem ser adicionadas sob a mesma chave.

Estrutura de servidor Streamable HTTP (exemplo oficial de integração do Figma):

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

A chave url mapeia o domínio de destino, e bearer_token_env_var aponta o nome da variável de ambiente que armazena a chave de acesso — mantendo credenciais fora do arquivo de configurações principal (seguindo boas práticas de segurança). Parâmetros adicionais de cabeçalho podem ser passados via http_headers ou env_http_headers.

A edição via terminal ou direta de arquivo altera as chaves sob mcp_servers no mesmo config.toml geral abordado na seção 18.

💡 Resumo em uma frase: O Codex centraliza a configuração do MCP no config.toml, limitando o escopo ao diretório global ~/.codex/ ou local .codex/ do projeto, permitindo parametrizações via codex mcp add ou edição de tabelas.

---

04 Restrições e controle de permissões de servidores

Adicionar a conexão com o servidor não implica liberar todo o acesso. O Codex permite restringir chaves de execução de servidores no config.toml — controlando ferramentas permitidas, tempos de expiração e regras de confirmação.

Analogia: Atribuir credenciais de acesso locais para novos colaboradores. Novas credenciais de segurança não liberam acesso a todas as salas da empresa. O sistema permite configurar salas autorizadas, limites de horário e portas que exigem liberação da segurança. Restringir permissões de servidores MCP segue o mesmo princípio: define quais ferramentas podem executar e quais demandam sua confirmação.

Mapeamento de chaves de controle de servidores:

Propriedade	Função	Valor Padrão
enabled	Permite desativar temporariamente o servidor sem remover suas configurações	true
enabled_tools	Lista de ferramentas autorizadas a executar (whitelist)	Libera todas se não especificada
disabled_tools	Lista de ferramentas bloqueadas (blacklist, aplicada sobre a whitelist)	Nenhuma
default_tools_approval_mode	Regra de aprovação padrão para comandos deste servidor	auto
startup_timeout_sec	Tempo limite para o servidor responder na inicialização (segundos)	10
tool_timeout_sec	Tempo limite para execução de comandos individuais (segundos)	60

Pontos de atenção na parametrização:

A lista de bloqueios (blacklist) atua sobre as permissões da whitelist. A documentação confirma que disabled_tools é aplicada após a validação do enabled_tools. Isso permite configurar um escopo inicial com enabled_tools = ["open", "screenshot"] e bloquear itens específicos adicionando disabled_tools = ["screenshot"], resultando na liberação apenas da ferramenta open.

A propriedade de aprovação (default_tools_approval_mode) aceita os seguintes estados:

• auto: o Codex avalia a criticidade do comando para decidir se pede confirmação;
• prompt: exige autorização manual a cada execução de ferramenta;
• approve: libera a execução automática sem solicitações (indica confiança no servidor).

O escopo de aprovação pode ser definido para ferramentas individuais via tools.<nome_da_ferramenta>.approval_mode (ex: liberando ferramentas gerais e exigindo confirmação para ações de alteração de dados).

Os tempos padrões de timeout limitam-se a 10 segundos para inicialização e 60 segundos para comandos. Se você conectar servidores que exigem compilação local lenta para inicializar, altere o valor de startup_timeout_sec para evitar falhas de timeouts:

[mcp_servers.slow_server]
command = "python"
args = ["-m", "slow_server"]
startup_timeout_sec = 30   # Aumenta a margem de inicialização
tool_timeout_sec = 120     # Aumenta a margem de execução

Exemplo de configuração consolidando chaves de restrições e permissões:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]          # Limita a ação, restando apenas open
default_tools_approval_mode = "prompt"   # Exige aprovação padrão
startup_timeout_sec = 20
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"                # Habilita execução direta apenas para open

💡 Resumo em uma frase: Gerencie chaves de controle do MCP no config.toml usando enabled para desativações, listas enabled_tools/disabled_tools para restringir comandos, e default_tools_approval_mode para regras de aprovação.

---

05 Confiança em servidores de terceiros

Este ponto relaciona-se com as discussões da seção 16 sobre segurança e limites de risco.

Servidores MCP executam códigos de terceiros sem auditorias nativas da OpenAI. Configurar um conector STDIO local inicializa scripts de terceiros em sua máquina de trabalho; integrar conexões HTTP externas envia dados de contexto do terminal para domínios da internet.

Analogia: Instalar dependências externas em seu repositório local. Você evita adicionar dependências sem verificar a quantidade de instalações, reputação da biblioteca ou criadores do pacote. Conectores MCP seguem a mesma diretriz: valide as fontes e autores antes de adicionar o servidor, especialmente conexões que capturam dados externos (como ferramentas de busca web ou integradores de fóruns).

O consumo de dados da internet por servidores externos aumenta a exposição a injeções de instruções (prompt injection). Informações de sites lidos pelo servidor podem conter instruções ocultas formatadas como comandos para o Codex. Para mitigar riscos, utilize as regras de controle (seção 04): ajuste a política de aprovação do servidor como prompt (exigindo confirmação) e restrinja privilégios a apenas leitura.

Guia rápido de avaliação de servidores:

Classificação do Servidor	Diretriz de uso
Servidores recomendados oficiais (Playwright, Figma, OpenAI Docs)	✅ Conexão segura
Servidores de grandes provedores corporativos (GitHub, Sentry)	✅ Conexão segura
Servidores avulsos de repositórios do GitHub com poucos commits	⚠️ Audite o código fonte do plugin antes de conectar
Ativar liberação total (default_tools_approval_mode = "approve")	⚠️ Limite aos servidores oficiais conhecidos
Liberar permissão de escrita em bancos de dados críticos	❌ Restrinja a conexão a apenas leitura

O uso de sandboxes e aprovações (seções 15 e 16) mitiga riscos, contudo, definir privilégios automáticos (approve) para servidores desconhecidos remove as barreiras de proteção. Mantenha o maior nível de controle ativo.

💡 Resumo em uma frase: Conectores MCP representam execução de código de terceiros; priorize servidores homologados ou oficiais, evite conexões com permissão de escrita direta e configure regras de aprovação manual (prompt) para servidores novos.

---

06 Laboratório: Conectando o servidor de documentação Context7

Vamos realizar o laboratório prático de integração com o servidor Context7 — plugin de busca de documentações técnicas recomendado oficialmente por ser gratuito e rápido.

Requisitos: a máquina de trabalho deve possuir o Node.js instalado (confirme executando node -v no terminal). O processo exige conexão à internet para baixar a dependência.

Passo 1: Adicionar o servidor de testes.

Execute na linha de comando de sua máquina (fora da conversa do Codex):

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

Resultado esperado: Confirmação da inclusão do servidor Context7. O comando cria a tabela [mcp_servers.context7] no arquivo ~/.codex/config.toml global.

Passo 2: Confirmar a conexão.

Inicie a sessão interativa do Codex:

codex

E verifique a lista de servidores ativos com o comando de barra:

/mcp

Resultado esperado: a listagem exibirá a chave context7 como ativa no sistema. Caso falhe, confirme a presença e versão do Node.js em seu terminal.

Passo 3: Executar a busca de documentação.

Solicite uma consulta de código informando o conector de dados:

Use a ferramenta Context7 para buscar a estrutura básica de rotas da biblioteca React Router em sua versão mais recente, e exiba os exemplos correspondentes.

Resultado esperado: O Codex acionará a ferramenta do servidor Context7. No primeiro acesso, uma solicitação de aprovação de execução de ferramenta será exibida, confirme a ação. A resposta trará o formato da documentação atualizada diretamente do servidor externo, permitindo auditar a origem da resposta.

Passo 4: Remover a conexão de testes (Opcional).

Para remover a conexão de sua máquina, utilize o utilitário de remoção da CLI do Codex (confirme a sintaxe do comando executando codex mcp --help) ou edite o arquivo ~/.codex/config.toml e delete a tabela [mcp_servers.context7] manualmente.

Com isso, você validou a ativação, chamada de ferramenta e limpeza do servidor MCP de forma prática.

💡 Resumo em uma frase: O laboratório do Context7 demonstra a inclusão do servidor via terminal, confirmação com /mcp e consulta à documentação externa com validação de aprovação.

---

07 Resumo

Esta seção apresentou as ferramentas de integração com APIs e serviços por meio do Model Context Protocol (MCP).

Consolidação dos conceitos:

Objetivo	Caminho	Regra de uso
Ampliar contexto local	Conectores MCP	Protocolo padrão para expor ferramentas, APIs e documentações ao Codex
Tipos de servidores	STDIO e HTTP	STDIO executa scripts locais na máquina; HTTP chama domínios externos autenticados
Escopo de conexões	Caminho do arquivo config	Definido por onde o config.toml é salvo (global ~/.codex/ ou local do projeto)
Inserir servidores	CLI / config.toml	Use codex mcp add para inicializações rápidas e chaves de tabelas para ajustes finos
Segurança de execução	Chaves de restrição	Use enabled_tools para filtrar ações, timeout para limites e prompt para aprovações
Auditoria de terceiros	Triagem de conexões	Mantenha chaves de escrita desativadas por padrão e verifique fontes de servidores não oficiais

A partir de agora, você entende: a utilidade do conector MCP para integrar sistemas externos, a diferença de parametrização entre conexões STDIO e HTTP, como definir o escopo de atuação local ou global e gerenciar chaves de limites e aprovação de ferramentas. A integração dessas regras expande a atuação do Codex para além dos limites do terminal local.

---

A próxima seção 21 · Subagentes (Subagents) — detalhará o fluxo de execução distribuído: como o Codex pode criar subagentes especializados para executar tarefas em paralelo? Como se comunicar com os subagentes e gerenciar seu andamento na conversa? Mapeadas as ferramentas de integração externa, vejamos como gerenciar a divisão de tarefas.

---

Leituras Recomendadas

• Estruturação de tarefas comuns no Codex
• Diretrizes de modelos e endpoints de API
• Uso do arquivo de contexto AGENTS.md