Claude Code MCP : modèle de permissions et bonnes pratiques — GitHub / CodeGraph / API avec exposition minimale

Prérequis : triple connexion MCP (connecter d'abord, sécuriser ensuite). Le tutoriel d'installation arrive dans un article dédié. Réponses rapides via « Questions fréquentes » ; norme complète ci-dessous — ce document est la spécification autoritaire des permissions (v1.0), pas un guide de connectivité.

Parcours de lecture (~15 min · norme) : questions → synthèse → modèle système → frontière et flux → matrice et contrôle → extraits de config → chaîne d'attaque. Citable en procédure ou annexe de revue sécurité.

Positionnement : norme autoritaire (actionnable et auditable)

Le encadré « Questions » relie l'intention de recherche aux sections ; ici commence le texte normatif sécurité. La connectivité vérifie l'enregistrement des outils (mcp__github__*) ; les permissions vérifient la portée de chaque appel : chemins, API, ressources GitHub, scopes des secrets.

Quand Claude Code, CodeGraph et le GitHub Runner partagent la même machine, comptes séparés pour jetons MCP et secrets Runner — pas de clé GitHub App commune, pas de DATABASE_URL prod dans l'espace agent (Mac distant : Cloud Mac vs Mac local).

Niveau 1 · Modèle système (avant la matrice)

Le MCP triple répartit trois rôles — chacun avec sa frontière lecture/écriture, pas trois « plugins branchés » (architecture : vue d'ensemble) :

Session Claude Code
    │
    ├─ GitHub MCP     →  Intent   (besoin : issue / PR / commentaire)
    ├─ CodeGraph MCP  →  Context  (où : impact / symboles / dépendances)
    └─ API MCP        →  Truth    (vérité : données staging / contrats)

Axe risque : écriture intent → collaboration ; context → index/sources ;
             truth → mélange staging / production.

Déploiement : CodeGraph en 5 minutes = graphe disponible ; cet article = graphe et API en RO devant l'agent. Série : architecture, threat model prévu (STRIDE · surface · flux de credentials).

Frontière de confiance

Pour les revues d'architecture : la session agent est en zone A ; MCP est la seule porte vers l'extérieur. Tout accès production, FS inscriptible ou credentials CI = violation de frontière.

┌─────────────────────────────────────────────────────────┐
│  Zone A · session Claude Code (utilisateur / agent)      │
│                                                         │
│   ┌──────────────── couche MCP ────────────────┐        │
│   │  GitHub MCP (intent)  ──► collaboration     │        │
│   │  CodeGraph MCP (ctx)   ──► index / graphe   │        │
│   │  API MCP (truth)       ──► BDD staging      │        │
│   └────────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
   [ API GitHub ]      [ .codegraph/ ]      [ API staging ]
   externe             local · RO défaut     hors production

Frontière (ne pas franchir par défaut) :
  ✗ BDD / URL API production
  ✗ FS inscriptible (monorepo entier)
  ✗ credentials CI/Runner
  ✗ .env.production · secrets projets voisins

Les lignes « production = interdit » et « CI/Runner ≠ MCP » de la matrice opérationnalisent cette frontière.

Flux de données

Les permissions, c'est le flux et les effets de bord entre agent, MCP et système cible. La frontière : « a-t-il le droit ? » ; le flux : « que se passe-t-il ensuite ? »

Prompt utilisateur
   ↓
Claude Code (état agent · contexte dialogue)
   ↓
Appel outil MCP (GitHub / CodeGraph / API)
   ↓
Réponse (issue · JSON graphe · lignes staging)
   ↓
Interprétation agent (plan · description PR · paramètres suivants)
   ↓
Effet de bord (commentaire · INSERT · .codegraph/ · déclenchement CI)

Points de contrôle (matrice) :
  · avant MCP → service RO / scope minimal
  · avant réinjection → masquage PII · pas de champs prod
  · avant effet de bord → sans MCP d'écriture, la chaîne doit échouer

§ Chaîne de mauvaise config détaille les mêmes étapes avec des erreurs concrètes.

Accidents de permissions (comportement agent)

Même avec une config « raisonnable » — points de contrôle revue code / sécurité :

• GitHub MCP écrit commentaires/labels → bot CI ou auto-merge sans validation humaine.
• CodeGraph ou FS MCP en écriture → l'agent altère .codegraph/ ou la config voisine ; codegraph_impact devient peu fiable.
• API MCP écrit en staging → données de test confondues avec des mocks prod ; mauvais schéma recopié dans le PR.
• FS MCP lit la racine du workspace → .env.production ou secrets du monorepo dans le fil ou une issue.

Niveau 2 · Principes par défaut

1. Session Claude : MCP lecture seule (*-ro) ; écriture = jeton éphémère + second service MCP.
2. Pas de CI/Runner via MCP ; rebuild d'index et tests DB en workflow, pas en chat.
3. Production invisible pour l'agent : pas d'URL prod, pas de DATABASE_URL, pas de PAT merge/push permanent dans ~/.claude.json.

Matrice de stratégie (lignes par défaut recommandées)

Tableau auditable : ressource, politique, colonnes session Claude · CI/Runner · production. Toute écriture : justification et date d'expiration dans le PR.

Plan de contrôle (qui applique quoi)

La matrice dit « il faut » ; ici « qui impose, où » :

Application :

  1. Config MCP (~/.claude.json · scopes statiques · RO par défaut)
  2. OS / FS (montage RO repo & .codegraph/ · isolation workspace)
  3. Console GitHub App / PAT (fin · un repo · jetons d'écriture expirants)
  4. CI (garde URL prod · scan secrets · pas de PAT dans le repo)
  5. Coffre Runner (env CI séparé de MCP · pas dans mcpServers)

Colonnes matrice :
  · Claude  → ①②
  · CI      → ④⑤
  · Prod    → ③④

Checklist imprimable et page pannes : § Suite.

GitHub MCP · PAT et scopes

Objectif : lire les issues et citer, sans confier en permanence « merger la PR » à l'agent du dialogue.

Paliers recommandés

• Quotidien (RO) : repo (lecture privée), read:org si besoin ; flux issues + issues.
• Écriture automatisée (éphémère) : PAT fin, un dépôt, Contents/Issues en écriture, 7–30 jours, puis retrait de mcpServers.

Stockage : variable d'environnement (GITHUB_MCP_TOKEN), pas dans le dépôt ; Cloud Mac = secret d'instance, local = Keychain / 1Password.

# Exemple : logique de scopes — l'UI GitHub fait foi
# Fin · un repo · Contents RO + Issues RW

CodeGraph · index en lecture seule

1. Après codegraph init : traiter .codegraph/ comme artefact de build.
2. Processus MCP RO sur les sources ; rebuild via CI ou manuel, pas via le chat.
3. codegraph_impact vide : vérifier index et CWD avant d'ouvrir l'écriture.

Gros dépôts : CodeGraph et agent de code IA — politique RO inchangée.

API MCP · staging en lecture seule

• Seule l'URL de base staging dans mcpServers.
• Compte BDD SELECT uniquement ; écriture via api-staging-rw, désactivé par défaut dans Claude.
• PII masquées ; pas de JSON brut dans les commentaires d'issue.

~/.claude.json · exemple minimal

Les noms de champs peuvent varier — l'essentiel : services séparés, variables séparées, ensemble actif minimal.

{
  "mcpServers": {
    "github-readonly": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_MCP_TOKEN_READONLY}"
      }
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"],
      "env": {
        "CODEGRAPH_READ_ONLY": "1"
      }
    }
  }
}

