Claude Code MCP: Berechtigungsmodell & Best Practices — GitHub / CodeGraph / API mit minimaler Exposition

Voraussetzung: MCP-Dreifachverbindung (erst verbinden, dann absichern). Installationsdetails folgen in einer separaten Anleitung. Kurzantworten über die Box „Typische Fragen“; vollständige Norm im Rest — dieses Dokument ist die autoritative Berechtigungsspezifikation (v1.0), kein Connectivity-Tutorial.

Lesepfad (ca. 15 Min. · Normtext): Typische Fragen → Kernaussage → Systemmodell → Vertrauensgrenze & Datenfluss → Matrix & Kontrollebene → Konfigurationsfragmente → Angriffskette. Als SOP oder Anhang im Security Review zitierbar.

Einordnung: autoritative Norm (lösbar + auditierbar)

Die Box „Typische Fragen“ verknüpft Suchintention mit Kapiteln; ab hier folgt der Sicherheitsarchitektur-Normtext. Connectivity prüft Tool-Registrierung (mcp__github__*); Berechtigungen prüfen die Reichweite pro Aufruf: Pfade, APIs, GitHub-Ressourcen, Secret-Scopes.

Laufen Claude Code, CodeGraph und der GitHub Runner auf demselben Host, gelten getrennte Konten für MCP-Token und Runner-Geheimnisse — kein gemeinsamer GitHub-App-Key, kein Produktions-DATABASE_URL im Agent-Workspace (Remote-Mac: Cloud Mac vs. lokaler Mac).

Ebene 1 · Systemmodell (vor der Matrix)

Die Dreifach-MCP teilt Verantwortung in drei Klassen — jeweils mit eigener Read/Write-Grenze, nicht als „einfach angeschlossene Plugins“ (Architektur: MCP-Überblick):

Claude-Code-Sitzung
    │
    ├─ GitHub MCP     →  Intent   (Bedarf: Issue / PR / Kommentar)
    ├─ CodeGraph MCP  →  Context  (Ort: impact / Symbole / Abhängigkeiten)
    └─ API MCP        →  Truth    (Validierung: Staging-Daten / Verträge)

Risikoachse: Intent-Schreiben trifft Kollaboration; Context-Schreiben index/Quellcode;
             Truth-Schreiben vermischt Staging und Produktion.

Deployment: CodeGraph in fünf Minuten = Graph verfügbar; dieser Artikel = Graph und API vor dem Agent standardmäßig read-only. Serie: Architektur, geplant Threat Model (STRIDE · Angriffsfläche · Credential Flow).

Vertrauensgrenze

Für Architektur-Reviews: Die Agent-Sitzung liegt in Zone A; MCP ist das einzige Tor nach außen. Jeder Zugriff auf Produktion, beschreibbares Dateisystem oder CI-Credentials gilt als Grenzverletzung.

┌─────────────────────────────────────────────────────────┐
│  Zone A · Claude-Code-Sitzung (Nutzer / Agent)           │
│                                                         │
│   ┌──────────────── MCP-Schicht ────────────────┐       │
│   │  GitHub MCP (Intent)  ──► Kollaboration      │       │
│   │  CodeGraph MCP (Ctx)  ──► Index / Graph lokal│       │
│   │  API MCP (Truth)      ──► Staging-DB         │       │
│   └─────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
   [ GitHub API ]      [ .codegraph/ ]      [ Staging-API ]
   extern · Kollab.    lokal · RO default   nicht Produktion

Vertrauensgrenze (nicht per Default überschreiten):
  ✗ Produktions-DB / Produktions-API-URL
  ✗ beschreibbares FS (Gesamt-Monorepo)
  ✗ CI/Runner-Credentials (GITHUB_TOKEN · App-Key)
  ✗ .env.production · Secrets benachbarter Projekte

Matrix-Zeilen „Produktion = verboten“ und „CI/Runner ≠ MCP“ operationalisieren diese Grenze.

Datenfluss

