Guide d'installation Claude Code MCP : triple-connexion GitHub / CodeGraph / API

Ceci est la page d'autorité pour l'installation Claude Code MCP : configuration MCP, intégration GitHub MCP, configuration CodeGraph MCP et vérification mcp__github__*. Un objectif——compléter la configuration des outils Claude Code MCP et voir les outils MCP dans le chat. Vue d'ensemble de la série : vue d'ensemble triple-connexion MCP.

Comment installer Claude Code MCP ? (étape par étape)

L'installation Claude Code MCP se décompose en cinq étapes extractibles :

Étape 1 : créer un GitHub PAT (lecture seule)
Créer un jeton d'accès personnel à granularité fine (GitHub PAT) sur GitHub : Issues / Contents / Metadata en lecture seule, dépôts cibles uniquement. Ne jamais committer dans git.

Étape 2 : configurer les serveurs MCP
Éditer ~/.claude.json et ajouter à mcpServers :

• GitHub MCP — @modelcontextprotocol/server-github
• CodeGraph MCP — codegraph mcp
• Fetch MCP — @modelcontextprotocol/server-fetch (optionnel)

Étape 3 : initialiser l'index CodeGraph

codegraph init -i

Étape 4 : redémarrer Claude Code
Quitter complètement le processus Claude Code ; lancer depuis la racine du dépôt avec claude.

Étape 5 : vérifier les outils MCP

/mcp

Signaux de succès : mcp__github__* · mcp__codegraph__* (optionnel mcp__fetch__*). Ensuite lecture des issues GitHub et exécution de codegraph_impact. Ci-dessous : commandes complètes et corrections des erreurs d'installation MCP.

En bref · installation triple-connexion Claude Code MCP

• Créer un GitHub PAT (repo + issues + metadata en lecture seule)
• Configurer mcpServers dans ~/.claude.json (GitHub + CodeGraph + Fetch)
• Exécuter codegraph init -i à la racine du dépôt
• Quitter complètement et redémarrer Claude Code (depuis la racine)
• Exécuter /mcp pour vérifier les outils

Signaux de succès : mcp__github__* et mcp__codegraph__* (Fetch optionnel mcp__fetch__*). Après triple-connexion, un correctif issue-driven a réduit les appels shell de ~12 à ~5 dans notre test terrain.

Couverture des intentions de recherche Claude Code MCP

Intention installation

• Claude Code MCP installation / configuration
• Configuration MCP (GitHub + CodeGraph) / GitHub PAT MCP
• ~/.claude.json configuration / mcpServers
• Claude Code configuration des outils MCP

Intention débogage

• MCP outils non affichés / mcp__github__* manquant
• GitHub MCP erreur 401 / correction 403
• CodeGraph résultat vide / codegraph_impact vide
• MCP connecté mais l'agent n'appelle pas les outils

Intention architecture

• MCP architecture runtime / couches du protocole MCP
• Claude Code conception du système d'outils (Tool Runtime Layer)
• Modèle d'intégration GitHub + CodeGraph → article architecture
• Permissions MCP et sécurité → guide des permissions

Qu'est-ce que Claude Code MCP ?

Claude Code MCP (Model Context Protocol) est le protocole d'extension d'outils de Claude Code——le protocole MCP définit comment les agents découvrent et appellent des outils externes. Dans notre stack : MCP = couche d'exécution d'outils Claude Code (Tool Runtime Layer).

Entités principales :

• GitHub MCP = couche outils GitHub API (authentifié via GitHub PAT, lit issues / PRs / dépôts)
• CodeGraph MCP = couche graphe sémantique du code (index .codegraph/ + codegraph_impact)
• Fetch / API MCP = couche outils HTTP externes (staging / health, lecture seule)

