Claude Code : ajouter un serveur MCP sans écrire votre jeton dans la commande (add-json en stdin)

Un jeton collé dans `claude mcp add` peut rester dans l'historique du shell. Voici comment lire le JSON en stdin avec `add-json`, choisir la bonne portée et vérifier que rien n'a fuité.

Pour ajouter un serveur MCP à Claude Code sans exposer ton jeton, lis le JSON de configuration depuis l'entrée standard : cat server.json | claude mcp add-json <nom> -. Cette forme existe depuis la version 2.1.327 de Claude Code (17 novembre 2026). Le jeton n'est alors pas tapé dans la commande : il n'est pas enregistré dans l'historique du shell, à condition de ne pas le saisir en clair ailleurs. Cet article suit le parcours pour apprendre Claude et s'adresse à quelqu'un qui a déjà un terminal ouvert.

En bref :

  • Depuis Claude Code 2.1.327 (17 novembre 2026), claude mcp add-json <nom> - lit le JSON du serveur sur l'entrée standard, ce qui garde le jeton hors de la ligne de commande.
  • La forme classique claude mcp add-json <nom> '<json>' reste valable, mais un jeton écrit dedans peut rester dans l'historique du shell.
  • Trois portées existent : local (défaut, stockée dans ~/.claude.json), project (.mcp.json, partagé par Git) et user (tous les projets).
  • Le fichier .mcp.json accepte ${VAR} et ${VAR:-défaut} : on le commite sans valeur secrète.
  • claude mcp add ne valide pas les identifiants : un faux jeton est accepté et l'échec apparaît plus tard dans /mcp.

Pourquoi ne pas coller son jeton dans claude mcp add ?

Un jeton écrit dans une commande peut rester dans l'historique du shell (.zsh_history, .bash_history), c'est un conseil de prudence général, pas une alerte de la documentation d'Anthropic. La commande classique n'est pas dangereuse en soi : elle devient un souci quand le secret y est tapé en clair, puis copié dans un tutoriel, un script ou un message.

Le scénario typique : tu suis un guide, tu colles la clé d'un serveur type Notion ou GitHub dans la commande, tout fonctionne. Trois semaines plus tard, tu retrouves la clé en tapant ↑ dans le terminal, ou dans un fichier d'historique synchronisé avec une sauvegarde. Rien de spectaculaire, juste un secret qui traîne à un endroit où personne ne pense à le chercher. Autant éviter de l'y mettre.

Comment fonctionne claude mcp add-json ?

claude mcp add-json prend un nom de serveur et une chaîne JSON qui décrit le serveur : la même structure que celle d'une entrée de .mcp.json. Là où claude mcp add assemble la configuration à partir d'options, add-json reçoit l'objet complet, ce qui est plus confortable dès qu'il y a plusieurs variables d'environnement ou en-têtes HTTP.

Forme habituelle, avec le JSON entre apostrophes, ici pour un serveur HTTP qui attend un en-tête d'autorisation :

claude mcp add-json mon-serveur '{"type":"http","url":"https://exemple.com/mcp","headers":{"Authorization":"Bearer MON_JETON"}}'

Ce que tu dois savoir sur les champs :

ChampRôle
type"http", "sse" ou "ws" pour un serveur distant ; sans type, l'entrée est traitée comme stdio
urlAdresse du serveur distant
headersEn-têtes HTTP, c'est là que va un jeton Authorization
command / args / envPour un serveur stdio local, la commande à lancer, ses arguments et ses variables d'environnement

Le piège le plus courant : une entrée avec une url mais sans type est lue comme du stdio et échoue. Ajoute toujours "type": "http" (ou sse, ws) pour un serveur distant. Les détails de chaque commande sont dans la documentation officielle de Claude Code sur MCP.

Comment passer le JSON en stdin pour garder le secret hors de la commande ?

