MCP-Einrichtung

Diese Anleitung fuehrt dich durch die Verbindung deines KI-Coding-Assistenten mit DevFlow ueber das Model Context Protocol (MCP).

Was ist MCP?

Das Model Context Protocol (MCP) ist ein Standard fuer die Integration von KI-Assistenten mit externen Tools. Anstatt Kontext hin und her zu kopieren, gibt MCP dem KI-Agent direkten Zugriff auf strukturierte Tools — Flows lesen, Tasks erstellen, Fortschritt melden und mehr.

Stell es dir so vor, als wuerdest du dem KI-Agent einen Platz an deinem Schreibtisch geben. Er kann dein Projekt sehen, deine Aufgaben verstehen und seine Arbeit berichten — alles ueber eine klar definierte Schnittstelle.

MCP-Server installieren

Der DevFlow MCP-Server funktioniert mit jedem MCP-kompatiblen KI-Client. Der empfohlene Weg ist der Einrichtungsassistent in DevFlow oder das direkte Ausfuehren des Setup-Befehls.

Einrichtungsassistent (empfohlen)

Gehe in der DevFlow-UI zu Settings > Agent und klicke auf Add Client. Der interaktive Assistent fuehrt dich durch:

Deinen KI-Client auswaehlen (Claude Code, Cursor, Windsurf, Gemini CLI oder andere)
Den Setup-Befehl ausfuehren (wird direkt angezeigt, bereit zum Kopieren)
Die Verbindung bestaetigen

Der Assistent zeigt ausserdem das Client-Dashboard — eine Matrix-Ansicht, welche Clients mit welchen Projekten verbunden sind. So siehst du auf einen Blick, wo der MCP-Server aktiv ist, und kannst Verbindungen zentral verwalten.

Claude Code

Als Claude Code Plugin installieren:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install devflow

Das installiert alles in einem Schritt: der MCP-Server wird ueber das mcpServers-Manifest des Plugins automatisch registriert, zusammen mit Enforcement-Hooks, state-spezifischen Skills und Slash Commands (/devflow-start, /devflow-status, /devflow-next, /devflow-tasks, /devflow-create, /devflow-list, /devflow-review). Beim ersten Start oeffnet sich ein Browser zur Authentifizierung.

DevFlow ist im offiziellen Anthropic Community Marketplace gelistet. Kein separater npx ... setup Schritt noetig — das Plugin uebernimmt die MCP-Registrierung selbst (seit devflow-mcp 4.23).

Updates: /plugin update devflow. Starte Claude Code nach der Installation neu.

Cursor

npx github:KlausFreiberufler/devflow-mcp setup --client cursor

Gemini CLI

npx github:KlausFreiberufler/devflow-mcp setup --client gemini

Windsurf

npx github:KlausFreiberufler/devflow-mcp setup --client windsurf

Eigene Backend-URL

Wenn deine DevFlow-Instanz unter einer anderen URL laeuft:

npx github:KlausFreiberufler/devflow-mcp setup --url https://deine-instanz.example.com

Aktualisieren

Um auf die neueste Version zu aktualisieren, fuehre den Setup-Befehl erneut aus:

npx github:KlausFreiberufler/devflow-mcp setup

Das Setup erkennt vorhandene Registrierungen und aktualisiert sie.

Authentifizierung

Der MCP-Server nutzt deine DevFlow-Zugangsdaten. Beim ersten Start oeffnet sich ein Browser-Fenster zur Anmeldung. Deine Session wird lokal gespeichert, sodass du dich nicht jedes Mal neu authentifizieren musst.

Alternativ kannst du einen API-Token verwenden (erstelle einen unter Settings > Agent):

export DEVFLOW_TOKEN="dein-token"

Der Agent erbt deine Berechtigungen — er kann nur auf Projekte und Flows zugreifen, auf die du auch Zugriff hast.

Projekt-Verknuepfung

Die Projekt-Verknuepfung erfolgt automatisch. Wenn der Agent devflow_init mit einer Flow-ID aufruft, ermittelt DevFlow das Projekt anhand des Flows und begrenzt die Session entsprechend. Es ist keine manuelle Konfiguration oder .devflow.json-Datei erforderlich.

