Como isolar um servidor MCP com o codex sandbox

O Codex não executa servidores MCP stdio em sandbox, então servidores npx rodam com suas permissões completas. Crie um perfil de permissão, envolva o servidor no sandbox do Codex e teste-o.

INEZA Felin-Michel

INEZA Felin-Michel

20 novembro 2026

Como isolar um servidor MCP com o codex sandbox

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

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:

  1. ":root" = "read" concede leituras amplas, que o Node.js e o npm precisam para carregar seus próprios arquivos.
  2. Um caminho como "~/.npm" = "write" concede escrita apenas a essa pasta.
  3. Uma tabela ":workspace_roots" aplica regras relativas a cada raiz de workspace. "**/*.env" = "deny" bloqueia todos os arquivos .env dentro dela.

A rede tem três modos: desligada, roteada pelo proxy do Codex com uma lista de domínios permitidos, ou acesso total.

Três modos de rede para um perfil de permissões do Codex: network.enabled = false para sem rede, um proxy com lista de domínios permitidos como api.apidog.com, e acesso total à rede a ser evitado para servidores MCP

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:

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:

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.

Diagrama: o Codex inicia o codex sandbox com o perfil apidog-mcp, que executa npx --offline apidog-mcp-server com um arquivo OpenAPI; dentro do sandbox ele pode ler openapi.json e gravar em ~/.npm e ~/.apidog-mcp-server, enquanto arquivos .env, a internet e outras pastas ficam bloqueados

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.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs