MCP : Model Context Protocol - Tutoriel

Ce tutoriel vous guide pas à pas pour configurer le Model Context Protocol dans Claude Code, connecter des serveurs MCP externes (GitHub, Brave Search, Playwright) et sécuriser vos intégrations. Vous apprendrez à ajouter, tester et utiliser des outils MCP en moins de 30 minutes.

Le Model Context Protocol (MCP) est un standard ouvert créé par Anthropic qui permet à Claude Code de communiquer avec des services externes via des serveurs d'outils normalisés. MCP prend en charge trois modes de transport : stdio, SSE et HTTP streamable.

MCP a été conçu pour unifier la manière dont les modèles de langage accèdent aux données et aux actions extérieures, réduisant le code d'intégration nécessaire par rapport aux approches ad hoc.

Pour une vue d'ensemble du protocole avant de plonger dans la pratique, consultez la page de référence MCP : Model Context Protocol qui couvre l'architecture et les concepts fondamentaux.

Quels sont les prérequis avant de commencer ?

Vérifiez que votre environnement remplit ces conditions avant de lancer la configuration MCP.

Exécutez ces commandes pour valider votre environnement :

node --version # v22.x attendu
claude --version # v2.1+ attendu
npm --version # v9.x+ attendu

Si vous débutez avec Claude Code, suivez d'abord le tutoriel d'installation et premier lancement pour mettre en place votre environnement complet.

Durée estimée pour l'ensemble du tutoriel : environ 25 minutes.

À retenir : Node.js 22 LTS, Claude Code 2.1+ et npm 9+ sont les trois prérequis indispensables pour travailler avec MCP.

Comment installer votre premier serveur MCP ? (~3 min)

Étape 1 : Ajoutez un serveur MCP filesystem via la CLI

Lancez la commande suivante pour enregistrer le serveur filesystem :

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /chemin/vers/votre/projet

Étape 2 : Vérifiez que le serveur est bien enregistré

Listez les serveurs MCP configurés pour confirmer l'ajout :

claude mcp list

Étape 3 : Testez la connexion au serveur

Exécutez la commande de diagnostic pour valider le fonctionnement :

claude mcp list

✅ Vérification : la sortie doit afficher le serveur filesystem dans la liste avec son statut. Si vous le voyez listé, votre premier serveur MCP est opérationnel.

⚠️ Si vous voyez "spawn npx ENOENT", vérifiez que Node.js est bien dans votre PATH. Exécutez which npx pour localiser le binaire. Sur macOS, relancez votre terminal après l'installation de Node.js.

MCP filesystem est un serveur qui expose des opérations de lecture/écriture de fichiers à Claude Code. Son débit dépend du modèle et du client qui l'interrogent, pas d'un nombre fixe de requêtes par seconde.

À retenir : la commande claude mcp add suffit pour enregistrer n'importe quel serveur MCP compatible stdio en une seule ligne.

Comment fonctionnent les trois modes de transport MCP ?

MCP définit trois protocoles de transport pour la communication entre Claude Code et les serveurs d'outils. Chaque mode convient à un cas d'usage spécifique.

Transport stdio : le mode par défaut

Le transport stdio est le mode standard pour les serveurs locaux. Claude Code lance le processus serveur et communique via stdin/stdout. Comme tout se passe en local via un processus enfant, c'est généralement le mode offrant la latence la plus faible.

claude mcp add mon-serveur -- npx -y @mon-org/mon-serveur-mcp

Transport SSE : pour les serveurs distants

Le transport SSE (Server-Sent Events) permet de connecter des serveurs MCP hébergés à distance. Le transport SSE est désormais déprécié : privilégiez HTTP streamable quand le serveur le supporte. Utilisez SSE uniquement pour les serveurs distants qui n'offrent pas encore le transport HTTP.

claude mcp add --transport sse mon-serveur-distant https://mon-serveur.example.com/mcp/sse

Transport HTTP streamable : pour les API cloud

Le transport HTTP streamable est le mode recommandé pour les déploiements en production sur le cloud. ce mode remplace progressivement SSE pour les intégrations serveur-à-serveur.

Pour mieux comprendre comment gérer les différents contextes de connexion, le tutoriel sur la gestion du contexte vous donne des stratégies complémentaires.

À retenir : choisissez stdio pour le local, HTTP streamable pour les déploiements cloud en production, et réservez SSE (déprécié) aux serveurs distants qui ne proposent pas encore HTTP.

Comment configurer le serveur MCP GitHub ? (~5 min)

Le serveur MCP GitHub est un connecteur qui expose les API GitHub (issues, pull requests, repositories) directement dans Claude Code. En pratique, il réduit très significativement le temps passé à copier-coller des informations entre GitHub et votre terminal.

Étape 4 : Créez un token GitHub personnel

Ouvrez GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens. Générez un token avec les permissions repo, issues et pull_requests.

Étape 5 : Ajoutez le serveur MCP GitHub

Exécutez la commande suivante en remplaçant YOUR_GITHUB_PAT par votre token :

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

✅ Vérification : lancez claude mcp list et confirmez que github apparaît avec le statut connected.

⚠️ Si vous voyez "Authentication failed", votre token est expiré ou n'a pas les bonnes permissions. Régénérez un token avec les scopes repo et issues cochés.

Pour approfondir la gestion des permissions et tokens, consultez le tutoriel Permissions et sécurité qui détaille les bonnes pratiques d'authentification.

Étape 6 : Testez les outils GitHub en session

Ouvrez une session Claude Code et demandez à Claude d'utiliser les outils GitHub :

claude
# Dans la session, tapez :
> Liste les 5 dernières issues ouvertes de mon repo

Claude Code détecte automatiquement les outils MCP disponibles et les utilise quand votre requête le nécessite. Le serveur GitHub expose plusieurs outils, comme list_issues, create_pull_request et search_repositories.

À retenir : le serveur MCP GitHub nécessite un token fine-grained avec les permissions repo et issues pour fonctionner correctement.

Comment ajouter Brave Search et Playwright comme serveurs MCP ? (~5 min)

Étape 7 : Configurez Brave Search pour la recherche web

Le serveur MCP Brave Search est un connecteur qui donne à Claude Code un accès à la recherche web via l'API Brave. Concrètement, vous obtenez des résultats de recherche directement dans votre session de développement.