Wenn du in mehreren Repositories arbeitest, wird jedes Repository-Verzeichnis unabhaengig erkannt. Der Agent arbeitet immer im Kontext des Flows, mit dem er initialisiert wurde.

Verfuegbare Tools

Nach der Verbindung hat der KI-Agent Zugriff auf folgende Tools:

Tool	Zweck
`devflow_init`	Eine Arbeitssession fuer einen Flow starten (zuerst erforderlich)
`flow_list`	Alle Flows eines Projekts auflisten
`flow_get`	Vollstaendiger Flow-Kontext — Beschreibung, Plan, Attachments (Markdown inline + Bilder als Content-Blocks)
`flow_create`	Einen neuen Flow erstellen
`flow_update`	Flow-Status aendern, Plaene einreichen oder Ergebnisse liefern
`flow_upload`	Datei (Markdown, HTML, PDF, Bild etc.) als Attachment hochladen — mit `kind: "plan"` wird sie als Implementation Plan des Flows verlinkt
`flow_get_feedback`	Benutzer-Feedback zu Plaenen oder Reviews pruefen
`task_list`	Tasks eines Flows auflisten
`task_create`	Tasks zur Aufgliederung der Arbeit erstellen
`task_update`	Tasks als erledigt markieren oder Details aktualisieren
`project_knowledge_get`	Projekt-Wissensbasis lesen
`project_knowledge_update`	Projekt-Wissensbasis aktualisieren
`project_guidelines_get`	Projekt-Richtlinien lesen
`release_list`	Releases auflisten
`release_get`	Release-Details abrufen
`release_create`	Neuen Release erstellen
`release_update`	Release aktualisieren
`search`	Ueber Flows, Tasks und Projekte hinweg suchen
`agent_session_create`	Agent-Arbeitssession starten
`agent_session_log`	Fortschritt waehrend einer Session loggen
`agent_session_complete`	Agent-Session abschliessen
`wiki_search`, `wiki_get_page`, `wiki_list_by_type`, `wiki_backlinks`, `wiki_graph_neighbors`, `wiki_get_flow_context`, `wiki_get_project_context`	Knowledge-Wiki Lese-Tools (DF-226)
`adr_list`, `adr_get`, `adr_accept`, `adr_update_status`, `adr_get_audit_log`	Architecture Decision Records (DF-225/241/248)
`knowledge_backfill_request`, `knowledge_draft_list`, `knowledge_draft_create`, `knowledge_draft_accept`, `knowledge_draft_reject`, `knowledge_harvest`, `knowledge_check_flow`, `knowledge_check_drift`	MCP-first Knowledge-Drafts + Harvest (DF-244/245/246/238)

Hinweis zum Enforcement (DF-248): Welche Tools verfuegbar sind, haengt vom Flow-State ab. Read-Tools (wiki_*, adr_list/get, search, knowledge_check_*) sind in jedem Working-State erlaubt. Write-Tools (knowledge_draft_*, adr_accept, flow_upload, …) in planning und in_progress. knowledge_harvest bleibt in done erlaubt, damit der Post-Flow-Harvest-Hinweis funktioniert. Details in CLAUDE.md → “MCP Enforcement Allowlist”.

Der Agent nutzt diese Tools, um am gesamten Flow-Lebenszyklus teilzunehmen — von der Planung ueber die Implementierung bis zum Review.

Rich Attachments & Plaene als Markdown-Dateien

Ab DevFlow 4.3 behandelt der MCP-Server Attachments als erstklassigen Kontext:

