DEV Community

Cover image for Comment isoler un serveur MCP avec codex sandbox
Antoine Laurent
Antoine Laurent

Posted on Originally published at apidog.com

Comment isoler un serveur MCP avec codex sandbox

Comment exécuter un serveur MCP dans un sandbox Codex (guide pratique)

Pour exécuter un serveur MCP dans un sandbox Codex, définissez un profil de permissions dans ~/.codex/config.toml, puis faites pointer le command du serveur vers codex sandbox --permission-profile <name> -- suivi de la commande d'origine. Codex ne place pas les serveurs MCP stdio dans un sandbox par défaut ; sans cet enrobage, un serveur npx s'exécute avec l'ensemble de vos permissions utilisateur.

Essayez Apidog dès aujourd'hui

L'article d'ingénierie d'OpenAI Inside the Codex sandbox, publié le 18 novembre 2026, l'explique sans détour : Codex ne peut pas deviner de manière fiable quels fichiers ou services réseau un serveur nécessite, il laisse donc intacte la commande de lancement du serveur. Chaque serveur MCP que vous ajoutez avec npx -y peut lire votre dossier personnel, écrire partout où vous avez les droits d'écriture et appeler n'importe quel hôte sur Internet.

Vous allez ci-dessous créer un profil pour le serveur MCP Apidog, le verrouiller sur un fichier OpenAPI local avec le réseau désactivé, vérifier que le profil fonctionne avec codex sandbox, puis confier le travail routinier à votre agent de programmation via la CLI Apidog.

Pourquoi Codex laisse les serveurs MCP stdio hors sandbox

Un serveur MCP stdio est un programme local que Codex lance et auquel il parle via l'entrée et la sortie standard. Codex applique un sandbox aux commandes shell exécutées par son modèle, mais il ne sandboxe pas la commande qui lance un serveur MCP, car il ne peut pas déterminer de quels fichiers ou hôtes ce serveur a besoin. Le serveur hérite de l'ensemble de vos permissions utilisateur.

Les commandes exécutées par le modèle bénéficient du profil intégré :workspace : écritures limitées à l'espace de travail, .git et .codex en lecture seule, lectures étendues, aucun réseau. Un serveur MCP déclaré dans [mcp_servers] ne bénéficie de rien de tout cela.

Cette lacune est importante, car les serveurs MCP sont du code tiers que vous récupérez au moment du lancement. Une configuration typique ressemble à ceci :

