Configurer un serveur MCP pour qu'il s'installe lui-même : trois hôtes, trois mécanismes, pièges

La configuration des serveurs MCP implique souvent l'édition manuelle d'un fichier JSON — et chaque hôte utilise un fichier et un format différents. Cette friction empêche les développeurs d'utiliser des serveurs qu'ils utiliseraient autrement. Cet article détaille trois hôtes, leurs mécanismes d'installation et les pièges qui vous surprennent.

Trois hôtes, trois mécanismes

• VS Code : Dispose d'une vraie API — registerMcpServerDefinitionProvider. Déclarez un fournisseur dans package.json et renvoyez la définition du serveur à l'exécution. VS Code affiche une invite de consentement. Pas d'édition de fichier de configuration. Le plus propre, mais nécessite de fournir une extension VS Code.
• Cursor : Pas d'API native. Écrivez .cursor/mcp.json directement avec la clé racine mcpServers.
• Claude Code : Utilisez la CLI. N'écrivez pas le fichier à la main. Exécutez par exemple :
  claude mcp add --transport stdio --scope <user|local> --env … <nom> -- node <chemin>

Six pièges à éviter

1. Ce fichier JSON n'est pas le vôtre. Le mcp.json de Cursor contient les autres serveurs de l'utilisateur. Lisez, fusionnez votre entrée, préservez les clés non liées — n'écrasez pas.
2. Survivez à un fichier malformé. Si le fichier existe mais est un JSON invalide, ne le traitez pas comme vide et ne l'écrasez pas. Idem pour les erreurs de lecture/permissions — relancez. Traiter « impossible de lire » comme « rien là » corrompra les configurations.
3. Sauvegardez + écrivez atomiquement. Copiez le fichier existant avant d'y toucher, écrivez dans un fichier temporaire, puis renommez sur la cible. Un mcp.json à moitié écrit casse l'éditeur.
4. Installer deux fois doit être un no-op, pas une erreur. La CLI de Claude génère une erreur si l'entrée existe déjà — donc remove puis add. Pour les hôtes basés sur fichiers, indexez par nom de serveur et remplacez sur place. Réexécuter doit converger, pas dupliquer.
5. La portée change tout. L'installation au niveau utilisateur vs projet change l'emplacement du fichier de configuration et ce dont le serveur a besoin (par exemple, dossier de données explicite vs découverte ascendante). Choisissez délibérément.
6. Vous devez rester à jour. La version enregistrée dérive de ce que vous fournissez. Ajoutez une vérification : « ce qui est installé est-il toujours la version que je fournis ? » et un chemin de réinstallation propre. Un bouton montre l'état : installer, mettre à jour ou à jour.

La leçon principale : l'installation manuelle échoue parce qu'un humain qui colle un extrait ne connaît pas le chemin absolu, la bonne portée, les variables d'environnement, ni comment fusionner en toute sécurité. Le code d'installation, lui, le sait.