Jetons en clair dans votre configuration MCP : comment les en sortir

Où chaque agent de code garde la configuration de ses serveurs MCP, comment repérer les jetons qui y sont écrits, ce que zn-gate init --wrap-mcp en fait (il ne les retire pas), et comment sortir les valeurs et annuler chaque étape.

Voir le .md

Un serveur MCP a souvent besoin d'un jeton, et le moyen le plus rapide de le lui donner est de le coller dans le env ou les headers du serveur, dans le fichier de configuration de l'agent. Le jeton se retrouve alors dans un fichier texte en clair, dans votre dossier personnel ou dans votre projet. Cette page indique où chaque agent garde ce fichier, comment y repérer les jetons, ce que zn-gate init --wrap-mcp fait et ne fait pas avec eux, et comment sortir les valeurs et annuler chaque étape. Pour la vue d'ensemble des secrets et des agents de code, voir le guide avec la liste de contrôle.

Où chaque agent garde ses serveurs MCP

Agent Fichier utilisateur Fichier de projet Réécrit par init --wrap-mcp
Claude Code ~/.claude.json .mcp.json à la racine du projet ~/.claude.json
Claude Desktop claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/) aucun ce fichier
Cursor ~/.cursor/mcp.json .cursor/mcp.json ~/.cursor/mcp.json
Codex CLI ~/.codex/config.toml (ou $CODEX_HOME/config.toml) .codex/config.toml (projets de confiance uniquement) le fichier utilisateur
OpenCode ~/.config/opencode/opencode.json (ou opencode.jsonc) opencode.json dans le projet le fichier utilisateur
Antigravity ~/.gemini/config/mcp_config.json .agents/mcp_config.json les fichiers utilisateur (zn-gate cherche aussi ~/.gemini/antigravity/mcp_config.json)

~/.claude.json contient aussi les serveurs configurés pour un seul projet, sous projects. init --wrap-mcp n'enveloppe que les mcpServers de premier niveau de ce fichier, donc les entrées par projet restent non enveloppées ; audit les vérifie bien.

Les chemins de Claude Code, Cursor, Codex CLI et OpenCode viennent de la documentation de chaque agent ; ceux de Claude Desktop et d'Antigravity suivent la documentation de zn-gate et la page Antigravity. init --wrap-mcp ne touche pas aux fichiers de projet : un jeton dans un fichier de projet reste où il est. Pour VS Code, Windsurf, Cline, Zed, JetBrains et Continue, voir Éditeurs.

Repérer les jetons

npx -y zn-gate reach
npx -y zn-gate audit --include-home

reach demande zn-gate 1.12.0 ou plus récent. Les deux commandes sont en lecture seule. Elles signalent une valeur secrète écrite dans la configuration d'un agent (règle ZNA011) et n'affichent jamais la valeur. Lancez audit depuis un dossier de projet pour vérifier aussi ses fichiers ; --include-home ajoute les fichiers de votre dossier personnel du tableau ci-dessus (sauf ceux de Claude Desktop et d'Antigravity). Les deux utilisent la détection propre à zn-gate : un jeton dans un format qu'elle ne connaît pas peut passer inaperçu, lisez donc aussi vous-même vos fichiers de configuration.

Ce que zn-gate init --wrap-mcp fait d'un jeton

Il ne le retire pas. Pour chaque serveur local (stdio), il ne change que la commande de démarrage : la commande d'origine devient l'argument de npx -y zn-gate shield --. Tout le reste de l'entrée, y compris env, reste tel quel. Le shield vérifie ensuite les descriptions d'outils, les arguments des appels et la sortie des outils, et retire de la sortie les secrets qu'il reconnaît avant que votre agent la lise (détails). Cela protège ce que l'agent reçoit du serveur. Cela ne protège pas le fichier.

Autres faits sur la commande :

  • Les serveurs distants (URL) sont laissés tels quels : un jeton dans une entrée headers reste.
  • Avant d'écrire un fichier, elle le copie à côté de l'original sous le nom <fichier>.bak.<horodatage>. Cette copie est le fichier tel qu'il était, jetons compris.
  • Les fichiers OpenCode avec commentaires et les entrées Codex avec des args sur plusieurs lignes ne sont pas réécrits ; init les signale comme « wrap manually ».
npx -y zn-gate init --dry-run    # aperçu, ne change rien
npx -y zn-gate init --shadow     # enveloppe, journalise seulement
npx -y zn-gate init --wrap-mcp   # enveloppe et applique
npx -y zn-gate init --revert     # restaure la dernière sauvegarde de chaque fichier

Sortir la valeur

Mettez le jeton dans une variable d'environnement et faites référencer cette variable par son nom dans la configuration. Ce que dit la documentation de chaque agent :

  • Claude Code, dans .mcp.json : ${VAR} (et ${VAR:-default}) est développé dans command, args, env, url et headers. Pour url et headers d'un serveur distant, la documentation de Claude Code ajoute une limite pour les variables d'identifiants ; lisez-la avant de vous y fier.
  • Cursor, dans mcp.json : ${env:NAME} est résolu dans command, args, env, url et headers.
  • Codex CLI, dans config.toml : env_vars transmet des variables de l'environnement de Codex à un serveur stdio, bearer_token_env_var nomme la variable qui contient un jeton bearer, et env_http_headers associe des noms d'en-têtes à des noms de variables. Le fichier ne contient que des noms.
  • OpenCode : {env:VARIABLE_NAME} est substitué dans les fichiers de configuration, et sa documentation MCP le montre dans les en-têtes.
  • Claude Desktop, Antigravity et les autres éditeurs : nous n'avons pas vérifié de moyen de référencer une variable d'environnement dans leurs fichiers MCP, cette page n'en donne donc aucun.

Exemple pour Cursor, avec un serveur et une variable inventés (EXAMPLE_API_TOKEN) :

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"],
      "env": { "EXAMPLE_API_TOKEN": "${env:EXAMPLE_API_TOKEN}" }
    }
  }
}