Berechtigungsfragen sind Fluss und Nebenwirkungen zwischen Agent, MCP und Zielsystem. Die Grenze beantwortet „darf er?“; der Fluss „was passiert danach?“.

Nutzer-Prompt
   ↓
Claude Code (Agent-State · Dialogkontext)
   ↓
MCP-Toolaufruf (GitHub / CodeGraph / API)
   ↓
Antwort (Issue-Text · Graph-JSON · Staging-Zeilen)
   ↓
Agent-Interpretation (Plan · PR-Beschreibung · nächste Parameter)
   ↓
Nebenwirkung (Kommentar · INSERT · .codegraph/ · CI-Start)

Kontrollpunkte (Matrix):
  · vor MCP → RO-Dienst / minimaler Scope
  · vor Rückführung → PII-Redaktion · keine Produktionsfelder
  · vor Nebenwirkung → ohne Schreib-MCP soll die Kette abbrechen

§ Fehlkonfiguration zeigt dieselbe Kette mit konkreten Fehltrittstellen.

Typische Berechtigungsunfälle (Agent-Fehlverhalten)

Auch bei „plausibler“ Konfiguration — Prüfpunkte für Code- und Security-Review:

• GitHub MCP schreibt Kommentare/Labels → CI-Bot oder Auto-Merge ohne menschliche Freigabe.
• CodeGraph oder FS-MCP mit Schreibzugriff → Agent verändert .codegraph/ oder Nachbar-Config; codegraph_impact unzuverlässig.
• API-MCP schreibt ins Staging → Testdaten vermischen sich mit Produktions-Mocks; falscher Schema-Kontext landet im PR.
• FS-MCP liest Workspace-Root → .env.production oder Monorepo-Secrets im Dialog oder Issue.

Ebene 2 · Default-Prinzipien

1. Nur read-only MCP in der Claude-Sitzung (*-ro); Schreiben = kurzlebiges Token + zweiter MCP-Dienst.
2. CI/Runner nicht über MCP; Index-Rebuild und DB-Schreibtests laufen in Workflows, nicht im Chat.
3. Produktion für den Agent unsichtbar: keine Prod-URL, kein DATABASE_URL, kein dauerhaftes merge/push-PAT in ~/.claude.json.

Strategiematrix (empfohlene Default-Zeilen)

Auditierbar: Ressource, Default, Spalten Claude-Sitzung · CI/Runner · Produktion. Schreibbedarf im PR mit Begründung und Ablaufdatum dokumentieren.

Kontrollebene (wer setzt durch?)

Die Matrix sagt „soll“; hier „wer erzwingt wann“:

Durchsetzung:

  1. MCP-Konfig (~/.claude.json · statische Scopes · RO default)
  2. OS / FS (Repo & .codegraph/ RO-Mount · Workspace-Isolation)
  3. GitHub App / PAT-Konsole (fein · ein Repo · ablaufende Schreib-Tokens)
  4. CI (Prod-URL-Gate · Secret-Scan · kein PAT im Repo)
  5. Runner-Vault (CI-Env getrennt von MCP · nicht in mcpServers)

Matrix-Spalten:
  · Claude  → ①②
  · CI      → ④⑤
  · Prod    → ③④

Druckbare Checkliste und Störungsseite siehe § Weiterlesen.

GitHub MCP · PAT & Scopes

Ziel: Issues lesen und zitieren, ohne dauerhaft „PR mergen“ dem Dialog-Agent zu geben.

Empfohlene Stufen

• Tagesgeschäft (RO): repo (private Leserechte), read:org bei Bedarf; Issue-Flow + issues.
• Automatisiertes Schreiben (kurzlebig): feingranularer PAT, ein Repo, Contents/Issues write, 7–30 Tage, danach aus mcpServers entfernen.

Speicherung: Umgebungsvariable (GITHUB_MCP_TOKEN), nicht im Repo; Cloud Mac = Instanz-Secret, lokal = Keychain / 1Password.

# Beispiel: Scope-Denke — GitHub-Oberfläche ist maßgeblich
# Feingranular · ein Repo · Contents RO + Issues RW

CodeGraph · read-only Index

