Claude Code et serveurs MCP : guide d’intégration pas à pas

Claude Code × MCP = un agent qui sort enfin de sa cage

Claude Code parle à du code. C’est son travail. Sauf que sans MCP, il est borgne : il voit ce que tu lui colles dans le prompt, rien d’autre. Avec le Model Context Protocol, tu lui donnes des yeux sur ton filesystem, sur GitHub, sur tes outils de build. Ce guide t’explique comment brancher tout ça, étape par étape. Aujourd’hui tu vas apprendre à :

• Comprendre ce que MCP apporte concrètement à Claude Code et pourquoi ça change la donne
• Configurer un fichier JSON de serveurs MCP sans te planter dans les chemins
• Connecter le serveur MCP Filesystem pour que Claude Code lise et écrive tes fichiers locaux
• Intégrer GitHub via MCP pour gérer des issues et interagir avec l’API depuis l’agent
• Combiner plusieurs serveurs MCP dans un workflow de construction d’app de bout en bout

Ce dont t’as besoin avant de commencer

1. Un accès Claude Code actif

Claude Code est inclus dans tous les plans payants de Claude, à partir du plan Pro à 20 $US/mois. Sans plan actif, tu n’as pas accès à l’agent. Vérifie ton accès sur claude.ai avant d’aller plus loin.

2. Node.js installé sur ta machine

La plupart des serveurs MCP officiels tournent sur Node.js. Installe la version LTS depuis nodejs.org. Vérifie avec node --version dans ton terminal : tu as besoin d’une version récente.

3. Claude Code CLI installé

Claude Code se pilote via la ligne de commande. Installe-le avec npm : npm install -g @anthropic-ai/claude-code. Vérifie l’installation avec claude --version.

4. Un éditeur de texte pour éditer du JSON

Tu vas toucher des fichiers de configuration JSON. VSCode, Zed, Neovim, peu importe. L’important : un éditeur qui surligne les erreurs de syntaxe JSON, parce qu’une virgule mal placée et le serveur MCP refuse de démarrer.

5. Un token GitHub (pour la partie GitHub)

Pour brancher le serveur MCP GitHub, tu auras besoin d’un Personal Access Token avec les scopes repo et read:org. Génère-le dans les paramètres de ton compte GitHub sous Developer settings.

Pourquoi MCP change la façon de travailler avec Claude Code

Avant d’entrer dans les étapes, il faut comprendre ce que MCP change fondamentalement. Sans MCP, Claude Code est un agent qui lit le code que tu lui montres et génère du code en réponse. C’est déjà utile. Sauf que dans la vraie vie, un projet ne vit pas dans le prompt : il vit dans des fichiers, des dépôts, des bases de données, des APIs. Tu es obligé de copier-coller constamment pour combler l’écart entre l’agent et ton environnement réel. MCP (Model Context Protocol) est le protocole ouvert qu’Anthropic a développé pour éliminer cet écart. Plutôt que de copier-coller, tu connectes directement les ressources à l’agent. Claude Code supporte MCP nativement : c’est un fait vérifié, pas une feature expérimentale qu’on teste en beta.

Le principe technique est simple. Un serveur MCP est un processus qui s’exécute en arrière-plan sur ta machine. Il expose des outils (lire un fichier, créer une issue, faire un commit) via une interface standardisée. Claude Code sait appeler ces outils automatiquement quand le contexte le demande. Tu configures quels serveurs sont disponibles dans un fichier JSON. C’est tout le concept. Ce qui distingue MCP des intégrations classiques : le protocole est bidirectionnel. Claude Code ne fait pas que lire des données depuis tes serveurs, il peut aussi écrire, créer, modifier. Un agent qui peut lire ton filesystem ET y écrire des fichiers en réponse à une instruction, c’est un workflow de développement qualitativement différent.

Le workflow, étape par étape

La configuration MCP de Claude Code vit dans un fichier JSON appelé claude_desktop_config.json (pour l’app desktop) ou dans un fichier de configuration de projet pour les usages CLI. L’emplacement exact dépend de ton système d’exploitation. Sur macOS, le fichier de configuration global se trouve ici :

~/Library/Application Support/Claude/claude_desktop_config.json

Sur Windows, il est dans :

%APPDATA%\Claude\claude_desktop_config.json

Sur Linux, cherche du côté de :

~/.config/claude/claude_desktop_config.json

Si le fichier n’existe pas encore, crée-le. Claude Code le lit au démarrage. Toute modification nécessite un redémarrage de l’application pour prendre effet. La structure de base ressemble à ceci :

{
"mcpServers": {
"nom-du-serveur": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/chemin/vers/répertoire"],
"env": {}
}
}
}