Obtenez une clé API sur brave.com/search/api (un palier gratuit est disponible, dans la limite d'un quota mensuel), puis exécutez :

claude mcp add --env BRAVE_API_KEY=VOTRE_CLE --transport stdio brave-search -- npx -y @modelcontextprotocol/server-brave-search

Étape 8 : Configurez Playwright pour les tests navigateur

Le serveur MCP Playwright est un connecteur qui permet à Claude Code de contrôler un navigateur : naviguer, cliquer, capturer des screenshots et extraire du contenu. Chaque instance de navigateur lancée consomme de la mémoire supplémentaire, à prendre en compte sur les machines aux ressources limitées.

claude mcp add playwright -- npx -y @playwright/mcp@latest

Le nombre exact d'outils varie selon la version de chaque serveur : utilisez /mcp en session pour afficher la liste à jour.

✅ Vérification : exécutez claude mcp list : vous devez voir au minimum github, brave-search et playwright avec le statut connected.

Pour des astuces d'optimisation sur l'utilisation de vos serveurs MCP au quotidien, explorez les astuces MCP compilées par la communauté.

À retenir : Brave Search et Playwright s'installent chacun en une commande et étendent Claude Code avec la recherche web et le contrôle navigateur.

Comment utiliser les outils MCP en session Claude Code ? (~5 min)

Une fois vos serveurs configurés, Claude Code détecte et utilise automatiquement les outils MCP disponibles. Voici comment interagir avec eux concrètement.

Invocation automatique

Claude Code analyse votre requête et sélectionne le bon outil MCP. Vous n'avez pas besoin de spécifier quel serveur utiliser : le modèle choisit l'outil adapté en fonction du contexte.

claude
# Exemples de requêtes qui déclenchent des outils MCP :
> Recherche les articles récents sur MCP # → Brave Search
> Crée une issue "Fix login bug" sur mon repo # → GitHub
> Fais un screenshot de localhost:3000 # → Playwright

Vérification des outils disponibles

Listez les outils exposés par chaque serveur avec la commande /mcp dans une session Claude Code :

# Dans une session Claude Code :
> /mcp

Cette commande affiche tous les serveurs connectés et leurs outils. Selon sa complexité, un serveur MCP peut exposer d'un seul outil à de nombreux outils.

Si vous débutez avec les sessions interactives de Claude Code, le guide sur vos premières conversations vous aidera à maîtriser les commandes de base.

Gestion des permissions d'outils

Quand Claude Code souhaite utiliser un outil MCP, il vous demande votre autorisation. Vous pouvez accepter pour la requête courante, pour toute la session, ou configurer une autorisation permanente.

Le système de mémoire de Claude Code, documenté dans le tutoriel CLAUDE.md, vous permet de stocker des règles de permission persistantes pour vos outils MCP favoris.

À retenir : Claude Code sélectionne automatiquement l'outil MCP adapté à votre requête : vous interagissez en langage naturel, sans syntaxe spéciale.

Comment configurer et sécuriser vos serveurs MCP ? (~5 min)

Portées de configuration : projet vs global

MCP propose plusieurs portées de configuration. La portée locale (par défaut) stocke la configuration dans ~/.claude.json (privée, propre au projet courant). La portée projet (flag --scope project) stocke dans un fichier .mcp.json à la racine du projet, partagé via le contrôle de version. La portée utilisateur (flag --scope user) stocke dans le fichier ~/.claude.json pour un accès depuis tous vos projets.

# Configuration locale (par défaut)
claude mcp add mon-serveur -- npx -y @mon-org/serveur

# Configuration projet (flag --scope project, partagée via .mcp.json)
claude mcp add --scope project mon-serveur -- npx -y @mon-org/serveur

# Configuration utilisateur (flag --scope user)
claude mcp add --scope user mon-serveur -- npx -y @mon-org/serveur

Sécurisation des tokens et clés API

Ne stockez jamais vos tokens en dur dans les fichiers de configuration versionnés. Utilisez des variables d'environnement ou un gestionnaire de secrets.

# Méthode recommandée : variable d'environnement
export GITHUB_PAT=$(security find-generic-password -s "github-mcp" -w)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer $GITHUB_PAT"

Le SFEIR Institute recommande de toujours utiliser un gestionnaire de secrets pour les environnements de production. Les bonnes pratiques de sécurité exigent une rotation des tokens tous les 90 jours.

Pour aller plus loin sur la sécurisation de votre environnement Claude Code, le tutoriel Permissions et sécurité couvre les autorisations granulaires et le sandboxing.

⚠️ Si vous versionnez accidentellement un token, révoquez-le immédiatement sur la plateforme concernée et exécutez git filter-branch ou git-filter-repo pour purger l'historique.

À retenir : utilisez la portée projet pour partager des serveurs avec l'équipe via .mcp.json et la portée utilisateur pour les serveurs que vous réutilisez dans tous vos projets, et ne versionnez jamais vos secrets.

Quels sont les serveurs MCP les plus populaires ?

L'écosystème MCP compte des centaines de serveurs communautaires. Voici les plus utilisés classés par catégorie.

Les serveurs GitHub et les serveurs de recherche web figurent parmi les plus installés par la communauté.

Pour retrouver les réponses aux questions fréquentes sur le protocole, la FAQ MCP traite les problèmes de compatibilité et de dépannage les plus courants.

Les commandes slash essentielles de Claude Code incluent /mcp pour diagnostiquer vos serveurs directement en session.

Vous souhaitez maîtriser MCP et l'ensemble des fonctionnalités de Claude Code dans un cadre structuré ? La formation Claude Code de SFEIR Institute, d'une durée d'un jour, vous fait pratiquer l'ajout et la configuration de serveurs MCP sur des labs concrets.

Pour une montée en compétence plus large sur le développement assisté par IA, la formation Développeur Augmenté par l'IA de deux jours couvre MCP, le prompt engineering et l'intégration CI/CD. Les développeurs déjà à l'aise trouveront dans la formation Développeur Augmenté par l'IA – Avancé un programme d'un jour centré sur les architectures MCP multi-serveurs et les patterns avancés.

À retenir : GitHub, Brave Search et Playwright sont les trois serveurs MCP incontournables pour couvrir le DevOps, la recherche et le testing.

Comment déboguer un serveur MCP qui ne répond pas ?

Le débogage MCP suit une procédure systématique. Voici comment diagnostiquer et résoudre les problèmes les plus fréquents.

Étape 9 : Diagnostiquez avec la commande list

Exécutez la commande de diagnostic pour inspecter l'état des serveurs :

claude mcp list

Cette commande affiche le statut de connexion de tous les serveurs configurés et les éventuelles erreurs. En pratique, la grande majorité des problèmes MCP viennent d'un chemin binaire incorrect ou d'une variable d'environnement manquante.

Étape 10 : Réinitialisez un serveur en erreur

Si le serveur est en état disconnected, supprimez-le et réajoutez-le :

claude mcp remove nom-du-serveur
claude mcp add nom-du-serveur -- npx -y @org/serveur-mcp

⚠️ Si le serveur met trop de temps à démarrer, ajustez le délai d'attente via la variable d'environnement MCP_TIMEOUT (par exemple MCP_TIMEOUT=10000 pour 10 secondes) ou vérifiez votre connexion réseau pour les serveurs SSE/HTTP.

Le guide de démarrage rapide MCP fournit une checklist condensée pour valider rapidement votre configuration.

Concrètement, les erreurs les plus fréquentes sont :

• Binaire introuvable (ENOENT) : le binaire npx ou node n'est pas trouvé → vérifiez votre PATH
• Permissions insuffisantes (EACCES) : droits manquants → exécutez chmod +x sur le binaire
• Délai de démarrage dépassé : le serveur ne démarre pas dans le temps imparti → augmentez MCP_TIMEOUT et vérifiez les dépendances npm
• Erreur d'authentification : token invalide ou expiré → régénérez votre token
• Connexion refusée : le port SSE/HTTP est bloqué → vérifiez votre pare-feu

À retenir : claude mcp list est votre outil de diagnostic principal : la grande majorité des problèmes se résolvent en vérifiant le PATH et les variables d'environnement.

Comment aller plus loin avec MCP ?

Vous maîtrisez maintenant les bases du Model Context Protocol. Voici les pistes pour approfondir votre pratique.

Créez votre propre serveur MCP

Le SDK MCP, disponible en TypeScript et Python, permet de créer des serveurs personnalisés avec relativement peu de code. Un serveur MCP minimal nécessite uniquement de définir un handler de transport et de déclarer ses outils via le protocole JSON-RPC 2.0.

# Dans une session Claude Code, installez le plugin d'aide à la création de serveurs MCP
> /plugin marketplace add anthropics/claude-plugins-official
> /plugin install mcp-server-dev@claude-plugins-official

# Puis lancez l'assistant de génération de serveur MCP
> /mcp-server-dev:build-mcp-server

Intégrez MCP dans votre workflow CI/CD

MCP fonctionne en mode headless dans les pipelines CI/CD. Configurez vos serveurs dans le fichier .claude/settings.json de votre repository pour que chaque développeur de l'équipe dispose des mêmes outils automatiquement.

L'écosystème MCP évolue vite : de nouveaux serveurs sont publiés chaque semaine sur le registry officiel. Surveillez les annonces d'Anthropic et de la communauté pour rester à jour.

À retenir : le SDK MCP vous permet de créer des serveurs personnalisés et l'intégration CI/CD rend vos outils MCP disponibles pour toute l'équipe.