La variable doit exister dans l'environnement du processus de l'agent : définissez-la là où vous lancez l'agent (le profil de votre shell, ou la façon dont votre système d'exploitation définit les variables), redémarrez l'agent et vérifiez que le serveur se connecte. Gardez à l'esprit qu'un profil de shell est lui-même un fichier texte brut que l'agent peut lire : y mettre le jeton ne fait que le déplacer vers un autre fichier. Mieux vaut utiliser le trousseau de votre système d'exploitation ou un gestionnaire de secrets pour fournir la variable au lancement de l'agent, ou au moins garder le jeton dans un fichier situé hors de tout dossier que l'agent ouvre.

Un ordre sûr

  1. Lancez npx -y zn-gate reach et notez quels fichiers contiennent un jeton.
  2. Remplacez chaque jeton par une référence à une variable d'environnement comme ci-dessus et redémarrez l'agent.
  3. Renouvelez tous les jetons qui ont un jour été dans le fichier, si ce fichier a été commité, sauvegardé, partagé ou poussé, si un agent a pu le lire, ou si le jeton est apparu dans une transcription. Une valeur retirée du fichier reste valable tant que vous ne la révoquez pas chez le fournisseur.
  4. Seulement ensuite, lancez npx -y zn-gate init --dry-run, puis --shadow, puis --wrap-mcp. La sauvegarde écrite contient le fichier sans les jetons.
  5. Si vous avez enveloppé d'abord : supprimez les fichiers .bak.<horodatage> à côté de vos fichiers de configuration une fois les jetons sortis, car ils contiennent encore les anciennes valeurs.
  6. Relancez npx -y zn-gate reach.

À quoi sert zn env shadow, et à quoi il ne sert pas

zn env shadow .env déplace les valeurs d'un fichier .env dans le coffre local de zn-gate et laisse des marqueurs dans le fichier (Scrubber). Il lit des lignes CLÉ=valeur. Les fichiers de configuration MCP sont en JSON ou en TOML, et la documentation de zn-gate ne décrit pas env shadow pour eux : ne le pointez pas vers l'un d'eux.

Comment annuler chaque étape

  • Envelopper : npx -y zn-gate init --revert recopie la dernière .bak.<horodatage> sur chaque fichier de configuration. Tout ce que vous avez modifié dans le fichier après l'enveloppement est perdu, et si la sauvegarde contient des jetons, ils reviennent. Après l'étape 2 ci-dessus, annulez plutôt à la main : dans chaque entrée, remettez la commande et les arguments d'origine à la place de npx -y zn-gate shield --.
  • Références à des variables d'environnement : ne remettez la valeur dans le fichier que si vous y êtes obligé, et jamais dans un fichier que vous commitez.
  • env shadow : zn env unshadow FICHIER --backup NOM, avec le nom qu'env shadow a affiché.

Limites

  • La détection trouve les formats connus ; un jeton sans format connu peut passer inaperçu.
  • L'enveloppement vérifie ce qu'un serveur renvoie et ce que l'agent lui envoie. Il n'empêche pas un autre programme de lire le fichier de configuration.
  • Un fichier de projet comme .mcp.json est hors de portée de init --wrap-mcp.
  • Un jeton déplacé dans une variable d'environnement est visible de tout programme lancé avec cet environnement.

Questions fréquentes

zn-gate init --wrap-mcp retire-t-il les jetons de ma configuration MCP ? Non. Il change la commande de démarrage des serveurs locaux et laisse env et headers tels quels.

La sauvegarde contient-elle mes jetons ? Oui, s'ils étaient dans le fichier au moment de l'enveloppement. Supprimez les fichiers .bak.<horodatage> après avoir sorti les valeurs.

Puis-je utiliser zn env shadow sur mcp.json ? Il n'est documenté que pour les fichiers .env.

Comment vérifier qu'il ne reste rien ? Lancez npx -y zn-gate reach et npx -y zn-gate audit --include-home, et lisez vous-même les fichiers.

Sources