Chaque entrée dans mcpServers est un serveur distinct. La clé (ici nom-du-serveur) est le nom que Claude Code utilise pour référencer le serveur. Le champ command est l’exécutable à lancer. Les args sont les arguments passés à cet exécutable. Le champ env contient les variables d’environnement, utile pour passer des tokens d’API sans les mettre en clair dans le fichier.

Le serveur MCP Filesystem est le point de départ le plus concret. Il donne à Claude Code la capacité de lire et d’écrire des fichiers dans les répertoires que tu lui autorises explicitement. Pas un accès global à tout ton disque dur : tu définis exactement quels chemins sont accessibles. Installe le package si tu veux le faire tourner localement (optionnel avec npx, qui le télécharge à la volée) :

npm install -g @modelcontextprotocol/server-filesystem

Puis ajoute cette entrée dans ton claude_desktop_config.json :

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/toi/projets",
"/Users/toi/documents/notes"
]
}
}
}

Tu peux passer plusieurs chemins en argument. Le serveur Filesystem ne donne accès qu’à ces chemins précis. Si Claude Code essaie de lire un fichier en dehors de ces répertoires, le serveur refuse.

Ce qu’on ne dit pas assez sur le serveur Filesystem : il expose des outils distincts pour lire un fichier (read_file), lister le contenu d’un répertoire (list_directory), créer ou modifier un fichier (write_file), et créer des répertoires (create_directory). Claude Code choisit quel outil appeler selon l’instruction. Tu n’as pas besoin de les appeler manuellement. Après avoir modifié le fichier JSON, redémarre Claude Code. Dans l’interface, tu verras une icône ou une indication que les serveurs MCP sont actifs. Tu peux ensuite demander à Claude Code de lister les fichiers dans un répertoire configuré : il appellera le serveur Filesystem automatiquement.

Un test concret pour vérifier que ça marche : demande à Claude Code "Liste tous les fichiers TypeScript dans /Users/toi/projets/mon-projet". Si le serveur Filesystem est correctement configuré, tu verras Claude Code appeler l’outil list_directory puis filtrer les résultats. Si tu vois un message d’erreur de connexion au serveur, le problème est dans la config JSON ou dans les permissions du chemin.

Le serveur MCP GitHub ouvre un accès complet à l’API GitHub depuis Claude Code. L’agent peut lire le contenu de fichiers dans des dépôts distants, créer des issues, commenter sur des pull requests, et même créer des branches. Ce qui change concrètement : tu n’as plus à aller dans l’interface GitHub pour les tâches répétitives de gestion de dépôt. D’abord, génère ton Personal Access Token sur GitHub : Settings → Developer settings → Personal access tokens → Tokens (classic). Coche les scopes repo (accès complet aux dépôts privés et publics) et read:org si tu travailles avec des organisations. Copie le token immédiatement après la création, tu ne le reverras pas. Stocke le token dans une variable d’environnement système pour ne pas le mettre en clair dans ton JSON :

# Dans ton .zshrc ou .bashrc
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_tonTokenIci"

Puis ajoute le serveur dans ta config :

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/toi/projets"
]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
}
}
}
}

La syntaxe ${VARIABLE} dans le champ env demande à Claude Code de lire la variable depuis l’environnement système. Ça évite de coller ton token directement dans le fichier JSON.

Ce que le serveur MCP GitHub expose comme outils : search_repositories, get_file_contents, create_issue, create_pull_request, list_commits, get_issue, add_comment. Claude Code appelle ces outils automatiquement selon le contexte. Si tu lui demandes de créer une issue pour un bug qu’il vient de détecter dans ton code, il appelle create_issue sans que tu aies à le préciser. Un exemple d’instruction qui utilise les deux serveurs en combinaison : "Lis le fichier README.md dans le dépôt monorg/mon-projet sur GitHub, compare-le avec le README local dans /Users/toi/projets/mon-projet, et crée une issue GitHub pour chaque section qui est désynchronisée." Claude Code orchestre les appels à get_file_contents (GitHub), read_file (Filesystem) et create_issue (GitHub) dans le bon ordre.

Le débogage MCP a ses patterns classiques. Avant de passer à la construction d’un workflow complet, il faut savoir diagnostiquer rapidement. L’erreur la plus fréquente est une syntaxe JSON invalide. JSON est brutal avec ça : une virgule de trop après le dernier élément d’un objet, et le fichier entier est refusé. Utilise node -e "JSON.parse(require('fs').readFileSync('~/Library/Application\\ Support/Claude/claude_desktop_config.json', 'utf8'))" pour valider la syntaxe avant de redémarrer. La deuxième erreur courante : un chemin dans args qui n’existe pas. Le serveur Filesystem refuse de démarrer si le répertoire que tu lui passes n’existe pas sur le disque. Vérifie avec ls /ton/chemin dans le terminal. Claude Code expose les logs des serveurs MCP. Sur macOS, cherche dans ~/Library/Logs/Claude/. Sur Linux et Windows, consulte la documentation CLI pour l’emplacement exact. Ces logs montrent exactement pourquoi un serveur refuse de démarrer : chemin manquant, permission refusée, package npm introuvable.