Remplace le JSON en argument par un tiret : claude mcp add-json <nom> - lit alors le JSON sur l'entrée standard. Cette forme date de la version 2.1.327 de Claude Code ; elle se lance hors d'une session Claude Code (elle n'est pas disponible à l'intérieur d'une session). Vérifie ta version avec claude --version avant de commencer.

Pas à pas, avec une variable d'environnement :

  1. Mets le jeton dans une variable de ta session, sans l'écrire dans la commande qui suit. Le plus simple : read -s TOKEN (bash ou zsh), qui te demande la valeur sans l'afficher ni l'enregistrer dans l'historique.
  2. Fabrique le JSON à partir de cette variable et envoie-le sur stdin :
read -s TOKEN
printf '{"type":"http","url":"https://exemple.com/mcp","headers":{"Authorization":"Bearer %s"}}' "$TOKEN" | claude mcp add-json mon-serveur -
unset TOKEN
  1. Vérifie l'enregistrement (voir la section sur les contrôles plus bas).

Ici, la commande tapée ne contient que $TOKEN, jamais sa valeur : c'est le shell qui la substitue au moment de l'exécution. Si ta clé est dans un gestionnaire de secrets en ligne de commande (1Password CLI, Bitwarden CLI, pass, trousseau macOS), remplace simplement la première ligne par une lecture depuis l'outil :

TOKEN=$(pass show mcp/mon-serveur)
printf '{"type":"http","url":"https://exemple.com/mcp","headers":{"Authorization":"Bearer %s"}}' "$TOKEN" | claude mcp add-json mon-serveur -
unset TOKEN

Autre usage documenté : cat server.json | claude mcp add-json <nom> - avec un fichier préparé. Attention, ce fichier contiendrait alors le jeton en clair sur le disque : réserve-le à un fichier hors dépôt, ou génère-le à la volée comme ci-dessus.

Local, projet ou utilisateur : quelle portée choisir pour un serveur avec jeton ?

Pour un serveur qui demande un jeton, choisis la portée local (défaut) ou user, et réserve la portée project aux configurations sans valeur secrète. Le fichier de portée project, .mcp.json, est partagé par le contrôle de version : tout ce qui y est écrit voyage avec le dépôt.

Portée (--scope)Où c'est stockéQui la voitRisque de fuite
local (défaut)~/.claude.jsonToi, sur ce projet seulementFaible : rien n'est partagé
project.mcp.json à la racine du projetToute l'équipe via GitÉlevé si le jeton est écrit en clair
user~/.claude.jsonToi, sur tous tes projetsFaible : rien n'est partagé

Si l'équipe doit partager la configuration, garde le jeton hors du fichier : .mcp.json accepte ${VAR} et ${VAR:-défaut} dans command, args, env, url et headers. Le fichier se partage alors sans valeur secrète, et chacun définit la variable dans son propre environnement. Les serveurs de portée project demandent par ailleurs une approbation interactive avant usage, ce qui évite qu'un dépôt cloné lance un serveur à ton insu. Un détail utile : dans l'url et les headers d'un serveur distant, Claude Code ne développe pas ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN ni AWS_BEARER_TOKEN_BEDROCK (lus comme vides) ; pour en passer un, copie-le d'abord dans une variable portant un autre nom.

Deux autres mécanismes existent pour garder un secret hors de la config : headersHelper, qui exécute une commande à la connexion et fusionne sa sortie JSON dans les en-têtes, et pour un secret client OAuth, l'option --client-secret, qui ouvre une saisie masquée et stocke le secret dans le trousseau système sur macOS ou dans un fichier d'identifiants, pas dans la config.

Comment vérifier que le serveur est bien ajouté et que le secret n'a pas fuité ?

Trois commandes suffisent pour l'enregistrement : claude mcp list liste les serveurs, claude mcp get <nom> affiche celui que tu viens d'ajouter, et la commande /mcp dans une session Claude Code montre l'état de connexion. Le point à retenir : claude mcp add ne valide pas les identifiants. Un faux jeton est accepté sans broncher, et l'échec n'apparaît que dans /mcp. Un serveur présent dans la liste n'est donc pas forcément un serveur qui fonctionne.

Ensuite, le contrôle d'hygiène :

  1. Relis ton historique de shell (history | grep -i bearer, ou cherche une partie de la clé) pour t'assurer qu'elle n'y figure pas.
  2. Si tu as utilisé un fichier .mcp.json, cherche le jeton dans le dépôt : git log -S 'début_du_jeton', ou un scanner de secrets comme gitleaks.
  3. Rappelle-toi que ~/.claude.json contient la config des portées local et user : traite-le comme un fichier sensible et ne le synchronise pas dans un dépôt public.

Si le jeton a fuité, supprimer la ligne d'historique ne règle rien : elle a pu être sauvegardée ou synchronisée. Révoque le jeton chez le fournisseur et génères-en un nouveau. Les bonnes pratiques de périmètre et de révocation sont décrites dans la documentation GitHub sur la gestion des jetons d'accès.

Que faire quand la commande échoue (JSON invalide, serveur qui ne se connecte pas) ?

Deux familles de problèmes, qui n'ont pas la même cause : la commande refuse le JSON, ou la commande passe mais le serveur ne se connecte pas. Le premier cas se voit tout de suite, le second seulement dans /mcp.

Un cas de bout en bout : tu lances la commande avec printf et un jeton qui contient un guillemet ou une barre oblique inverse. Le JSON devient invalide, la commande échoue. Teste d'abord le JSON seul, sans l'envoyer à Claude Code : printf ... | python3 -m json.tool. Si la sortie est une erreur, corrige l'échappement avant de recommencer. Les jetons composés de lettres, chiffres et tirets passent sans souci ; ce sont les caractères spéciaux qui cassent. Sous PowerShell, les guillemets doubles imbriqués se comportent autrement que sous bash ou zsh : préfère passer par un fichier JSON préparé et lu sur stdin.

Si la commande réussit mais que /mcp montre un échec de connexion, les causes habituelles sont un jeton expiré ou mal copié, un type manquant (une url sans "type": "http" est lue comme du stdio), ou, pour un serveur stdio, une commande introuvable comme npx absent du PATH. Pour repartir proprement : claude mcp remove <nom>, avec --scope si le même nom existe à plusieurs niveaux, puis refais l'ajout. Pour comprendre ce qu'un serveur peut faire avant de le brancher, la spécification du Model Context Protocol décrit les types de transport.

Questions fréquentes

Quelle différence entre claude mcp add et claude mcp add-json ?

claude mcp add construit la configuration à partir d'options en ligne de commande, alors que claude mcp add-json reçoit directement un objet JSON complet, identique à ce qu'on écrirait dans .mcp.json. add-json est plus pratique pour les serveurs avec plusieurs variables d'environnement ou en-têtes HTTP.

Mon jeton est déjà dans l'historique du shell, que faire ?

Supprimer la ligne de l'historique ne suffit pas si elle a pu être sauvegardée ou synchronisée. Révoque le jeton chez le fournisseur, génères-en un nouveau, puis ajoute le serveur avec la méthode par stdin ou par variable d'environnement.

Peut-on partager une config MCP avec son équipe sans partager les jetons ?

Oui : place la configuration dans .mcp.json au niveau du projet en référençant des variables avec la syntaxe ${VAR}, et laisse chaque personne définir sa propre valeur dans son environnement. Le fichier se commite sans risque puisqu'il ne contient aucun secret.

Où Claude Code stocke-t-il les serveurs MCP ajoutés ?

Selon la portée choisie : dans ~/.claude.json pour les portées local et user, dans .mcp.json à la racine du dépôt pour la portée project. Vérifie la documentation officielle de ta version, l'emplacement exact a pu évoluer entre versions.

Comment supprimer un serveur MCP ajouté par erreur ?

La commande claude mcp remove <nom> retire le serveur de la portée concernée. Ajoute --scope si le même nom existe à plusieurs niveaux, puis relance claude mcp list pour confirmer.

Et maintenant : quels serveurs MCP brancher ensuite ?

Une fois la méthode en main, le gain vient du choix des serveurs : un accès à une base de données, à un outil de tickets, à ton CRM ou à tes documents internes évite de recopier des données à la main dans une conversation. Un exemple d'entrepreneur : brancher son outil de facturation en lecture seule, puis demander à Claude un point sur les factures impayées de la semaine, sans exporter de CSV. Chaque serveur supplémentaire ajoute un jeton à gérer : applique à chacun la même discipline (stdin, portée adaptée, révocation en cas de doute) et donne-lui le minimum de droits.

Pour explorer les serveurs existants, regarde l'annuaire des serveurs MCP ; pour les clés d'un fournisseur, la page sur l'obtention d'une clé API Anthropic ; pour enchaîner plusieurs connecteurs dans un vrai flux de travail, le dossier automatiser sa stack avec MCP. Si tu veux aller du serveur MCP à un produit complet, cette formation de cinq semaines pour bâtir ton produit IA reprend ces briques sur des projets concrets.

Pilier 6 · Mastery

Automatiser sa stack avec Claude et MCP

Connecter Claude à votre CRM, Notion, Slack, et construire des workflows fiables. Le territoire des opérationnels et des Builders.

Découvrir le pilier complet →