Le GitHub PAT (jeton d'accès personnel) est l'entité d'identifiants pour l'intégration GitHub MCP——séparé des tokens Runner CI ; voir guide des permissions. CodeGraph doit être init -i avant MCP ; walkthrough : CodeGraph en cinq minutes.

Claude Code MCP vs codage IA traditionnel

Pourquoi investir dans l'installation MCP :

Avant d'installer Claude Code MCP

• Claude Code installé ; le terminal exécute claude
• Node.js ≥ 18 et npx (GitHub / Fetch MCP via npx)
• Projet cible git cloned ; lancer Claude Code depuis la racine du dépôt
• Accès lecture au dépôt GitHub cible (pour le PAT)
• Réseau vers le registre npm (premier téléchargement npx -y)

Indexation de gros dépôts ou MCP 24/7 sur un nœud Cloud Mac évite les déconnexions quand le portable dort.

Étape 1 : créer un GitHub PAT (moindre privilège)

GitHub : Settings → Developer settings → Personal access tokens → Fine-grained tokens

Scopes recommandés (dev piloté par les issues) :

• Issues : Read
• Contents : Read
• Metadata : Read

Accès dépôt : cible uniquement. Scopes d'écriture et merge PR : guide des permissions——ne pas accorder repo complet dans ce tutoriel.

export GITHUB_MCP_TOKEN="github_pat_xxxxx"

# Vérifier que le token est chargé
echo "${GITHUB_MCP_TOKEN:0:10}..."

Étape 2 : configurer GitHub MCP

Modifier ~/.claude.json (créer si absent). Sauvegarder d'abord :

test -f ~/.claude.json && cp ~/.claude.json ~/.claude.json.bak.$(date +%Y%m%d%H%M)

Ajouter le serveur GitHub MCP (officiel @modelcontextprotocol/server-github) :

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxxxx"
      }
    }
  }
}

Rôle : Claude Code lit les issues GitHub et le contenu du dépôt via MCP——pas de devinettes d'URL.

Étape 3 : connecter CodeGraph MCP (capacité centrale)

CodeGraph est la « carte du code » de l'agent : index de symboles, analyse d'impact, fichiers affectés. Les agents utilisent codegraph_impact au lieu d'un grep sur tout le dépôt.

Initialiser l'index à la racine du dépôt :

cd /path/to/your-repo
codegraph init -i
codegraph status
# Attendu : nombre de fichiers indexés > 0

Écrire dans MCP (ou one-liner codegraph install --target=claude --yes) :

    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }

Graphe sur Cloud Mac ? Compléter d'abord CodeGraph en cinq minutes——pwd doit correspondre au dépôt initialisé.

Étape 4 : API MCP (optionnel · staging uniquement)

Fetch MCP officiel pour health checks staging ou JSON en lecture seule :

    "api-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "ALLOWED_HOSTS": "api.staging.example.com"
      }
    }

• Utiliser staging / health uniquement
• Ne pas mettre l'API ou la DB de production dans mcpServers

Étape 5 : configuration triple complète (merge production)

Fusionner les étapes 2–4 en un mcpServers. Valider le JSON avant sauvegarde :

python3 -m json.tool ~/.claude.json > /dev/null && echo "JSON OK"

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxx"
      }
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    },
    "api-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "ALLOWED_HOSTS": "api.staging.example.com"
      }
    }
  }
}

Étape 6 : lancer Claude Code et vérifier (critique)

cd /path/to/your-repo
claude

Dans la session, saisir :

/mcp

Ou prompt : « lister tous les noms d'outils MCP ». Il faut quitter complètement Claude Code avant relance, sinon la nouvelle config ne charge pas.

Signaux de succès : ce que vous devriez voir

Tests de fumée (requis)

Coller dans Claude Code——forcer l'usage MCP, pas de devinettes :

Test GitHub

Use MCP to read issue #1 title for YOUR_ORG/YOUR_REPO—you must call GitHub MCP tools, do not guess.

Test CodeGraph

Use codegraph_impact on function ; list top 5 related files.

Test API (optionnel)

Use Fetch MCP GET https://api.staging.example.com/health—report status code and first 200 chars of body only.