Si npx échoue à télécharger le package du serveur, c’est souvent un problème de réseau ou de cache npm. Lance npx --yes @modelcontextprotocol/server-filesystem /tmp directement dans le terminal pour tester hors du contexte de Claude Code. Si ça marche en standalone mais pas dans l’app, le problème vient du chemin vers l’exécutable npx que Claude Code utilise (qui peut différer de celui de ton shell). Pour forcer le chemin absolu vers npx dans ta config :

{
"command": "/usr/local/bin/npx"
}

Trouve le chemin exact avec which npx dans ton terminal.

C’est là que ça devient intéressant. Avec Filesystem et GitHub branchés ensemble, Claude Code peut prendre une instruction de haut niveau et orchestrer tout le workflow de développement sans que tu aies à changer de contexte. Voici un workflow concret que MCP rend possible depuis une seule session Claude Code : Première phase : analyse du projet existant. Tu demandes à Claude Code d’explorer la structure d’un projet local, de lire les fichiers de configuration, de comprendre l’architecture en place. Sans MCP, tu copies-colles les fichiers pertinents. Avec le serveur Filesystem, Claude Code navigue lui-même dans la structure, lit ce dont il a besoin, et construit sa compréhension du projet. Deuxième phase : consultation du dépôt distant. Claude Code peut lire les issues ouvertes sur GitHub pour comprendre quels bugs sont connus ou quelles features sont demandées. Il peut lire les pull requests en cours pour éviter les conflits. Il construit une vue complète de l’état du projet, local et distant.

Troisième phase : génération et écriture de code. Claude Code génère les modifications nécessaires et les écrit directement dans les fichiers via le serveur Filesystem. Tu n’as pas à copier le code généré et le coller dans ton éditeur : le fichier est modifié sur le disque. Quatrième phase : documentation et suivi. Claude Code crée une issue GitHub pour documenter les changements effectués, ou ajoute un commentaire sur une issue existante pour signaler la progression. Tout ça depuis la même session, sans quitter le contexte.

Tu as accès au filesystem local dans /Users/toi/projets/mon-app
et au dépôt GitHub monorg/mon-app via MCP.
Fais les choses suivantes dans l'ordre :
1. Lis la structure du projet local et identifie les dépendances principales
2. Consulte les issues ouvertes sur GitHub pour trouver les bugs marqués "high priority"
3. Pour le bug le plus critique, propose et implémente un correctif dans le fichier concerné
4. Mets à jour le fichier CHANGELOG.md local avec la description du correctif
5. Crée un commentaire sur l'issue GitHub pour signaler que le correctif est implémenté localement

Claude Code va orchestrer les appels MCP dans l’ordre logique : list_directory et read_file pour explorer le projet, list_issues et get_issue pour consulter GitHub, write_file pour le correctif et le changelog, add_comment pour clore la boucle sur GitHub. Le truc critique à comprendre sur l’orchestration : Claude Code décide lui-même de l’ordre des appels et gère les dépendances entre eux. Si lire le fichier de config local est nécessaire avant de comprendre quelle issue GitHub est pertinente, il le fait dans le bon ordre sans que tu aies à le spécifier.

Quelques trucs bons à savoir

MCP et les permissions filesystem sont permanentes jusqu’à ce que tu les changes. Si tu ajoutes un répertoire dans la config, Claude Code peut y lire et écrire tant que la config n’est pas modifiée. Pense à restreindre les chemins aux projets actifs sur lesquels tu travailles, pas à ton répertoire home entier. Chaque serveur MCP est un processus distinct. Si tu as trois serveurs configurés, tu as trois processus qui tournent en arrière-plan pendant que Claude Code est actif. Sur une machine avec peu de RAM, ça se sent. Désactive les serveurs que tu n’utilises pas en les commentant dans le JSON (avec des guillemets autour de la clé, puisque JSON ne supporte pas les vrais commentaires). Le serveur MCP GitHub respecte tes permissions de token. Si ton token n’a pas le scope write:org, Claude Code ne pourra pas créer des issues dans les dépôts d’organisation, même si tu lui demandes. Les erreurs MCP en provenance de GitHub sont souvent des erreurs 403 liées aux scopes du token. Les instructions en langage naturel suffisent pour déclencher les outils MCP. Tu n’as pas besoin de spécifier quel outil appeler. Dire "Lis le fichier package.json" suffit pour que Claude Code appelle read_file via le serveur Filesystem. C’est le protocole MCP qui fait la correspondance entre l’intention et l’outil. MCP supporte aussi des serveurs custom. Si tes outils internes ont une API, tu peux écrire un serveur MCP custom en Node.js ou Python qui expose ces outils à Claude Code. Le SDK MCP officiel d’Anthropic est disponible sur npm et PyPI. Le principe est le même : tu définis des outils, tu les exposes via le protocole, et tu configures le serveur dans ton JSON. La latence des appels MCP dépend du serveur. Le serveur Filesystem est ultra-rapide (lecture locale). Le serveur GitHub dépend de la latence réseau vers l’API GitHub. Sur un projet qui nécessite beaucoup d’appels GitHub en séquence, c’est perceptible. Structure tes instructions pour regrouper les appels distants quand c’est possible. Il n’y a pas de mémoire entre les sessions. Chaque nouvelle session Claude Code repart de zéro. Les serveurs MCP sont reconnectés au démarrage, mais l’agent ne se souvient pas des fichiers qu’il a lus dans une session précédente. Si tu travailles sur un projet complexe, donne le contexte de départ dans tes premières instructions.

