Tutoriel MCP Claude Code : ajouter des serveurs correctement
Connectez Context7, Playwright ou n'importe quel serveur MCP à Claude Code — transports, portées, fichier .mcp.json, clés API et panneau /mcp, en un seul passage illustré.
L'essentiel
- Une commande installe n'importe quel serveur : claude mcp add name -- npx -y @scope/package pour un serveur local, ou claude mcp add --transport http name url pour un serveur distant.
- Trois transports existent : stdio exécute une commande sur votre machine, SSE est la forme distante historique, et le HTTP streamable est l'option distante moderne.
- Trois portées décident qui profite du serveur : local (vous seul), project (partagé via .mcp.json) et user (tous vos projets).
- Lancez /mcp dans une session pour voir l'état et les outils ; le premier appel d'outil demande une autorisation, à accorder une fois ou toujours.
Claude Code Tutorial #7 - MCP Servers
Chaîne : The Net Ninja14:16
Claude Code MCP: How to Add MCP Servers (Complete Guide)
Chaîne : Leon van Zyl17:58
Model Context Protocol (MCP) — official Claude Code docs
Docs : code.claude.com/docs
Les captures d'écran viennent du chapitre de The Net Ninja — un enregistrement plein écran bien propre. Le décryptage des commandes, des portées et des correctifs Windows suit la vidéo plus complète de Leon van Zyl ainsi que la documentation officielle.
Les images appartiennent à leurs créateurs respectifs et sont créditées ici avec des liens profonds vers les moments exacts ; le texte est de nous.
De zéro à deux serveurs MCP fonctionnels
Partie 1 · Ce que les serveurs MCP apportent
- 1
Ce que MCP apporte à Claude Code
Claude Code embarque des outils pour les fichiers et le shell, mais tout ce qui dépasse votre base de code lui échappe. MCP — le Model Context Protocol — est le mécanisme standard d'Anthropic pour brancher des outils supplémentaires : un serveur expose des capacités, et Claude Code les appelle comme n'importe quel outil intégré.
La diapositive du cours qui définit MCP en une ligne.Voir à 0:52 - 2
Choisissez des serveurs selon le travail
Chaque serveur apporte ses propres outils. Le serveur Supabase sait lister les tables, déployer des edge functions et exécuter du SQL ; Playwright pilote un vrai navigateur ; Context7 sert une documentation de framework à jour. Commencez par celui qui supprime votre corvée la plus fréquente.
L'exemple Supabase : trois outils, un service externe.Voir à 1:24 - 3
Trouvez la commande d'installation dans le README
Les auteurs de serveurs publient une commande Claude Code prête à l'emploi dans leur README — Context7 et Playwright le font tous les deux. Les annuaires comme PulseMCP permettent de parcourir ce qui existe avant de choisir.
Le README de Playwright MCP documente fonctionnalités et prérequis.Voir à 2:02 - 4
Comprenez les trois types de transport
La documentation officielle sépare les installations locales et distantes. Un serveur stdio exécute une commande sur votre machine — c'est le défaut. Les serveurs SSE et HTTP sont des endpoints distants ; SSE est l'ancienne forme, remplacée par le HTTP streamable. La syntaxe de claude mcp add varie légèrement selon le cas.
La page de la doc comparant stdio local aux SSE et HTTP distants.Voir à 3:02
Partie 2 · Ajouter votre premier serveur
- 5
Ajoutez Context7 avec la portée project
Depuis le terminal : claude mcp add context7 --scope project -- npx -y @upstash/context7-mcp. Le nom est à votre convenance, tout ce qui suit le double tiret est la commande à lancer, et --scope project écrit le serveur dans la config partagée du projet plutôt que dans la vôtre.
La commande exacte pour ajouter le serveur de documentation Context7.Voir à 5:22 - 6
Lisez le .mcp.json généré
Les serveurs en portée project atterrissent dans un fichier .mcp.json à la racine du dépôt, sous la clé mcpServers. Chaque entrée enregistre le type — stdio ici — plus la commande et ses arguments : la même forme que Cursor ou Claude Desktop.
Dans .mcp.json : type, command et args pour le serveur stdio.Voir à 6:42 - 7
Sur Windows, attention au préfixe cmd /c
Sur un Windows natif sans WSL, les commandes stdio exigent cmd /c devant npx pour que le shell se referme proprement après le serveur. La doc le signale dans un encadré d'avertissement, et la vidéo montre la modification exacte.
L'encadré d'avertissement officiel pour les serveurs stdio sous Windows.Voir à 3:24 - 8
Vérifiez que le fichier est dans le dépôt
Après un ajout en portée project, .mcp.json apparaît dans l'explorateur comme un nouveau fichier non suivi, prêt à être commité pour que vos coéquipiers aient les mêmes serveurs. Les serveurs en portée locale ne touchent jamais ce fichier.
Un nouveau .mcp.json à la racine du projet, non suivi et prêt à être commité.Voir à 8:32 - 9
Vous préférez le distant ? Passez en HTTP
Quand un stdio local fait des siennes, l'endpoint distant est la porte de sortie rapide : claude mcp add --transport http context7 --scope project https://mcp.context7.com/mcp. Pas de processus local ni de npm — Claude Code parle directement à l'URL.
La variante HTTP de la commande d'ajout vers l'endpoint Context7.Voir à 8:36 - 10
Contrôlez la connexion dans /mcp
Démarrez Claude Code et lancez /mcp. Chaque serveur affiche son état et sa liste d'outils. Un échec se règle souvent par la reconnexion intégrée ; sinon, la section dépannage ci-dessous couvre les causes courantes.
Le panneau /mcp montrant context7 connecté avec ses deux outils.Voir à 9:22
Partie 3 · Utiliser les serveurs en conditions réelles
- 11
Appelez le serveur dans un vrai prompt
Demandez ce que les outils intégrés ne savent pas faire et nommez le serveur : « vérifie la doc Tailwind la plus récente par rapport à mon fichier CSS global — utilise context7 ». Joindre le fichier via une mention @ ancre la réponse dans votre code.
Le prompt qui demande la doc Tailwind à jour via context7.Voir à 9:38 - 12
Approuvez l'appel d'outil
La première fois qu'un outil de serveur s'exécute, Claude Code demande la permission. Approuvez une fois, ou choisissez « toujours autoriser » pour les serveurs de confiance afin que les appels suivants passent sans pause.
La carte d'autorisation pour l'outil resolve-library-id de Context7.Voir à 10:00 - 13
Lisez la réponse documentée
L'outil renvoie les passages pertinents — ici les consignes sur les variables de thème de Tailwind v4 — avec le coût en tokens affiché, et Claude Code l'applique à votre fichier. Tout l'intérêt est là : des réponses issues de la documentation courante plutôt que des suppositions tirées des données d'entraînement.
La réponse get-library-docs confirmant la configuration du thème.Voir à 10:15 - 14
Gravez l'habitude dans CLAUDE.md
Tapez le symbole dièse pour ajouter une mémoire de projet, par exemple : « utilise Context7 pour une doc à jour quand tu implémentes de nouvelles bibliothèques ou frameworks ». La ligne atterrit dans CLAUDE.md et chaque session suivante en hérite.
Une mémoire CLAUDE.md d'une ligne qui fait de Context7 le réflexe par défaut.Voir à 10:42 - 15
Ajoutez un deuxième serveur : Playwright
Reprenez le schéma pour l'automatisation du navigateur : claude mcp add playwright --scope project -- cmd /c npx @playwright/mcp@latest — et retirez la partie cmd /c sur macOS ou Linux. Un dépôt, plusieurs serveurs, un seul fichier de config.
Ajout du serveur Playwright MCP avec la portée project.Voir à 11:22 - 16
Regardez-le piloter le navigateur
Demandez à Claude Code d'ouvrir une page et de la résumer — Playwright navigue, clique et lit, puis rend compte. Entre la doc de Context7 et le navigateur de Playwright, la plupart des tâches externes sont à un prompt de distance.
Playwright MCP naviguant vers un site pour en faire le résumé.Voir à 12:42
Variables d'environnement, en-têtes et clés API
Les serveurs distants et les API authentifiées demandent des identifiants. Claude Code les prend en variables d'environnement pour les serveurs stdio et en en-têtes pour les distants — sans éditer de fichier de config.
- 1Serveurs stdio : claude mcp add myserver -e API_KEY=your-key -e ZONE=your-zone -- npx -y @some/mcp-server — répétez le drapeau -e pour chaque variable, juste après le nom du serveur.
- 2Serveurs HTTP distants : claude mcp add --transport http myserver https://example.com/mcp --header "Authorization: Bearer your-key" — l'en-tête part avec chaque appel d'outil.
- 3Rappel des portées : local garde le serveur pour vous dans ce projet, project le partage via .mcp.json, user l'installe dans tous vos projets. À définir avec -s ou --scope lors de l'ajout.
- 4Retirer un serveur : claude mcp remove name — en portée project, commitez le changement de .mcp.json pour que le serveur disparaisse aussi chez vos coéquipiers.
Les valeurs passées avec -e sont stockées en clair dans le fichier de config. Privilégiez des clés à périmètre réduit quand l'API le permet, et ne commitez jamais de vrais identifiants dans un .mcp.json en portée project.
Quand /mcp affiche failed
Presque tous les échecs MCP dans Claude Code remontent à quelques causes. Parcourez cette liste avant de supprimer et réinstaller quoi que ce soit.
- 1Unknown option -y sous Windows : certains terminaux butent sur ce drapeau npm. Lancez la commande d'ajout depuis PowerShell ou l'invite de commandes, ou retirez -y, ajoutez le serveur, puis remettez -y dans le tableau args du .mcp.json à la main.
- 2stdio échoue sur Windows natif : préfixez la commande avec cmd /c — par exemple cmd /c npx -y @some/package@latest. Sans WSL c'est obligatoire, et le tag @latest évite les builds en cache périmés.
- 3Statut failed : ouvrez /mcp et rebranchez — les échecs passagers s'effacent généralement à la deuxième tentative. Sinon, le panneau indique l'emplacement du log du serveur pour la vraie erreur.
- 4Serveur absent dans un autre projet : c'est la portée qui fait son travail. Les serveurs en portée project vivent dans le .mcp.json de ce dépôt ; passez en portée user pour une installation à l'échelle de la machine.
- 5Serveur connecté mais jamais utilisé : nommez-le dans le prompt — « utilise context7 pour vérifier la doc » — ou ajoutez une mémoire CLAUDE.md, car sans consigne les modèles prennent leurs outils intégrés habituels.
En dernier recours : claude mcp remove name, redémarrez le terminal, puis rajoutez le serveur avec le transport qui marche à coup sûr — la variante HTTP distante est la plus prévisible.