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

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup

Das Setup-Kommando macht automatisch:

Installiert einen Shell-Wrapper, der den korrekten node-Pfad aufloest — das verhindert ENOENT-Fehler in GUI-Apps wie Cursor und Windsurf, die den Shell-PATH nicht erben
Registriert den MCP-Server bei Claude Code
Verbindet mit deiner DevFlow-Instanz
Oeffnet einen Browser zur Authentifizierung beim ersten Start

Starte Claude Code nach dem Setup neu.

Cursor

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup --client cursor

Gemini CLI

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup --client gemini

Windsurf

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup --client windsurf

Eigene Backend-URL

Wenn deine DevFlow-Instanz unter einer anderen URL laeuft:

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup --url https://deine-instanz.example.com

Aktualisieren

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

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz 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`	Details eines bestimmten Flows abrufen
`flow_create`	Einen neuen Flow erstellen
`flow_update`	Flow-Status aendern, Plaene einreichen oder Ergebnisse liefern
`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

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

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 https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup aus um die neueste Version zu erhalten
Starte deinen KI-Client nach dem Update neu