flow_get laedt vollstaendige Inhalte. Markdown-, Text-, HTML- und JSON-Attachments werden inline in der Tool-Response unter ## Attachment: <filename> eingebettet — der Agent sieht den kompletten Dateiinhalt, nicht nur einen Link. Bilder (sowohl als Attachments als auch als eingebettete Bilder im Rich-Text-Editor der Beschreibung) werden als MCP-image-Content-Blocks zurueckgegeben, damit der Agent sie tatsaechlich sehen kann.
flow_upload unterstuetzt einen kind-Parameter. Mit kind: "plan" laedst du den Implementation Plan als Markdown-Datei hoch — DevFlow verknuepft sie automatisch mit dem Flow, sodass sie in der UI als formatiertes Markdown gerendert wird (das implementation_plan-DB-Feld wird zum Pointer statt Blob). Weitere Werte: summary, design, notes.
Auth-geschuetzte Inhalte. Alle Attachment-Inhalte werden ueber GET /api/flows/:id/attachments/:attId/content ausgeliefert. Der Endpoint erfordert Auth und Flow-Access. Die alten oeffentlichen /uploads/flow-attachments/*-URLs sind blockiert. In der UI werden HTML- und PDF-Attachments inline im Browser gerendert (per Blob-URL) — kein Download noetig.

So hat der Agent das komplette Bild eines Flows (Plaene, Design-Dokumente, Screenshots, Referenz-HTML) ohne raten oder nachfragen zu muessen.

Pipeline-Integration

Projekte mit Pipeline-Regeln erhalten erweitertes Agent-Verhalten:

Step-basierte Berechtigungen — Der Agent bekommt nur Tools, die fuer den aktuellen Pipeline-Step relevant sind
Gate-Enforcement — Steps mit transitionPolicy: human_only blockieren den Agent bis ein Mensch in der UI genehmigt
Skill-Zuordnung — Jedem Step koennen Skills zugewiesen werden, die das Agent-Verhalten steuern
Retry-Handling — Wenn der Mensch Arbeit ablehnt, bekommt der Agent das Feedback und kann es erneut versuchen

Das Backend ist die einzige Source of Truth fuer das, was der Agent tun darf. Der MCP-Server leitet diese Berechtigungen nur weiter, ohne eigene Logik hinzuzufuegen.

Verbindung testen

Nach der Einrichtung pruefe die Verbindung, indem du deinen KI-Assistenten bittest, deine Flows aufzulisten:

“Liste meine DevFlow Flows auf”

Der Agent sollte flow_list aufrufen und deine aktiven Flows zurueckgeben. Wenn du deine Projektdaten siehst, funktioniert die Verbindung.

Du kannst ausserdem das Client-Dashboard unter Settings > Agent aufrufen, um zu bestaetigen, dass der Client als verbunden angezeigt wird.

Fehlerbehebung

ENOENT-Fehler beim Start des MCP-Servers

Das passiert, wenn eine GUI-App (Cursor, Windsurf, VS Code) node nicht findet, weil sie den Shell-PATH nicht erbt
Fuehre den Setup-Befehl erneut aus — er installiert einen Shell-Wrapper, der den node-Pfad automatisch aufloest
Starte deinen KI-Client nach dem erneuten Setup neu

Verbindungs-Timeouts

Pruefe, ob dein DevFlow-Backend erreichbar ist: oeffne https://api.app.dev-flow.tech/health im Browser
Wenn du hinter einem VPN oder einer Firewall arbeitest, stelle sicher, dass der MCP-Server die Backend-URL erreichen kann
Pruefe, ob die URL in deiner MCP-Client-Konfiguration mit deiner DevFlow-Instanz uebereinstimmt

Der Agent findet keine Flows

Pruefe ob der MCP-Server registriert ist (z.B. claude mcp list fuer Claude Code)
Stelle sicher, dass du authentifiziert bist
Vergewissere dich, dass du mindestens ein Projekt mit Flows hast

Der Agent kann Flows nicht aktualisieren

Stelle sicher, dass der Flow nicht von einer anderen Agent Session gesperrt ist
Pruefe, ob der Flow sich in einem Status befindet, der die angeforderte Aktion erlaubt
Pruefe die Pipeline-transitionPolicy fuer den aktuellen Step

Der Agent wird bei einem Step blockiert

Der Step hat moeglicherweise transitionPolicy: human_only — genehmige oder lehne in der DevFlow-UI ab
Pruefe die Pipeline-Regeln unter Project Settings > Rules

Update-Probleme

Fuehre npx github:KlausFreiberufler/devflow-mcp setup aus um die neueste Version zu erhalten
Starte deinen KI-Client nach dem Update neu