Para executar um servidor MCP do Codex sandbox, defina um perfil de permissões em ~/.codex/config.toml e então aponte o command do servidor para codex sandbox --permission-profile <nome> --, seguido do comando original. O Codex não coloca servidores MCP stdio em sandbox por padrão, então sem esse wrapper um servidor npx é executado com todas as suas permissões de usuário.
O artigo de engenharia da OpenAI Inside the Codex sandbox, publicado em 18 de novembro de 2026, deixa isso claro: o Codex não consegue adivinhar com segurança quais arquivos ou serviços de rede um servidor precisa, então ele não mexe no comando de inicialização do servidor. Todo servidor MCP que você adiciona com npx -y pode ler sua pasta pessoal, gravar em qualquer lugar onde você tem permissão de escrita e acessar qualquer host na internet.
A seguir, você vai criar um perfil para o Apidog MCP Server, vinculá-lo a um arquivo OpenAPI local com a rede desativada, comprovar que o perfil funciona com codex sandbox e então delegar o trabalho rotineiro ao seu agente de programação com a Apidog CLI.
Por que o Codex deixa servidores MCP stdio sem sandbox
Um servidor MCP stdio é um programa local que o Codex inicia e com o qual se comunica por entrada e saída padrão. O Codex coloca em sandbox os comandos de shell que seu modelo executa, mas não coloca em sandbox o comando que inicia um servidor MCP, porque não consegue determinar quais arquivos ou hosts esse servidor precisa. O servidor herda todas as suas permissões de usuário.
Os comandos executados pelo modelo recebem o perfil interno :workspace: escrita apenas dentro do workspace, .git e .codex somente leitura, leituras amplas, sem rede. Um servidor MCP em [mcp_servers] não recebe nada disso.
Essa lacuna importa porque servidores MCP são código de terceiros que você baixa no momento da inicialização. Uma configuração típica se parece com isto:
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory@1.0.0"]
npx -y baixa o pacote e o executa sem nenhum aviso. Se esse pacote estiver comprometido, ele pode ler seus arquivos .env e chaves SSH e enviá-los para qualquer lugar. Nosso guia sobre políticas de segurança do MCP aborda o modelo de ameaças mais amplo; este artigo corrige a única brecha na sua configuração do Codex.
Como funciona um perfil de permissões do Codex
Um perfil de permissões é um conjunto nomeado de regras de sistema de arquivos e de rede em [permissions] no config.toml. O artigo da OpenAI e a documentação de permissões do Codex descrevem três níveis de sistema de arquivos:
| Valor | Efeito |
|---|---|
read |
Acesso somente leitura |
write |
Acesso de leitura e escrita |
deny |
Nenhum acesso |
Três chaves fazem a maior parte do trabalho:
":root" = "read"concede leituras amplas, que o Node.js e o npm precisam para carregar seus próprios arquivos.- Um caminho como
"~/.npm" = "write"concede escrita apenas a essa pasta. - Uma tabela
":workspace_roots"aplica regras relativas a cada raiz de workspace."**/*.env" = "deny"bloqueia todos os arquivos.envdentro dela.
A rede tem três modos: desligada, roteada pelo proxy do Codex com uma lista de domínios permitidos, ou acesso total.