[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory@1.0.0"]
Enter fullscreen mode Exit fullscreen mode

npx -y télécharge le paquet et l'exécute sans confirmation. Si ce paquet est compromis, il peut lire vos fichiers .env et vos clés SSH et les envoyer n'importe où. Notre guide sur les politiques de sécurité MCP couvre le modèle de menace dans son ensemble ; cet article comble la seule faille de votre configuration Codex.

Fonctionnement d'un profil de permissions Codex

Un profil de permissions est un ensemble nommé de règles de système de fichiers et de réseau définies sous [permissions] dans config.toml. L'article d'OpenAI et la documentation sur les permissions Codex décrivent trois niveaux de système de fichiers :

Valeur Effet
read Accès en lecture seule
write Accès en lecture et en écriture
deny Aucun accès

Trois clés font l'essentiel du travail :

  1. ":root" = "read" accorde des lectures étendues, dont Node.js et npm ont besoin pour charger leurs propres fichiers.
  2. Un chemin tel que "~/.npm" = "write" n'accorde l'écriture que dans ce dossier.
  3. Une table ":workspace_roots" applique des règles relatives à chaque racine d'espace de travail. "**/*.env" = "deny" bloque tous les fichiers .env qu'elle contient.

Le réseau dispose de trois modes : désactivé, routé via le proxy de Codex avec une liste de domaines autorisés, ou accès complet.

Trois modes réseau pour un profil de permissions Codex : network.enabled = false pour aucun réseau, un proxy avec une liste de domaines autorisés comme api.apidog.com, et un accès réseau complet à éviter pour les serveurs MCP

La CLI Codex open source fait respecter ces règles par le système d'exploitation : Seatbelt sur macOS, bubblewrap associé à seccomp sur Linux et, sur les appareils Windows compatibles, MXC de Microsoft. Les processus enfants héritent des limites, si bien que tout ce que le serveur lance reste dans la même boîte.

Étape 1 : choisir le mode le plus sûr pour le serveur MCP Apidog

Le serveur MCP Apidog (apidog-mcp-server sur npm, version 0.0.18 aujourd'hui) fonctionne selon deux modes :

  • Mode projet, avec --project-id=<id> et un APIDOG_ACCESS_TOKEN, récupère la documentation de vos API depuis un projet Apidog via le réseau.
  • Mode OAS, avec --oas=<url-or-path>, lit directement un fichier Swagger ou OpenAPI.

Le mode OAS avec un fichier local ne nécessite aucun réseau. C'est le profil le plus restrictif que vous puissiez écrire, c'est donc l'exemple principal ici. La CLI Apidog maintient la spec à jour depuis l'extérieur du sandbox (étape 5).

Nous avons examiné le paquet 0.0.18 pour identifier ce que le serveur écrit : il met des données en cache dans ~/.apidog-mcp-server (ou dans le dossier défini par APIDOG_DATA_LOCATION), et en mode projet, il appelle https://api.apidog.com sauf si vous passez --apidog-api-base-url.

Étape 2 : définir le profil de permissions

Ajoutez ceci dans ~/.codex/config.toml :

[permissions.apidog-mcp.filesystem]
# Broad reads so Node.js and npm can load their own files.
":root" = "read"
"~/.npm" = "write"
"~/.apidog-mcp-server" = "write"

[permissions.apidog-mcp.filesystem.":workspace_roots"]
"**/*.env" = "deny"

[permissions.apidog-mcp.network]
enabled = false
Enter fullscreen mode Exit fullscreen mode

Le serveur peut lire la spec et écrire dans deux dossiers de cache. Il ne peut ouvrir aucun fichier .env de l'espace de travail et n'a aucun accès réseau.

Étape 3 : enrober la commande du serveur dans codex sandbox

Remplacez maintenant le lancement npx simple par codex sandbox. L'option -C définit le répertoire de travail, qui est aussi la racine d'espace de travail à laquelle s'applique la règle .env :

[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"
]
Enter fullscreen mode Exit fullscreen mode

Trois détails comptent :

  • Épinglez la version. @0.0.18 empêche une nouvelle version de remplacer le code sous vos pieds.
  • Utilisez npx --offline. Avec le réseau désactivé, npx doit trouver le paquet dans le cache.
  • Utilisez des chemins absolus. Codex transmet les args directement, sans passer par un shell, donc ~ n'est pas développé.

Le README d'Apidog suggère de nommer le serveur d'après l'API qu'il documente, par exemple « Pets API Documentation », afin que le modèle sache quand l'utiliser.

Schéma : Codex lance codex sandbox avec le profil apidog-mcp, qui exécute npx --offline apidog-mcp-server avec un fichier OpenAPI ; dans le sandbox, il peut lire openapi.json et écrire dans ~/.npm et ~/.apidog-mcp-server, tandis que les fichiers .env, Internet et les autres dossiers sont bloqués

Étape 4 : pré-mettre le paquet en cache et vérifier que le profil fonctionne

Le sandbox peut écrire dans le dossier de cache mais ne peut pas le créer, et il ne peut rien télécharger. Exécutez ces commandes une fois, en dehors du sandbox :

mkdir -p ~/.apidog-mcp-server
npx -y --package=apidog-mcp-server@0.0.18 -c true
Enter fullscreen mode Exit fullscreen mode

Testez ensuite le profil avant de lui faire confiance. codex sandbox exécute n'importe quelle commande sous un profil, ce qui en fait un banc d'essai rapide :

cd /Users/you/code/pets-api

# 1. A .env file in the workspace is unreadable
codex sandbox --permission-profile apidog-mcp -- cat .env
# cat: .env: Operation not permitted

# 2. Writes outside the allowed folders fail
codex sandbox --permission-profile apidog-mcp -- bash -c 'echo x > /tmp/probe.txt'
# bash: /tmp/probe.txt: Operation not permitted

# 3. The allowed cache folder is writable
codex sandbox --permission-profile apidog-mcp -- touch ~/.apidog-mcp-server/probe
# (no output, exit 0)

# 4. No network
codex sandbox --permission-profile apidog-mcp -- curl -sS https://api.apidog.com/
# curl: (6) Could not resolve host: api.apidog.com
Enter fullscreen mode Exit fullscreen mode

Voici les résultats que nous avons obtenus sur macOS. Vérifiez ensuite que le serveur fonctionne toujours en lui envoyant un 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
Enter fullscreen mode Exit fullscreen mode

Avec le réseau désactivé, le serveur a répondu avec trois outils : un qui lit la spec OpenAPI, un qui lit les fichiers référencés par $ref, et un qui rafraîchit la spec. C'est tout ce dont Codex a besoin pour écrire du code contre votre API.

Sous macOS, ajoutez --log-denials à n'importe quel appel codex sandbox pour afficher les refus Seatbelt après la sortie de la commande. C'est le moyen le plus rapide d'identifier un dossier dont le serveur a légitimement besoin.

Étape 5 : laisser Codex maintenir la spec à jour avec la CLI Apidog

Un serveur hors ligne lit un fichier, donc quelque chose doit mettre à jour ce fichier. Confiez cette tâche à votre agent de programmation avec la CLI Apidog. Elle s'exécute en dehors du sandbox MCP, sous les règles de commande normales de Codex, et le serveur MCP n'a jamais besoin de jeton.

Configuration (une seule fois) :

npm install -g apidog-cli
apidog auth login --with-token <your-access-token>
Enter fullscreen mode Exit fullscreen mode

Si vous n'avez pas encore intégré la CLI à Codex, suivez notre guide How to Use the Apidog CLI in Codex.

Demandez à votre agent :

Export the OpenAPI 3.1 spec for Apidog project 1234567 to ./openapi.json,
then run test scenario 637132 in environment 358171 against it and give me
a CLI summary. Don't touch any .env file.
Enter fullscreen mode Exit fullscreen mode

Commandes exécutées par l'agent (options issues de apidog export --help et 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
Enter fullscreen mode Exit fullscreen mode

export écrase le fichier lu par le serveur sandboxé, de sorte que l'appel MCP suivant voit les nouveaux endpoints. run exécute votre scénario de test et écrit un rapport JUnit pour la CI. Ajoutez --upload-report si vous voulez consulter l'exécution dans l'application Apidog. Le forfait Free d'Apidog couvre jusqu'à 4 utilisateurs.

Quand le serveur a besoin du réseau : la liste de domaines autorisés

Le mode projet doit pouvoir joindre api.apidog.com. La solution de Codex est le proxy réseau : définissez enabled = true, listez les domaines autorisés et activez la fonctionnalité network_proxy. Voici la forme documentée dans l'article d'OpenAI, adaptée à 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
Enter fullscreen mode Exit fullscreen mode

Un deny explicite l'emporte sur allow, et le proxy ne résout un nom d'hôte qu'une fois qu'une règle l'a autorisé, car même une requête DNS peut exfiltrer des données. OpenAI prévient que des wildcards trop larges peuvent encore permettre une exfiltration via DNS ; listez donc des hôtes précis.

Une mise en garde tirée de notre propre test. Sur notre Mac, le proxy a démarré et injecté HTTP_PROXY et consorts dans le sandbox, mais il a répondu 403 avec x-proxy-error: blocked-by-allowlist pour tous les hôtes, y compris ceux qui étaient autorisés. Notre machine route le DNS via une application de proxy locale, ce qui explique peut-être ce comportement. Exécutez codex sandbox --permission-profile apidog-mcp-live -- curl -sS https://api.apidog.com/ sur votre propre machine avant de vous fier à ce profil. Si l'hôte autorisé échoue, revenez au mode OAS de l'étape 1.

Quel profil choisir ?

Type de serveur Réseau Écritures sur le système de fichiers Exemple
Lecture de fichiers locaux uniquement enabled = false cache npm + son propre dossier de données Serveur MCP Apidog avec --oas
Appel à une API connue Proxy + domaines précis cache npm + son propre dossier de données Serveur MCP Apidog avec --project-id
Nécessite un accès Internet ouvert À éviter, ou isoler dans une VM Le plus restreint possible Serveurs de navigation web

Si vous utilisez Codex en équipe, les administrateurs peuvent utiliser allowed_permission_profiles dans requirements.toml pour limiter les profils que les utilisateurs peuvent sélectionner. Et si vous êtes tenté de désactiver le sandbox à la place, lisez pourquoi contourner le sandbox Codex revient exactement à renoncer à cette protection.

FAQ

Codex sandboxe-t-il les serveurs MCP par défaut ? Non. OpenAI précise que Codex ne place pas dans un sandbox la commande qui démarre un serveur MCP stdio configuré dans config.toml. Vous ajoutez le sandbox vous-même en lançant le serveur via codex sandbox --permission-profile <name> --.

Pourquoi utiliser npx --offline plutôt que npx -y ? Avec network.enabled = false, npx ne peut rien télécharger. --offline lui indique d'utiliser la copie que vous avez mise en cache via npx -y --package=<pkg>@<version> -c true, et épingler la version empêche une nouvelle version de remplacer le code.

Le sandbox protège-t-il mes clés d'API ? Il bloque ce que vous refusez. Le profil :workspace autorise des lectures étendues ; ajoutez donc des règles deny pour les fichiers .env et les dossiers de secrets. Avec le réseau désactivé, le serveur ne peut pas non plus envoyer ce qu'il lit.

Cela fonctionne-t-il sous Linux et Windows ? Oui. Le même profil s'applique partout ; Codex l'impose via bubblewrap et seccomp sous Linux, et via un sandbox basé sur MXC sur les appareils Windows compatibles. Testez chaque machine avec codex sandbox, car les chemins et les configurations DNS diffèrent.

Puis-je sandboxer d'autres serveurs MCP de la même manière ? Oui. N'importe quel serveur stdio fait l'affaire : identifiez les dossiers dans lesquels il écrit et les hôtes qu'il appelle, attribuez-lui un profil, enrobez la commande, pré-mettez le paquet en cache et testez. L'exemple d'OpenAI sandboxe @modelcontextprotocol/server-memory avec des écritures limitées à ~/.npm et ~/mcp-data.

Top comments (0)