Aller au contenu
Floskool

Chapitre 2 · Ajouter et connecter

Serveurs locaux, clés et fichier .mcp.json partagé

Leçon gratuite 8 minGroupe Claude Code & IA

Suis cette formation dans ton espace : ta progression est gardée, et la communauté répond à tes questions.

Suivre gratuitement

Pourquoi un serveur local

Tous les outils n'ont pas de serveur en ligne. Certains serveurs MCP se lancent sur ton ordinateur (type stdio). Ils peuvent alors accéder à des choses locales, ou servir d'intermédiaire vers un service qui fonctionne avec une clé.

Exemple : Nadia, traiteur, tient son catalogue de plats et ses allergènes dans une base Airtable (un tableur en ligne). La documentation de Claude Code donne un exemple de serveur local pour Airtable. Avec lui, Claude peut lire le catalogue pour préparer un devis.

La syntaxe d'un serveur local

claude mcp add [options] <nom> -- <commande> [arguments]

Le point clé, c'est le double tiret -- : tout ce qui suit est la commande qui lance le serveur, transmise telle quelle. Avant le --, tu mets les options de Claude Code (--transport stdio, --scope, --env).

L'exemple Airtable de la documentation, avec une clé factice :

claude mcp add --env AIRTABLE_API_KEY=**** --transport stdio airtable -- npx -y airtable-mcp-server
  • --env NOM=valeur (forme courte : -e) passe une variable d'environnement (une valeur que le programme lit au démarrage) au serveur.
  • La documentation conseille de placer une autre option, comme --transport stdio, entre --env et le nom du serveur.
  • npx est un outil livré avec Node.js qui télécharge et lance un programme. Il faut donc Node.js installé.

Si tu es sous Windows et qu'un serveur local lancé avec npx refuse de démarrer, consulte la documentation officielle de Claude Code et celle du serveur : les réglages propres à Windows y sont décrits, ne les devine pas.

Attention : un serveur local tourne avec tes droits

Un serveur local est un programme qui s'exécute sur ta machine, avec tes droits. Avant d'en installer un :

  • vérifie qu'il vient d'un éditeur reconnu (page officielle, dépôt connu) ;
  • lis sa documentation pour savoir ce qu'il fait ;
  • préfère toujours la version officielle à une copie.

Où vont les clés ?

Avec --env, la clé est enregistrée dans ta configuration personnelle (~/.claude.json) pour les portées local et user. Ce fichier n'est pas partagé, mais il contient alors un secret : ne l'envoie jamais à personne et ne le montre pas à l'écran.

Partager une configuration sans partager tes clés

Pour une équipe, le fichier .mcp.json (portée project) est pratique. Mais il est partagé : aucune clé ne doit y être écrite. La documentation prévoit une solution, les variables d'environnement dans le fichier. On écrit ${NOM} à la place de la valeur, et chaque personne définit NOM sur sa propre machine. On peut aussi donner une valeur par défaut avec ${NOM:-valeur}.

Exemple tiré de la documentation :

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

D'après la documentation, ces variables fonctionnent dans command, args, env, url et headers. Si une variable n'est pas définie et n'a pas de valeur par défaut, Claude Code affiche un avertissement.

Deux raccourcis utiles

  • Ajouter depuis une configuration JSON que te donne un éditeur : claude mcp add-json <nom> '<json>'.
  • Importer les serveurs déjà configurés dans Claude Desktop : claude mcp add-from-claude-desktop.

Copie ce prompt pour préparer un .mcp.json d'équipe propre :

Contexte : je veux partager avec mon équipe la configuration des serveurs MCP [noms] de ce projet.
Objectif : un fichier .mcp.json à la racine, sans aucune clé écrite dedans.
Contraintes : ne me demande jamais la valeur d'une clé et ne la lis pas. Utilise des variables ${NOM} pour toute clé ou jeton. Ne lance aucune commande d'installation.
Format attendu : le contenu proposé du fichier, puis la liste des variables que chaque personne doit définir sur sa machine, avec leur rôle.
Validation : montre-moi le fichier avant de l'enregistrer et attends mon accord.

Les erreurs à éviter

  • Oublier le -- avant la commande du serveur local : Claude Code prendrait la commande pour ses propres options.
  • Écrire une vraie clé dans .mcp.json. Même « juste pour tester » : le test d'aujourd'hui devient le partage de demain.
  • Installer un serveur local inconnu. Il tourne avec tes droits, sur ta machine.

À toi de jouer

Ouvre (ou demande à Claude d'ouvrir en lecture) le .mcp.json d'un de tes projets s'il existe. Vérifie qu'aucune clé n'y apparaît en clair. S'il n'y en a pas, rédige avec le prompt ci-dessus un .mcp.json de démonstration avec une variable ${MA_CLE}, sans l'enregistrer : l'objectif est de comprendre la forme.