1. Nach codegraph init: .codegraph/ als Build-Artefakt behandeln.
2. MCP-Prozess auf Quellcode read-only; Rebuild per CI oder manuell, nicht per Chat.
3. Leerer codegraph_impact: zuerst Index und CWD prüfen — nicht sofort Schreibrechte.

Große Repos: CodeGraph & AI Coding Agent — Policy bleibt RO für den Graph.

API MCP · Staging read-only

• Nur Staging-Base-URL in mcpServers; keine Produktions-URL.
• DB-Account nur SELECT; Schreiben über separaten Dienst (api-staging-rw), in Claude default aus.
• PII in Antworten redigieren; kein Roh-JSON in Issue-Kommentare.

~/.claude.json · Minimalbeispiel

Feldnamen können je Version abweichen — wichtig: getrennte Dienste, getrennte Env-Vars, minimale aktive Menge.

{
  "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 ist illustrativ — ohne Switch: OS-RO-Mount.

Checkliste vor Go-Live (Kurzfassung)

• □ GitHub-PAT mit minimalen Scopes, nicht in git?
• □ Schreibender API-MCP auf Produktion — falls ja, default aus?
• □ CodeGraph nur impact/query?
• □ Cloud Mac: CWD = ein Repo, keine fremden .env?
• □ Runner-Token getrennt vom MCP-Token?
• □ Team kennt Referenzdokument? (dieser Artikel + Überblick)

Fehlkonfiguration · Angriffskette

Typische „Effizienz“-Kombination, die per Agent-Kette eskaliert:

1. Ausgangslage (plausibel)

• Ein mcpServers-Profil: GitHub (repo write) + FS + CodeGraph gemeinsam.
• CodeGraph beschreibbar am Monorepo-Root; API-Staging mit INSERT.
• Workspace = Repo-Root, .env* nicht ausgeschlossen.

2. Auslöser

Auftrag: „Bug zu Issue #42 fixen und Repro-Schritte im PR aktualisieren.“ — GitHub lesen → impact → Staging-Query → FS-Schreiben.

3. Eskalation

1. FS schreibt Nachbar-Subprojekt.
2. CodeGraph überschreibt .codegraph/.
3. API-INSERT mit produktionsgleichen Feldnamen im PR-Text.
4. GitHub-Kommentar triggert Label-CI.

4. Schaden

• Falsche Config im PR; verunreinigtes Staging; unzuverlässiger Index.
• DATABASE_URL-Fragment im PR → Secret-Scan-Alarm (Leak).

5. Remediation

1. PAT widerrufen → feingranular RO, Schreib-Token 7–30 Tage separat.
2. CodeGraph RO-Mount; Rebuild nur Runner nachts.
3. API api-ro / api-rw trennen; Claude nur RO.
4. CI-Scan; kein gemeinsamer App-Key mit MCP.

Serie · Weiterlesen

Dieser Artikel = Seite 1 · Norm. Kurzanleitung und Störungen als eigene Seiten:

Ausblick: Policy as Code

Die Matrix lässt sich als JSON-Allowlist, MCP-DSL oder CI-Gates (keine Prod-URL / kein Voll-PAT im Repo) automatisieren — nach Threat Model (③) getrennt vom Normtext.

FAQ

CodeGraph read-only?
Ja, empfohlen. Index per CI oder manuell; Dialog nur Query.

GitHub MCP mit Schreibrechten?
Kommentare/Labels möglich; merge/push nur kurzlebig und mit Freigabe — nicht 24/7 in Claude.

Runner-Secrets teilen?
Nein. MCP = interaktiver Agent; Runner = CI — unterschiedliche Leak- und Rotationslogik.

MCP „tot“ nach Setup?
Connectivity: Problemkarte im Überblick; Störungsseite L4-Q07 geplant.

Dokumentmetadaten · Serie

Version: AI-Agent-Berechtigungssicherheit v1.0 (stabil). Serie: Cloud Mac AI Stack · L4 Sicherheitsnorm — MCP-Berechtigungsmodell & Threat Control.