CODEGRAPH_READ_ONLY est illustratif — sinon montage RO au niveau OS.

Checklist avant mise en prod (abrégée)

• □ PAT GitHub aux scopes minimaux, absent du git ?
• □ API MCP d'écriture sur prod — si oui, désactivée par défaut ?
• □ CodeGraph limité à impact/query ?
• □ Cloud Mac : CWD = un seul dépôt ?
• □ Jeton Runner séparé du jeton MCP ?
• □ L'équipe connaît la doc de référence ? (cet article + vue d'ensemble)

Chaîne de mauvaise configuration

Combinaison « pour aller plus vite » qui dérape via l'agent :

1. Point de départ (plausible)

• Un profil mcpServers : GitHub (repo write) + FS + CodeGraph.
• CodeGraph inscriptible à la racine monorepo ; API staging avec INSERT.
• Workspace = racine repo, .env* non exclus.

2. Déclencheur

Consigne : « corriger le bug de l'issue #42 et mettre à jour les étapes de repro dans la PR » — lecture GitHub → impact → requête staging → écriture FS.

3. Escalade

1. FS modifie un sous-projet voisin.
2. CodeGraph réécrit .codegraph/.
3. INSERT API avec noms de champs type prod dans le texte PR.
4. Commentaire GitHub déclenche le CI par label.

4. Impact

• Mauvaise config dans le PR ; staging pollué ; index incohérent.
• Fragment de DATABASE_URL dans la PR → alerte scan (fuite).

5. Remédiation

1. Révoquer le PAT → RO fin, jeton d'écriture 7–30 jours à part.
2. CodeGraph en montage RO ; rebuild via Runner la nuit.
3. Séparer api-ro / api-rw ; Claude = RO seulement.
4. Scan CI ; pas de clé App partagée avec MCP.

Suite de la série

Cet article = page 1 · norme. Guide court et pannes en pages dédiées :

Évolution : policy as code

La matrice peut devenir allowlist JSON, DSL MCP ou garde-fous CI (pas d'URL prod / pas de PAT complet dans le repo) — après le threat model (③), séparé de cette norme.

FAQ

CodeGraph en lecture seule ?
Oui, recommandé. Index via CI ou manuel ; le dialogue ne fait que des requêtes.

GitHub MCP en écriture ?
Commentaires/labels possibles ; merge/push en jeton court avec validation — pas 24/7 dans Claude.

Partager les secrets Runner ?
Non. MCP = agent interactif ; Runner = CI — logiques de fuite et rotation différentes.

MCP inactif après installation ?
Connectivité : carte des problèmes ; page pannes L4-Q07 prévue.

Métadonnées · série

Version : sécurité permissions agent IA v1.0 (stable). Série : Cloud Mac AI Stack · norme L4 — modèle MCP et contrôle des menaces.