A Codex CLI de código aberto aplica essas regras por meio do sistema operacional: Seatbelt no macOS, bubblewrap com seccomp no Linux e, em dispositivos Windows compatíveis, o MXC da Microsoft. Os processos filhos herdam os limites, então tudo o que o servidor iniciar permanece dentro da mesma caixa.
Passo 1: Escolha o modo mais seguro para o Apidog MCP Server
O Apidog MCP Server (apidog-mcp-server no npm, versão 0.0.18 atualmente) opera em dois modos:
- Modo projeto, com
--project-id=<id>e umAPIDOG_ACCESS_TOKEN, que busca a documentação da sua API de um projeto Apidog pela rede. - Modo OAS, com
--oas=<url-ou-caminho>, que lê um arquivo Swagger ou OpenAPI diretamente.
O modo OAS com um arquivo local não precisa de rede alguma. Esse é o perfil mais restritivo que você pode escrever, então é o exemplo principal aqui. A Apidog CLI mantém a especificação atualizada de fora do sandbox (Passo 5).
Analisamos o pacote 0.0.18 para identificar o que o servidor grava: ele armazena dados em cache em ~/.apidog-mcp-server (ou na pasta definida em APIDOG_DATA_LOCATION) e, no modo projeto, chama https://api.apidog.com, a menos que você passe --apidog-api-base-url.
Passo 2: Defina o perfil de permissões
Adicione isto ao ~/.codex/config.toml:
[permissions.apidog-mcp.filesystem]
# Leituras amplas para que o Node.js e o npm possam carregar seus próprios arquivos.
":root" = "read"
"~/.npm" = "write"
"~/.apidog-mcp-server" = "write"
[permissions.apidog-mcp.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.apidog-mcp.network]
enabled = false
O servidor pode ler a especificação e gravar em duas pastas de cache. Ele não consegue abrir nenhum arquivo .env do workspace e não tem acesso à rede.
Passo 3: Envolva o comando do servidor em codex sandbox
Agora substitua a inicialização simples com npx por codex sandbox. A flag -C define o diretório de trabalho, que também é a raiz do workspace à qual a regra de .env se aplica:
[mcp_servers.pets-api-docs]
command = "codex"
args = [
"sandbox",
"--permission-profile", "apidog-mcp",
"-C", "/Users/you/code/pets-api",
"--",
"npx", "--offline",
"apidog-mcp-server@0.0.18",
"--oas=/Users/you/code/pets-api/openapi.json"
]
Três detalhes importam:
- Fixe a versão.
@0.0.18garante que uma nova versão não substitua o código por baixo de você. - Use
npx --offline. Com a rede desligada, onpxprecisa encontrar o pacote no cache. - Use caminhos absolutos. O Codex passa os
argsdiretamente, sem shell, então o~não é expandido.
O README do Apidog sugere nomear o servidor com o nome da API que ele documenta, como "Pets API Documentation", para que o modelo saiba quando usá-lo.