Le hic

Soyons clairs sur ce qui accroche avec MCP dans l’état actuel. La configuration initiale est fragile. Un chemin mal formaté, une virgule de trop dans le JSON, et rien ne marche. Le debugging n’est pas terrible : les messages d’erreur de Claude Code sont parfois vagues, et tu dois aller chercher les logs manuellement. Pour quelqu’un qui n’est pas habitué à travailler avec des configs JSON et des processus en arrière-plan, la courbe d’entrée est raide. npx télécharge les serveurs à la volée. La première fois que tu démarres avec un nouveau serveur MCP, npx va chercher le package sur npm. Si tu es hors ligne ou si npm est lent, le serveur ne démarre pas. Et si Anthropic ou le mainteneur du package sort une mise à jour qui casse quelque chose, tu le découvres au prochain démarrage. L’installation locale avec npm install -g est plus stable mais ajoute une étape de maintenance. Les permissions filesystem sont binaires. Soit Claude Code peut lire et écrire dans un répertoire, soit il ne peut pas. Il n’y a pas de configuration plus granulaire genre lecture seulement pour /projets/archives, lecture-écriture pour /projets/actif. Si tu veux ce niveau de contrôle, tu dois configurer plusieurs instances du serveur Filesystem avec des chemins différents, ou écrire un serveur custom. L’orchestration peut partir dans une mauvaise direction. Claude Code décide lui-même de l’ordre des appels MCP. Sur des instructions complexes, il peut faire des appels dans un ordre sous-optimal ou même inutile. Dans ma pratique, des instructions plus précises et séquentielles ("Fais d'abord X, puis Y, puis Z") donnent des résultats plus fiables que des instructions ouvertes ("Gère tout le workflow"). Le serveur GitHub a une limite de taux. L’API GitHub impose des limites sur le nombre de requêtes par heure. Sur un workflow qui fait beaucoup d’appels GitHub en séquence (lire des dizaines d’issues, comparer plusieurs fichiers dans plusieurs dépôts), tu peux frapper cette limite. Consulte la documentation de l’API GitHub pour les limites exactes selon ton type de token. La surface de sécurité augmente. Tu donnes à un agent IA la capacité de modifier des fichiers sur ton disque et d’interagir avec ton compte GitHub. C’est puissant et c’est aussi un risque si tu n’es pas attentif aux instructions que tu donnes. Claude Code est prudent par défaut et te demande confirmation avant des actions destructives, mais ça reste ta responsabilité de vérifier ce qu’il fait.

Check-list finale

Verdict + prochaines étapes

MCP avec Claude Code, c’est la différence entre un assistant qui répond à des questions et un agent qui travaille dans ton environnement réel. Si tu construis des projets en équipe sur GitHub ou si tu travailles régulièrement sur des codebases existantes, le setup en vaut la peine. La configuration initiale demande une heure de patience, et c’est du temps récupéré à chaque session ensuite. La prochaine étape logique après Filesystem et GitHub : explorer les serveurs MCP de la communauté (il en existe pour PostgreSQL, Slack, Notion, et une trentaine d’autres outils) ou écrire ton propre serveur pour brancher tes outils internes. Le SDK MCP d’Anthropic est bien documenté et le modèle de base d’un serveur custom tient en quelques dizaines de lignes de code.

Texte par David Cyr

David Cyr

L'Opérateur AI · Fondateur Taverne AI

Opérateur québécois. J'ai construit LeadLoup, un mandat acheteur véhicules pour Complexe Kia, et plusieurs systèmes IA en production. À la Taverne, je teste des outils qu'on me paie pour utiliser, et je dis si c'est utile ou si c'est de la marde.

À propos·Méthodologie