Claude Code : déployer des serveurs MCP à toute l'équipe avec le réglage managedMcpServers

Sans managedMcpServers, chaque dev de l'équipe configure ses serveurs MCP à la main dans son ~/.claude/settings.json. Résultat prévisible : trois versions différentes du connecteur GitHub, deux personnes qui ont oublié Sentry, une qui a branché un MCP tiers non audité récupéré sur GitHub la veille. Zéro visibilité côté lead tech, zéro contrôle sur ce qui parle à quoi. Le réglage managedMcpServers, livré dans Claude Code 2.1.259 le 2 septembre 2026, corrige ça en poussant une liste de serveurs MCP depuis un fichier de policy que l'utilisateur ne peut pas modifier. Cet article détaille où le placer, comment le structurer, comment le distribuer, et où sont les pièges. Si tu n'as pas encore stabilisé ta stack Claude Code au niveau équipe, commence par le guide Apprendre Claude qui pose les fondations, puis reviens ici pour la partie gouvernance.

Ce que managedMcpServers change concrètement

Dans Claude Code, un serveur MCP se configure via la clé mcpServers dans les settings utilisateur, projet ou local. Chaque dev fait ce qu'il veut, ajoute, retire, modifie. Utile en exploration solo, ingérable dès que l'équipe passe cinq personnes.

managedMcpServers vit dans un fichier de policy géré (managed-settings.json) qui prend la précédence sur toutes les autres sources. Concrètement : ce que tu déclares dans ce fichier est imposé, apparaît dans claude mcp list chez tous les utilisateurs, et ne peut être ni supprimé ni modifié via la CLI. Attention à une limite documentée : managedMcpServers ne prend en charge que les serveurs distants HTTP et SSE. Les entrées qui déclarent une command à exécuter (serveurs stdio locaux) sont ignorées par ce réglage précis.

Le mental model est simple. mcpServers = ce que l'utilisateur préfère. managedMcpServers = ce que l'organisation impose. Les deux coexistent, la policy gagne en cas de conflit.

Pour les serveurs stdio locaux (un binaire interne qui tourne sur le poste dev), tu passes soit par le fichier managed-mcp.json (mécanisme plus ancien mais toujours supporté, déployé à un chemin système fixe), soit par un couplage avec des règles d'autorisation. On y revient dans la section gouvernance.

Où placer le fichier de policy selon l'OS

Les chemins sont figés par Claude Code, tu ne les choisis pas. C'est le point : ils demandent des droits admin pour être écrits, donc un dev ne peut pas les remplacer depuis son shell.

Le fichier managed-mcp.json (mécanisme complémentaire pour les serveurs stdio et le contrôle exclusif) suit la même logique, aux mêmes emplacements racines. Un managed-mcp.json déployé prend le contrôle exclusif des serveurs MCP : les utilisateurs ne peuvent plus ajouter ni modifier d'autres serveurs, y compris ceux fournis par des plugins. Une carte vide ({"mcpServers": {}}) désactive MCP entièrement pour l'organisation.

Ordre de précédence à retenir, du plus fort au plus faible : managed settings (entreprise) > arguments CLI (--settings) > settings projet local (.claude/settings.local.json) > settings projet partagé (.claude/settings.json) > settings utilisateur (~/.claude/settings.json). La policy entreprise gagne toujours.

Anatomie d'un bloc managedMcpServers

Un exemple concret avec un MCP tiers en HTTP et un MCP interne exposé en SSE via un reverse proxy d'entreprise :

{
  "managedMcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
      }
    },
    "docs-internes": {
      "type": "sse",
      "url": "https://mcp.corp.internal/docs/sse",
      "headers": {
        "X-Team-Token": "${INTERNAL_MCP_TOKEN}"
      }
    }
  }
}

Trois champs à connaître. type vaut http ou sse. url pointe vers l'endpoint distant. headers permet d'injecter l'auth. Les variables d'environnement au format ${VAR} sont résolues au moment de l'appel, ce qui te permet de ne jamais écrire un secret en clair dans le fichier de policy.

Pour un panorama des serveurs MCP tiers officiels et communautaires que tu peux inscrire ici, va voir la référence outils MCP et la nouvelle spec MCP 2026-07-28, qui a rendu le protocole stateless et modifié la façon dont certains serveurs gèrent leur session.

Distribuer la config à toute l'équipe

Trois voies, selon la maturité de ton parc.

MDM (Jamf, Intune, Kandji). Le plus propre pour un parc géré. Tu pousses managed-settings.json comme un fichier de config standard, avec permissions root:wheel 644 sur macOS/Linux, ou via une policy Group Policy sur Windows. Les mises à jour se propagent au prochain check-in. C'est la seule voie qui garantit qu'un dev ne peut pas simplement chmod le fichier pour le neutraliser.

Script d'onboarding. Si tu n'as pas de MDM, un script bash lancé au setup poste fait le job pour démarrer :

#!/usr/bin/env bash
set -euo pipefail

CONFIG_DIR="/Library/Application Support/ClaudeCode"
CONFIG_FILE="$CONFIG_DIR/managed-settings.json"
SOURCE="./managed-settings.json"

sudo mkdir -p "$CONFIG_DIR"
sudo cp "$SOURCE" "$CONFIG_FILE"
sudo chown root:wheel "$CONFIG_FILE"
sudo chmod 644 "$CONFIG_FILE"