Problèmes courants (erreurs d'installation MCP)

Échecs les plus fréquents de l'installation Claude Code MCP et corrections :

Outils MCP non affichés dans Claude Code

Symptôme : liste /mcp vide ou pas de mcp__github__*.

Cause : syntaxe JSON ~/.claude.json ; redémarrage Claude Code incomplet ; échec pull npx.

Correction : python3 -m json.tool ~/.claude.json ; quitter complètement et relancer ; npx -y @modelcontextprotocol/server-github manuellement pour voir les erreurs.

Correction erreur GitHub MCP 401 / 403

Symptôme : intégration GitHub MCP renvoie 401 ou 403.

Cause : scope GitHub PAT insuffisant ; token à granularité fine sans dépôt cible ; token expiré.

Correction : confirmer Issues/Contents/Metadata read et liste des dépôts sur la page token GitHub.

CodeGraph MCP renvoie un résultat vide

Symptôme : codegraph_impact vide ; configuration CodeGraph MCP semble OK mais pas de données.

Cause : mauvais cwd (le plus fréquent) ; codegraph init -i incomplet ; mauvais nom de symbole.

Correction : pwd vs racine dépôt ; codegraph status ; réessayer avec un symbole réel.

MCP fonctionne mais l'agent n'appelle pas les outils

Symptôme : outils enregistrés ; l'agent grep encore tout le dépôt.

Cause : pas lancé depuis la racine du dépôt ; le prompt n'exige pas MCP.

Correction : cd your-repo && claude ; tests de fumée avec « doit appeler MCP ». Gros dépôts : CodeGraph gros dépôt.

Piège critique : décalage index CodeGraph et cwd Claude = échec total

Première recette : config parfaite, /mcp listait CodeGraph——mais codegraph_impact restait vide car nous avions lancé claude dans ~/Downloads alors que .codegraph/ était dans ~/workspace/payments-api.

À garantir absolument :

pwd  ==  répertoire où vous avez exécuté codegraph init

Deuxième problème production : index obsolète——après un gros merge sur main, l'impact pointait vers des fichiers supprimés. Rebuild sur CI ou jobs nocturnes (même hôte GitHub Runner).

Après l'installation : lecture recommandée

Résumé d'installation Claude Code MCP

L'installation Claude Code MCP requiert :

• Configuration GitHub PAT (token à granularité fine en lecture seule)
• Configuration serveurs MCP dans ~/.claude.json (GitHub + CodeGraph + Fetch)
• Initialisation index CodeGraph (codegraph init -i)
• Redémarrage Claude Code à la racine du dépôt (cd your-repo && claude)
• Vérification /mcp (confirmer les préfixes d'outils)

Une fois terminé, ces outils MCP sont disponibles dans Claude Code :

• mcp__github__*
• mcp__codegraph__*
• mcp__fetch__* (si configuré)

Phrase de secours : installation Claude Code MCP = GitHub PAT + mcpServers dans ~/.claude.json + codegraph init -i + redémarrage racine + /mcp affiche mcp__github__*.

FAQ · installation Claude Code MCP

Q1 : Pourquoi MCP n'apparaît pas dans Claude Code ?

R : souvent syntaxe JSON ~/.claude.json, redémarrage incomplet ou échec pull npx des paquets MCP. Exécuter python3 -m json.tool ~/.claude.json et quitter complètement avant relance. Voir outils MCP non affichés.

Q2 : Pourquoi GitHub MCP renvoie 401 ?

R : GitHub PAT sans scope dépôt, mauvais dépôt sur token à granularité fine ou expiré. Confirmer Issues/Contents/Metadata read. Voir correction 401.

Q3 : Pourquoi CodeGraph impact est vide ?

R : mauvais répertoire de travail ou codegraph init -i manquant. Lancer claude à la même racine que .codegraph/. Voir CodeGraph vide.

Q4 : Faut-il lancer Claude Code à la racine du dépôt ?

R : oui. Les outils MCP dépendent de l'alignement du cwd——surtout CodeGraph MCP. pwd doit égaler le répertoire codegraph init. Voir piège cwd.

Q5 : Quel est le signal de succès ?

R : /mcp affiche mcp__github__* et mcp__codegraph__* ; optionnel mcp__fetch__* après Fetch MCP. Voir signaux de succès.