Passo 4: Pré-armazene o pacote em cache e comprove que o perfil funciona
O sandbox pode gravar na pasta de cache, mas não consegue criá-la, nem baixar nada. Execute estes comandos uma vez, fora do sandbox:
mkdir -p ~/.apidog-mcp-server
npx -y --package=apidog-mcp-server@0.0.18 -c true
Depois teste o perfil antes de confiar nele. O codex sandbox executa qualquer comando sob um perfil, o que o torna um harness de teste rápido:
cd /Users/you/code/pets-api
# 1. Um arquivo .env no workspace é ilegível
codex sandbox --permission-profile apidog-mcp -- cat .env
# cat: .env: Operation not permitted
# 2. Gravações fora das pastas permitidas falham
codex sandbox --permission-profile apidog-mcp -- bash -c 'echo x > /tmp/probe.txt'
# bash: /tmp/probe.txt: Operation not permitted
# 3. A pasta de cache permitida aceita escrita
codex sandbox --permission-profile apidog-mcp -- touch ~/.apidog-mcp-server/probe
# (sem saída, exit 0)
# 4. Sem rede
codex sandbox --permission-profile apidog-mcp -- curl -sS https://api.apidog.com/
# curl: (6) Could not resolve host: api.apidog.com
Esses foram os resultados que obtivemos no macOS. Em seguida, verifique se o servidor ainda funciona enviando a ele um handshake MCP:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| codex sandbox --permission-profile apidog-mcp -- \
npx --offline apidog-mcp-server@0.0.18 --oas=$PWD/openapi.json
Com a rede desligada, o servidor respondeu com três ferramentas: uma que lê a especificação OpenAPI, uma que lê arquivos referenciados por $ref e uma que atualiza a especificação. É tudo do que o Codex precisa para escrever código para a sua API.
No macOS, adicione --log-denials a qualquer chamada de codex sandbox para imprimir as negações do Seatbelt após o término do comando. É a maneira mais rápida de descobrir uma pasta da qual o servidor realmente precisa.
Passo 5: Deixe o Codex manter a especificação atualizada com a Apidog CLI
Um servidor offline lê um arquivo, então algo precisa atualizá-lo. Delegue essa tarefa ao seu agente de programação com a Apidog CLI. Ele é executado fora do sandbox do MCP, sob as regras normais de comando do Codex, e o servidor MCP nunca precisa de um token.
Configuração (uma vez):
npm install -g apidog-cli
apidog auth login --with-token <your-access-token>
Se você ainda não integrou a CLI ao Codex, siga How to Use the Apidog CLI in Codex.
Faça um prompt para o seu agente:
Exporte a especificação OpenAPI 3.1 do projeto Apidog 1234567 para ./openapi.json,
em seguida execute o cenário de teste 637132 no ambiente 358171 contra ela e me dê
um resumo via CLI. Não toque em nenhum arquivo .env.
Comandos executados pelo agente (flags de apidog export --help e apidog run --help, CLI 2.2.12):
apidog export --project 1234567 --format openapi --oas-version 3.1 --output ./openapi.json
apidog run -t 637132 -e 358171 -r cli,junit --out-dir ./apidog-reports
O export sobrescreve o arquivo que o servidor em sandbox lê, então a próxima chamada MCP enxerga os novos endpoints. O run executa seu cenário de teste e grava um relatório JUnit para a CI. Adicione --upload-report se quiser revisar a execução no app Apidog. O plano Free do Apidog cobre até 4 usuários.
Quando o servidor precisa de rede: a lista de domínios permitidos
O modo projeto precisa acessar api.apidog.com. A resposta do Codex é o proxy de rede: defina enabled = true, liste os domínios permitidos e ative o recurso network_proxy. Esta é a estrutura documentada no artigo da OpenAI, adaptada para o Apidog:
[permissions.apidog-mcp-live.filesystem]
":root" = "read"
"~/.npm" = "write"
"~/.apidog-mcp-server" = "write"
[permissions.apidog-mcp-live.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.apidog-mcp-live.network]
enabled = true
[permissions.apidog-mcp-live.network.domains]
"api.apidog.com" = "allow"
[features]
network_proxy = true
Um deny explícito tem precedência sobre allow, e o proxy só resolve um hostname depois que uma regra o permite, já que até uma consulta DNS pode vazar dados. A OpenAI alerta que wildcards amplos ainda podem permitir exfiltração via DNS, então liste hosts exatos.
Um alerta do nosso próprio teste. No nosso Mac, o proxy iniciou e injetou HTTP_PROXY e variáveis similares no sandbox, mas respondeu 403 com x-proxy-error: blocked-by-allowlist para todos os hosts, incluindo os permitidos. Nossa máquina roteia DNS por meio de um aplicativo de proxy local, o que pode ser a causa. Execute codex sandbox --permission-profile apidog-mcp-live -- curl -sS https://api.apidog.com/ na sua própria máquina antes de depender deste perfil. Se o host permitido falhar, volte para o modo OAS do Passo 1.
Qual perfil você deve usar?
| Tipo de servidor | Rede | Escritas no sistema de arquivos | Exemplo |
|---|---|---|---|
| Lê apenas arquivos locais | enabled = false |
Cache npm + pasta de dados própria | Apidog MCP Server com --oas |
| Chama uma API conhecida | Proxy + domínios exatos | Cache npm + pasta de dados própria | Apidog MCP Server com --project-id |
| Precisa de internet aberta | Evite, ou isole em uma VM | O mais restrito possível | Servidores de navegação web |
Se você usa o Codex em equipe, os administradores podem usar allowed_permission_profiles em requirements.toml para limitar quais perfis os usuários podem escolher. E se você estiver tentado a desativar o sandbox, leia por que contornar o sandbox do Codex abre mão exatamente dessa proteção.
Perguntas frequentes
O Codex coloca servidores MCP em sandbox por padrão? Não. A OpenAI afirma que o Codex não coloca em sandbox o comando que inicia um servidor MCP stdio configurado no config.toml. Você mesmo adiciona o sandbox iniciando o servidor por meio de codex sandbox --permission-profile <nome> --.
Por que usar npx --offline em vez de npx -y? Com network.enabled = false, o npx não consegue baixar nada. O --offline manda ele usar a cópia que você armazenou em cache com npx -y --package=<pkg>@<versão> -c true, e fixar a versão impede que uma nova release substitua o código.
O sandbox protege minhas chaves de API? Ele bloqueia o que você nega. O perfil :workspace permite leituras amplas, então adicione regras deny para arquivos .env e pastas de segredos. Com a rede desligada, o servidor também não consegue enviar nada do que lê.
Isso funciona no Linux e no Windows? Sim. O mesmo perfil se aplica em todos os lugares; o Codex o aplica com bubblewrap e seccomp no Linux e com um sandbox baseado em MXC em dispositivos Windows compatíveis. Teste cada máquina com codex sandbox, pois caminhos e configurações de DNS variam.
Posso colocar outros servidores MCP em sandbox da mesma forma? Sim. Qualquer servidor stdio funciona: identifique as pastas em que ele grava e os hosts que ele chama, atribua um perfil, envolva o comando, pré-armazene o pacote em cache e teste. O próprio exemplo da OpenAI coloca em sandbox o @modelcontextprotocol/server-memory com escritas limitadas a ~/.npm e ~/mcp-data.