echo "Policy Claude Code déployée. Vérifie avec : claude mcp list"

Dépôt Git privé + installeur maison. Tu versionnes managed-settings.json dans un repo infra-claude-code, tu tag chaque release (v1.2.0, v1.2.1), un pipeline CI construit un installeur signé que tes devs lancent au premier setup et sur mise à jour. Tu gagnes en traçabilité (qui a ajouté quel serveur MCP, quand, revue par qui) et tu peux rollback si une nouvelle version casse quelque chose.

Peu importe la voie choisie, versionne le fichier comme du code, avec code review et changelog. Un serveur MCP mal configuré peut faire fuiter des données ou consommer des tokens en boucle.

Gouverner ce qui tourne : allowlist, secrets, audit

managedMcpServers impose ce qui doit être là. Il n'empêche pas un dev d'ajouter en plus ses propres serveurs MCP en user settings. Si tu veux verrouiller vraiment, tu couples avec l'une des deux mesures suivantes.

Première option : allowedMcpServers et deniedMcpServers définissent des listes blanches et noires qui filtrent tous les serveurs, quelle que soit leur source (managed, user, project, plugin). Le réglage allowManagedMcpServersOnly: true va plus loin et rend la liste blanche gérée seule autoritaire, en ignorant celles définies côté utilisateur.

Deuxième option : déployer un managed-mcp.json à côté du managed-settings.json. Ce fichier prend le contrôle exclusif : plus aucun ajout côté user ne fonctionne. Tentative de claude mcp add ? Message d'erreur explicite : "Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers". Approche brutale mais efficace pour un environnement sensible.

Pour les secrets : jamais en clair dans le fichier. Tu référencies une variable d'environnement système (posée par ton MDM ou ton secret manager type Vault, AWS Secrets Manager, 1Password Connect) et Claude Code la résout au runtime. Si un dev pousse par erreur le fichier sur un repo public, tu perds la topologie de tes MCP mais pas les credentials.

Audit trimestriel recommandé : liste les MCP autorisés, croise avec l'usage réel (via les logs de ton reverse proxy interne pour les MCP maison, ou via la commande /cost qui affiche désormais le détail cache par session), retire ceux qui ne servent plus, révise les scopes de token. Pour l'usage API sous-jacent, garde en tête les clés API personnelles et comptes de service qui donnent à chaque identifiant un propriétaire explicite.

Cas limites et erreurs fréquentes

JSON invalide. Une virgule en trop, un guillemet mal fermé, et Claude Code refuse silencieusement la policy. Aucun message d'erreur à l'ouverture. Vérifie systématiquement avant de déployer :

# Validation locale
jq empty managed-settings.json && echo "OK" || echo "JSON invalide"

# Vérification côté poste après déploiement
claude mcp list

Si un serveur attendu n'apparaît pas dans claude mcp list, ta policy n'est pas prise en compte. Contrôle les permissions du fichier et les logs de démarrage.

Binaire absent du PATH système. Sur les serveurs MCP stdio poussés via managed-mcp.json, si le binaire (npx, uvx, un exécutable maison) n'est pas dans le PATH du process Claude Code au lancement, le serveur crash au premier appel. Utilise des chemins absolus dans command, ou garantis la présence des runtimes via ton MDM. Ce genre de setup à l'échelle mérite d'être pensé en amont, la configuration de Claude Code sur poste dev couvre les prérequis à standardiser.

Conflit avec une config user existante. Un dev qui avait déjà github configuré en user va voir la version managed prendre le dessus, sans être notifié. S'il avait des variables d'environnement locales différentes, ses scripts qui appellent le MCP GitHub via une convention de nommage vont changer de comportement. Communique explicitement avant le rollout, et documente comment purger les anciennes configs user : claude mcp remove <name>.

Workflow de rollout recommandé

Le déploiement en big bang casse la prod des devs. Séquence pragmatique :

1. Inventaire : liste les MCP réellement utilisés dans l'équipe (demande à chacun, ne te fie pas à la doc théorique).
2. Sélection : garde 3 à 5 serveurs au premier déploiement. Ceux dont l'usage est prouvé et dont tu as validé la sécurité.
3. Poste pilote : déploie sur un dev volontaire pendant une semaine complète. Recueille les frictions concrètes.
4. Documentation : un README interne qui explique quel serveur sert à quoi, avec un exemple de prompt Claude Code utilisant chacun.
5. Déploiement par vagues : équipe backend d'abord, puis frontend, puis data. Chaque vague à une semaine d'intervalle.
6. Itération : retour à l'étape 1 tous les trois mois pour retirer ce qui ne sert plus et intégrer les nouveaux besoins.

Ce cadre s'inscrit dans une démarche plus large d'automatiser sa stack avec Claude et MCP. Une fois que ta gouvernance MCP tient debout, tu peux commencer à construire des agents et des produits qui s'appuient dessus en confiance. Si tu veux structurer cette étape avec une cohorte de builders qui ont les mêmes contraintes, jette un œil à Construire votre produit IA en 5 semaines : le programme couvre le déploiement d'agents Claude Code en environnement d'équipe, avec la gouvernance MCP comme brique intégrée.