MCP-Integration (KI-Werkzeug-Zugang)

Canopy enthält einen integrierten MCP-Server (Model Context Protocol), der KI-Werkzeugen — wie Claude Desktop, GitHub Copilot, Cursor und VS Code — ermöglicht, EA-Daten direkt abzufragen und zu aktualisieren. KI-Werkzeuge können außerdem Artefakte (Tabellen, BPMN-Diagramme, DrawIO-Diagramme, freie Dokumente) hochladen und in Karten, Beziehungen und Diagramme umwandeln, die in das bestehende Metamodell passen. Benutzer authentifizieren sich über ihren bestehenden SSO-Anbieter, und jede Aktion respektiert ihre individuellen Berechtigungen.

Diese Funktion ist optional und startet nicht automatisch. Sie erfordert, dass SSO konfiguriert ist, das MCP-Profil in Docker Compose aktiviert wird und ein Administrator es in der Einstellungsoberfläche einschaltet.

Funktionsweise

KI-Werkzeug (Claude, Copilot usw.)
    │
    │  MCP-Protokoll (HTTP + SSE)
    ▼
Canopy MCP-Server (:8001, intern)
    │
    │  OAuth 2.1 mit PKCE
    │  delegiert an SSO-Anbieter
    ▼
Canopy Backend (:8000)
    │
    │  RBAC pro Benutzer
    ▼
PostgreSQL

Ein Benutzer fügt die MCP-Server-URL zu seinem KI-Werkzeug hinzu.
Bei der ersten Verbindung öffnet das KI-Werkzeug ein Browserfenster für die SSO-Authentifizierung.
Nach der Anmeldung stellt der MCP-Server ein eigenes Zugriffstoken aus (gestützt durch das Canopy-JWT des Benutzers). Das Token wird proaktiv erneuert, etwa eine Stunde bevor es abläuft.
Das KI-Werkzeug verwendet dieses Token für alle nachfolgenden Anfragen.
Jede Abfrage durchläuft das normale Canopy-Berechtigungssystem — Benutzer sehen nur Daten, auf die sie Zugriff haben.

Voraussetzungen

Vor der Aktivierung von MCP müssen folgende Voraussetzungen erfüllt sein:

SSO konfiguriert und funktionsfähig — MCP delegiert die Authentifizierung an Ihren SSO-Anbieter (Microsoft Entra ID, Google Workspace, Okta oder generisches OIDC). Siehe die Anleitung Authentifizierung und SSO.
HTTPS mit einer öffentlichen Domain — Der OAuth-Ablauf erfordert eine stabile Weiterleitungs-URI. Betreiben Sie Canopy hinter einem TLS-terminierenden Reverse-Proxy (Caddy, Traefik, Cloudflare Tunnel usw.).

Einrichtung

Schritt 1: MCP-Dienst starten

Der MCP-Server ist ein optionales Docker-Compose-Profil. Fügen Sie --profile mcp zu Ihrem Startbefehl hinzu:

docker compose --profile mcp up -d

Dies startet einen leichtgewichtigen Python-Container (Port 8001, nur intern) neben Backend und Frontend. Nginx leitet /mcp/-Anfragen automatisch an ihn weiter — läuft der Container nicht, erhalten Anfragen einen sauberen 502-Fehler, anstatt den Edge-Proxy zum Absturz zu bringen.

Schritt 2: Umgebungsvariablen konfigurieren

Fügen Sie diese zu Ihrer .env-Datei hinzu:

CANOPY_PUBLIC_URL=https://ihre-domain.beispiel.de
MCP_PUBLIC_URL=https://ihre-domain.beispiel.de/mcp

Variable	Standard	Beschreibung
`CANOPY_URL`	`http://backend:8000`	Interne Backend-URL, mit der der MCP-Container kommuniziert (Docker-Dienstname — muss selten geändert werden).
`CANOPY_PUBLIC_URL`	`http://localhost:8920`	Die öffentliche URL Ihrer Canopy-Instanz.
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	Die öffentliche URL des MCP-Servers (wird in OAuth-Weiterleitungs-URIs und Metadaten verwendet).
`MCP_PORT`	`8001`	Interner Port des MCP-Containers (muss selten geändert werden).

Schritt 3: OAuth-Weiterleitungs-URI zur SSO-App hinzufügen

Fügen Sie in der App-Registrierung Ihres SSO-Anbieters (dieselbe, die Sie für die Canopy-Anmeldung eingerichtet haben) diese Weiterleitungs-URI hinzu:

https://ihre-domain.beispiel.de/mcp/oauth/callback

Dies ist erforderlich für den OAuth-Ablauf, der Benutzer authentifiziert, wenn sie sich von ihrem KI-Werkzeug aus verbinden.

Schritt 4: MCP in den Admin-Einstellungen aktivieren

Gehen Sie zu Einstellungen im Administrationsbereich und wählen Sie den Reiter AI.
Scrollen Sie zum Abschnitt MCP-Integration (KI-Werkzeug-Zugang).
Schalten Sie den Schalter auf aktiviert.
Die Oberfläche zeigt die MCP-Server-URL und Einrichtungsanweisungen zum Teilen mit Ihrem Team.

warnung

Der Schalter ist deaktiviert, wenn SSO nicht konfiguriert ist. Richten Sie zuerst SSO ein.

KI-Werkzeuge verbinden

Sobald MCP aktiviert ist, teilen Sie die MCP-Server-URL mit Ihrem Team. Jeder Benutzer fügt sie zu seinem KI-Werkzeug hinzu:

Claude Desktop

Öffnen Sie Einstellungen > Konnektoren > Benutzerdefinierten Konnektor hinzufügen.
Geben Sie die MCP-Server-URL ein: https://ihre-domain.beispiel.de/mcp
Klicken Sie auf Verbinden — ein Browserfenster öffnet sich für die SSO-Anmeldung.
Nach der Authentifizierung kann Claude Ihre EA-Daten abfragen und aktualisieren.

VS Code (GitHub Copilot / Cursor)

Fügen Sie zu Ihrer Arbeitsbereich-Datei .vscode/mcp.json hinzu:

{
  "servers": {
    "canopy": {
      "type": "http",
      "url": "https://ihre-domain.beispiel.de/mcp/mcp"
    }
  }
}

Das doppelte /mcp/mcp ist beabsichtigt — das erste /mcp/ ist der Nginx-Proxy-Pfad, das zweite der MCP-Protokoll-Endpunkt.

Lokales Testen (Stdio-Modus)

Für lokale Entwicklung oder Tests ohne SSO/HTTPS können Sie den MCP-Server im Stdio-Modus ausführen — Claude Desktop startet ihn direkt als lokalen Prozess.

1. MCP-Server-Paket installieren:

pip install ./mcp-server

2. Zur Claude-Desktop-Konfiguration hinzufügen (claude_desktop_config.json):

{
  "mcpServers": {
    "canopy": {
      "command": "python",
      "args": ["-m", "canopy_mcp", "--stdio"],
      "env": {
        "CANOPY_URL": "http://localhost:8000",
        "CANOPY_EMAIL": "[email protected]",
        "CANOPY_PASSWORD": "ihr-passwort"
      }
    }
  }
}

In diesem Modus authentifiziert sich der Server direkt mit E-Mail/Passwort (kein OAuth) und erneuert das Canopy-JWT automatisch im Hintergrund.

Verfügbare Funktionen

Der MCP-Server stellt 47 Werkzeuge bereit: 30 Lese-Werkzeuge in neun Gruppen sowie 17 Schreib-Werkzeuge (13 additiv, 4 destruktiv). Jedes Werkzeug trägt ToolAnnotations (readOnlyHint / destructiveHint / idempotentHint), damit Konnektoren wie Claude Desktop die Zerstörungsgefahr eines Aufrufs in ihrer Oberfläche anzeigen können, bevor ein Benutzer ihn bestätigt.

Sicherheit beim Schreiben durch Trockenlauf

Jedes Schreib-Werkzeug verwendet standardmäßig dry_run=true. In diesem Modus führt das Backend jeden Validator und Resolver aus, erstellt den vollständigen Plan und macht die Transaktion dann rückgängig, sodass nichts dauerhaft gespeichert wird. Das KI-Werkzeug zeigt dem Benutzer die Vorschau; erst nach ausdrücklicher Bestätigung sollte es das Werkzeug erneut mit dry_run=false aufrufen, um den Vorgang zu übernehmen. Dies verhindert, dass ein übereifriger Agent leise Hunderte von Karten auf Grundlage einer falsch interpretierten Tabelle anlegt.

Für größere Commits gibt es eine zweite Sperre: Jeder Commit oberhalb von MCP_BATCH_CONFIRMATION_THRESHOLD (Standard 20 Zeilen) muss ein einmaliges confirm_token zurückspiegeln, das vom vorherigen Trockenlauf ausgestellt wurde. Das Token ist 15 Minuten gültig. Dies wird zweifach durchgesetzt — einmal vom MCP-Wrapper, bevor er überhaupt das Backend aufruft, und ein zweites Mal vom Backend selbst am Commit-Endpunkt — sodass ein Client, der den Trockenlauf-Schritt überspringt, keinen großen, ungeprüften Batch durchschleusen kann.

Mutations-Batches (Audit-Trail)

Jeder Schreib-Aufruf — ob Trockenlauf oder nicht — öffnet vor jeder Datenänderung eine mutation_batches-Zeile, und jedes dabei ausgelöste Ereignis (Karte erstellt, Beziehung angelegt/aktualisiert, Kommentar veröffentlicht, …) wird mit dieser Batch-ID sowie dem Namen des aufrufenden Werkzeugs und dem authentifizierten Benutzer markiert. Das Werkzeug get_change_history rekonstruiert anhand der ID den vollständigen Diff eines Batches auf Ereignisebene, und rollback_batch kann die Schreibvorgänge eines Batches rückgängig machen (siehe unten). Dadurch lässt sich jede MCP-gesteuerte Änderung genau darauf zurückführen, wer welches Werkzeug wann ausgeführt hat — unterscheidbar von derselben Aktion über die Weboberfläche.

Lese-Werkzeuge

Der Server stellt 30 Lese-Werkzeuge in neun Gruppen bereit.

Karten & Metamodell

Werkzeug	Beschreibung
`search_cards`	Karten nach Typ, Status oder Freitext suchen und filtern
`get_card`	Vollständige Details einer Karte per UUID abrufen
`get_card_relations`	Alle mit einer Karte verbundenen Beziehungen abrufen
`get_card_hierarchy`	Vorfahren und Kinder einer Karte abrufen
`list_card_types`	Alle Kartentypen im Metamodell auflisten, mit Feldern und Konfiguration
`get_relation_types`	Beziehungstypen auflisten, optional nach Kartentyp gefiltert
`resolve_card_refs`	Namensbasierte Kartenreferenzen (z. B. „Sales / Customer Mgmt / CRM") vor einem Bulk-Import vorab validieren — zeigt aufgelöste / mehrdeutige / fehlende Treffer an
`analyze_impact`	Mehrstufige Impact-Analyse — durchläuft den Beziehungsgraphen ausgehend von einer Karte bis zu 3 Hops, gruppiert nach Tiefe, mit optionalen Filtern nach Beziehungs- und Kartentyp

Dashboards

Werkzeug	Beschreibung
`get_dashboard`	KPI-Dashboard (Anzahl, Datenqualität, Genehmigungen, Aktivität)
`get_landscape`	Karten eines Typs, gruppiert nach einem verwandten Typ

GRC — Risikoregister

Werkzeug	Beschreibung
`list_risks`	Paginierte, filterbare Liste der EA-Risiken (TOGAF Phase G)
`get_risk`	Detail eines einzelnen Risikos mit verknüpften Karten + Audit-Trail
`get_risk_metrics`	KPIs + 4×4-Matrizen für initiale / residuale Eintrittswahrscheinlichkeit × Auswirkung
`get_card_risks`	Alle Risiken, die aktuell mit einer bestimmten Karte verknüpft sind

GRC — Compliance

Werkzeug	Beschreibung
`list_compliance_findings`	Compliance-Befunde gebündelt nach Regulierung (EU AI Act, DSGVO, NIS2, DORA, SOC 2, ISO 27001)
`get_compliance_overview`	Compliance-Scores + Statusmatrix pro Regulierung + Metadaten des letzten Scans

Governance & Bereitstellung

Werkzeug	Beschreibung
`list_principles`	Veröffentlichte EA-Prinzipien (Aussage, Begründung, Auswirkungen)
`list_adrs`	Architekturentscheidungen (ADRs), filterbar nach Initiative / Karte / Status / Suche
`get_adr`	Einzelnes ADR mit Abschnitten, verknüpften Karten, verwandten ADRs und Unterschriftspfad
`list_soaws`	Statements of Architecture Work einer Initiative

Berichte

Werkzeug	Beschreibung
`get_portfolio_report`	Bubble-Chart-Daten für einen Kartentyp (standardmäßig funktionaler × technischer Fit)
`get_cost_treemap`	Treemap der Kartenkosten, optional gruppiert nach einem verwandten Typ
`get_capability_heatmap`	Hierarchische Business-Capability-Heatmap
`get_data_quality_report`	Vollständigkeits-Aufschlüsselung pro Kartentyp

Karten-Kontext

Werkzeug	Beschreibung
`get_card_stakeholders`	Der Karte zugewiesene Benutzer + Rollen
`get_card_comments`	Kommentar-Threads einer Karte
`get_card_documents`	An einer Karte angehängte Dokument-Links

Diagramme

Werkzeug	Beschreibung
`list_diagrams`	Freihand-Diagramme auflisten, optional gefiltert auf eine Karte
`get_diagram`	Ein einzelnes Diagramm per ID abrufen, einschließlich seines DrawIO-XML

Audit & Änderungsverlauf

Werkzeug	Beschreibung
`get_change_history`	Einen Mutations-Batch anhand seiner ID nachschlagen (liefert den Batch sowie jedes darunter ausgelöste Ereignis in der richtigen Reihenfolge zurück), oder aktuelle Batches nach Akteur, Werkzeugname oder Herkunft (`mcp` / `web` / `api`) durchsuchen

Alle Lese-Werkzeuge unterliegen dem RBAC des authentifizierten Benutzers — eine Betrachterin erhält für unzugängliche Bereiche schlicht eine leere Liste (oder einen 403-Fehler); auf MCP-Ebene ist keine Konfiguration pro Werkzeug nötig.

Schreib-Werkzeuge

Der Server stellt 17 Schreib-Werkzeuge bereit: 13 additive (Erstellen-/Aktualisieren-Aktionen, die keine Daten zerstören) und 4 destruktive (können Daten überschreiben oder entfernen, wobei mehrere davon selbst wiederherstellbar sind — siehe Hinweise unten).

Karten & Lebenszyklus

Werkzeug	Annotation	Beschreibung
`create_cards_bulk`	Additiv	Erstellt in einem Aufruf viele Karten aus artefakt-extrahierten Zeilen (z. B. Tabellenzeilen). Unterstützt Eltern-Referenzen per Name innerhalb desselben Batches mit serverseitiger topologischer Sortierung.
`update_cards_bulk`	Additiv	Aktualisiert in einem Aufruf viele Karten — feldweise Patches mit einem Vorher-/Nachher-Diff pro Zeile im Trockenlauf. `attributes` wird pro Zeile vollständig ersetzt; `strict_attributes=true` lehnt unbekannte Feldschlüssel mit einem Hinweis zur Behebung ab.
`transition_card_lifecycle`	Additiv	Bewegt eine Karte durch Genehmigungsaktionen (`approve` / `reject` / `reset`), Lebenszyklusphasen (`phaseIn` / `active` / `phaseOut` / `endOfLife`) oder Statuswerte (`ACTIVE` / `PHASING_IN` / `PHASING_OUT` / `END_OF_LIFE` / `ARCHIVED`). Liefert eine `pending`-Antwort mit Deep-Link in die Oberfläche, wenn dem Aufrufer die Berechtigung fehlt, statt komplett fehlzuschlagen.
`archive_cards`	Destruktiv	Archiviert (Soft-Delete) eine oder mehrere Karten, mit einer Kaskaden-Vorschau im Trockenlauf (Kinder, verwaiste Beziehungen). Archivierte Karten sind 30 Tage lang wiederherstellbar, bevor sie automatisch endgültig gelöscht werden. Ein hartes/endgültiges Löschen ist über MCP bewusst nicht verfügbar.

Beziehungen & Diagramme

Werkzeug	Annotation	Beschreibung
`upsert_relations_bulk`	Destruktiv	Erstellt oder löscht Beziehungen zwischen Karten. `action: "delete"` wird standardmäßig abgelehnt (siehe Schutzmechanismen unten) — deshalb ist dieses Werkzeug als destruktiv annotiert, obwohl das Erstellen der übliche Fall ist.
`create_diagram`	Additiv	Erstellt ein frei gestaltetes DrawIO-Diagramm, optional verknüpft mit bestehenden Karten per UUID.
`update_diagram`	Destruktiv	Aktualisiert XML, Name, Beschreibung oder verknüpfte Karten eines bestehenden Diagramms — `drawio_xml` ersetzt die Zeichenfläche wortwörtlich.
`import_bpmn`	Additiv	Speichert ein BPMN-2.0-Diagramm an einer bestehenden Geschäftsprozess-Karte und durchläuft dabei den Ablauf Entwurf → Einreichen → Genehmigen. Existiert keine passende Karte, liefert das Werkzeug einen `card_not_found`-Fehler, der auf `create_cards_bulk` verweist, statt stillschweigend eine spärliche Karte anzulegen.

GRC — Risikoregister

Werkzeug	Annotation	Beschreibung
`create_risks`	Additiv	Erstellt ein oder mehrere Risiken, optional mit Verknüpfung betroffener Karten im selben Aufruf.
`update_risks`	Additiv	Aktualisiert bestehende Risiken per ID; `linked_card_ids` ersetzt bei Angabe die Menge der verknüpften betroffenen Karten.

Governance & Bereitstellung

Werkzeug	Annotation	Beschreibung
`create_soaw`	Additiv	Erstellt ein Statement of Architecture Work für eine Initiative.
`create_adr`	Additiv	Erstellt ein Architecture Decision Record (landet standardmäßig im Status `draft`).
`update_adr`	Additiv	Aktualisiert Titel, Abschnitte, Status oder verknüpfte Karten eines bestehenden ADR.
`sign_adr`	Additiv	Unterzeichnet ein ADR. Liefert eine `pending`-Antwort mit Deep-Link, wenn dem Aufrufer `adr.sign` fehlt.

Zusammenarbeit

Werkzeug	Annotation	Beschreibung
`add_card_comment`	Additiv	Veröffentlicht einen (optional verschachtelten) Kommentar auf einer Karte.
`assign_stakeholders`	Additiv	Weist Stakeholder-Rollen auf Karten zu oder entfernt sie. Das Backend hat dafür keinen Bulk-Endpunkt, daher fächert das Werkzeug pro Operation innerhalb eines einzigen Mutations-Batches auf.

Audit

Werkzeug	Annotation	Beschreibung
`rollback_batch`	Destruktiv	Macht die unter einem Mutations-Batch durchgeführten Schreibvorgänge rückgängig, indem seine Ereignisse in umgekehrter Reihenfolge durchlaufen und jeweils das Gegenteil angewendet wird. Deckt `card.created` / `card.updated` / `card.archived` / `card.restored` / `relation.created` / `relation.upserted` ab; andere Ereignistypen erscheinen im Trockenlauf-Plan als `unsupported_events`. Der Rollback selbst wird als neuer Batch protokolliert, sodass der Verlauf nie gelöscht wird. Verweigert die Ausführung, wenn ein späterer Batch dieselben Entitäten berührt hat, es sei denn `force=true` wird gesetzt, was `admin.events` erfordert.

Inhalte, die von diesen Werkzeugen gespeichert werden (Kommentartexte, ADR-/SoAW-Abschnittstexte), werden beim späteren Auslesen als nicht vertrauenswürdige Daten behandelt — der Server interpretiert sie niemals als Anweisungen, sondern zeigt sie nur an.

Typischer Ablauf beim Artefakt-Import

Wenn ein Benutzer dem KI-Agenten eine Tabelle freigibt:

Der Agent ruft list_card_types und get_relation_types auf, um das Metamodell zu verstehen.
Der Agent parst die Tabelle (in seinem eigenen Kontext, nicht in MCP) und baut Zeilen-Dicts auf.
Optional ruft der Agent resolve_card_refs auf, um zu prüfen, ob namensbasierte Eltern-/Beziehungsreferenzen eindeutig aufgelöst werden können.
Der Agent ruft create_cards_bulk(cards=…, dry_run=True) auf und zeigt dem Benutzer die Vorschau.
Der Benutzer bestätigt; der Agent ruft das Werkzeug erneut mit dry_run=False auf (und spiegelt dabei confirm_token zurück, falls der Batch über der Bestätigungsschwelle liegt), um zu übernehmen.
Sind Beziehungsspalten vorhanden, ruft der Agent anschließend upsert_relations_bulk mit demselben Trockenlauf-/Bestätigungszyklus auf.

Der MCP-Server selbst verarbeitet niemals hochgeladene Dateien — das aufrufende KI-Werkzeug liest das Quellartefakt (Tabelle, BPMN-XML, DrawIO-XML, PDF, Bild) in seinem eigenen Kontext und sendet bereits strukturierte Zeilen.

Schutzmechanismen für Schreib-Werkzeuge

Verteidigung in der Tiefe zusätzlich zum Trockenlauf, damit ein Fehlverhalten des LLM keinen Massenschaden verursachen kann:

Größenbegrenzung pro Aufruf. Die MCP-Schreib-Werkzeuge erzwingen eine wesentlich kleinere Obergrenze als die zugrunde liegenden Excel-Import-Endpunkte: 200 Karten für create_cards_bulk / update_cards_bulk / archive_cards, 500 Operationen für upsert_relations_bulk. Groß genug für jeden realistischen Einzel-Artefakt-Upload, klein genug, dass eine Trockenlauf-Vorschau überprüfbar bleibt. Die Backend-Endpunkte selbst akzeptieren für den regulären Excel-Importer der Weboberfläche bis zu 2000/5000.
Bestätigungstoken oberhalb der Schwelle. Commits, die mehr als MCP_BATCH_CONFIRMATION_THRESHOLD Zeilen betreffen (Standard 20), müssen das vom vorherigen Trockenlauf ausgestellte confirm_token zurückspiegeln. Wird sowohl vom MCP-Wrapper als auch vom Backend durchgesetzt.
Standardmäßig keine Löschung von Beziehungen. upsert_relations_bulk lehnt action: "delete"-Operationen ab — zum Entfernen von Beziehungen ist die Weboberfläche zu verwenden, wo die Aktion unter der Identität des Benutzers mit einem expliziten Audit-Trail erfasst wird. Operatoren können dies mit MCP_ALLOW_RELATION_DELETE=true aktivieren.
Kein hartes Löschen. Die Werkzeugsammlung lässt das endgültige Löschen von Karten bewusst weg. archive_cards (Soft-Delete mit 30-tägigem Wiederherstellungsfenster) und rollback_batch sind die einzigen Wege, über MCP Daten zu entfernen, und beide sind trockenlauf-gesichert und als destruktiv annotiert. Jedes künftige Werkzeug, das eine unumkehrbare Änderung durchführt, erfordert zunächst eine RFC-Diskussion.
Notausschalter. MCP_WRITES_ENABLED=false schaltet alle 17 Schreib-Werkzeuge aus, ohne dass Code neu bereitgestellt werden muss. Die 30 Lese-Werkzeuge funktionieren weiter.
Audit-Herkunfts-Marker. Jede Backend-Anfrage vom MCP-Server trägt einen X-Canopy-Origin: mcp-Header (serverseitig auf {mcp, web, api} beschränkt — jeder andere Wert wird verworfen). Ereignisse, die aus diesen Anfragen entstehen, werden im Audit-Payload mit origin: "mcp" markiert, sodass Administratoren MCP-gesteuerte Schreibvorgänge aus der Zeitleiste herausfiltern können. Der Header X-Canopy-Batch reicht die aktuelle Mutations-Batch-ID durch jeden Aufruf innerhalb eines einzelnen Werkzeugaufrufs weiter.

Die Umgebungsvariablen für Schutzmechanismen auf dem MCP-Container:

Variable	Standard	Wirkung
`MCP_WRITES_ENABLED`	`true`	Hauptschalter für Schreib-Werkzeuge. `false` → schreibgeschützter MCP.
`MCP_MAX_CARDS_PER_CALL`	`200`	Harte Obergrenze für Zeilen pro Aufruf bei `create_cards_bulk`, `update_cards_bulk`, `archive_cards`.
`MCP_MAX_RELATIONS_PER_CALL`	`500`	Harte Obergrenze für `upsert_relations_bulk`-Operationen pro Anfrage.
`MCP_ALLOW_RELATION_DELETE`	`false`	Bei `true` akzeptiert `upsert_relations_bulk` `action: "delete"`-Operationen.
`MCP_BATCH_CONFIRMATION_THRESHOLD`	`20`	Zeilenanzahl, oberhalb derer ein Commit ein `confirm_token` aus einem vorherigen Trockenlauf zurückspiegeln muss.
`MCP_REQUIRE_DRYRUN_FIRST`	`true`	Bei `true` wird ein Commit oberhalb der Schwelle ohne passenden vorherigen Trockenlauf in derselben Sitzung abgelehnt. Operatoren können dies für vertrauenswürdige Automatisierungs-Pipelines deaktivieren.

Ressourcen

URI	Beschreibung
`turbo-ea://types`	Alle Kartentypen im Metamodell
`turbo-ea://relation-types`	Alle Beziehungstypen
`turbo-ea://dashboard`	Dashboard-KPIs und zusammenfassende Statistiken

Geführte Prompts

Prompt	Beschreibung
`analyze_landscape`	Mehrstufige Analyse: Dashboard-Übersicht, Typen, Beziehungen
`find_card`	Karte nach Namen suchen, Details und Beziehungen abrufen
`explore_dependencies`	Abbilden, wovon eine Karte abhängt und was von ihr abhängt

Berechtigungen

Rolle	Zugriff
Administrator	MCP-Einstellungen konfigurieren (Berechtigung `admin.mcp`). Vollständiger Lese- + Schreibzugriff über MCP.
Alle authentifizierten Benutzer	Lesezugriff gemäß ihrem bestehenden RBAC. Schreib-Werkzeuge erfordern die passende Backend-Berechtigung für die jeweils ausgeführte Aktion.

Der Datenzugriff über MCP — lesend oder schreibend — folgt demselben RBAC-Modell wie die Weboberfläche. Wenn ein Benutzer in der Inventaroberfläche keine Karten erstellen kann, kann er sie auch nicht über MCP erstellen; es gibt keine separaten MCP-spezifischen Datenberechtigungen. Ausgewählte Berechtigungen nach Werkzeug:

Berechtigung	Steuert
`inventory.create`	`create_cards_bulk`
`inventory.edit`	`update_cards_bulk`, Lebenszyklus-/Statusübergänge über `transition_card_lifecycle`
`inventory.approval_status`	Genehmigungsübergänge (`approve` / `reject` / `reset`) über `transition_card_lifecycle`
`inventory.archive`	`archive_cards`
`relations.manage`	`upsert_relations_bulk`
`diagrams.manage`	`create_diagram`, `update_diagram`
`bpm.edit`	`import_bpmn` (Entwurf); für die Veröffentlichung wird zusätzlich `card.approval_status` auf dem Prozess benötigt, gehalten über die Stakeholder-Rolle `process_owner`, admin oder bpm_admin
`risks.manage`	`create_risks`, `update_risks`
`comments.create`	`add_card_comment`
`stakeholders.manage`	`assign_stakeholders`
`soaw.create`	`create_soaw`
`adr.create`	`create_adr`, `update_adr`
`adr.sign`	`sign_adr`
`admin.events`	`rollback_batch(force=True)` — Aufheben eines Rollback-Konflikts mit einem späteren Batch

Die Berechtigung admin.mcp steuert, wer MCP-Einstellungen verwalten kann. Sie ist standardmäßig nur für die Admin-Rolle verfügbar. Benutzerdefinierten Rollen kann diese Berechtigung über die Rollenverwaltungsseite gewährt werden.

Mehrere Schreib-Werkzeuge scheitern nicht hart, wenn dem Aufrufer eine Berechtigung fehlt, sondern degradieren kontrolliert: transition_card_lifecycle und sign_adr liefern eine pending-Antwort mit einem Deep-Link in die Weboberfläche, sodass eine Person mit der passenden Berechtigung die Aktion dort abschließen kann.

Sicherheit

SSO-delegierte Authentifizierung: Benutzer authentifizieren sich über ihren SSO-Anbieter des Unternehmens. Der MCP-Server sieht oder speichert niemals Passwörter (im HTTP-Modus).
OAuth 2.1 mit PKCE: Der Authentifizierungsablauf verwendet Proof Key for Code Exchange (S256), um das Abfangen von Autorisierungscodes zu verhindern.
RBAC pro Benutzer: Jede MCP-Abfrage — lesend oder schreibend — läuft mit den Berechtigungen des authentifizierten Benutzers. Keine gemeinsamen Dienstkonten.
Trockenlauf standardmäßig beim Schreiben: Schreib-Werkzeuge nutzen standardmäßig eine Validieren-und-Rückgängig-Vorschau. Das KI-Werkzeug muss explizit erneut mit dry_run=false aufrufen, bevor irgendetwas dauerhaft gespeichert wird, und jede Änderung wird unter der Identität des Benutzers als Teil eines Mutations-Batches protokolliert.
Bestätigungstoken-Sperre bei großen Commits: Commits oberhalb der konfigurierbaren Zeilenschwelle erfordern ein Token, das von einem vorherigen Trockenlauf ausgestellt wurde, und werden unabhängig sowohl vom MCP-Wrapper als auch vom Backend geprüft.
Vollständiger Audit-Trail mit Rollback: get_change_history rekonstruiert den Diff jedes Batches anhand seiner ID; rollback_batch kann die unterstützten Ereignistypen eines Batches rückgängig machen — der Rollback selbst wird als neuer, prüfbarer Batch protokolliert.
Keine Dateiverarbeitung in MCP: Der MCP-Server selbst nimmt keine PDFs, Excel-Dateien, Bilder oder anderen binären Artefakte entgegen. Das aufrufende KI-Werkzeug analysiert sie in seinem eigenen Kontext und sendet strukturierte Zeilen. Das hält die Angriffsfläche schmal und vermeidet, dass der Server fehlerhaften Binäreingaben ausgesetzt wird.
Kein hartes Löschen über MCP: Das endgültige Löschen von Karten wird nicht als Werkzeug angeboten. Die einzigen Wege zur Datenentfernung sind archive_cards (30 Tage wiederherstellbarer Soft-Delete) und rollback_batch.
Token-Rotation: Zugriffstoken laufen nach 1 Stunde ab und werden proaktiv erneuert. Erneuerungstoken (Refresh-Token) gelten 30 Tage. Autorisierungscodes sind einmalig verwendbar und laufen nach 10 Minuten ab.
Nur interner Port: Der MCP-Container gibt Port 8001 nur im internen Docker-Netzwerk frei. Jeglicher externer Zugriff läuft über den Nginx-Reverse-Proxy.
Single-Instance-Token-Speicher: OAuth-Tokens werden im Arbeitsspeicher des MCP-Containers gehalten. Wenn Sie mehrere Replikate hinter einem Load Balancer betreiben, binden Sie Sitzungen an eine Instanz oder rechnen Sie damit, dass sich Benutzer nach einem Failover erneut anmelden müssen — Tokens werden nicht zwischen Replikaten geteilt.

Fehlerbehebung

Problem	Lösung
MCP-Schalter ist in den Einstellungen deaktiviert	SSO muss zuerst konfiguriert werden. Gehen Sie zu Einstellungen > Reiter Authentifizierung und richten Sie einen SSO-Anbieter ein.
«host not found» in den Nginx-Logs	Der MCP-Dienst läuft nicht. Starten Sie ihn mit `docker compose --profile mcp up -d`. Die Nginx-Konfiguration behandelt dies problemlos (502-Antwort, kein Absturz).
OAuth-Callback schlägt fehl	Überprüfen Sie, dass Sie `https://ihre-domain.beispiel.de/mcp/oauth/callback` als Weiterleitungs-URI in Ihrer SSO-App-Registrierung hinzugefügt haben.
KI-Werkzeug kann sich nicht verbinden	Überprüfen Sie, dass `MCP_PUBLIC_URL` mit der URL übereinstimmt, die vom Rechner des Benutzers aus erreichbar ist. Stellen Sie sicher, dass HTTPS funktioniert.
Benutzer erhält leere Ergebnisse	MCP respektiert RBAC-Berechtigungen. Wenn ein Benutzer eingeschränkten Zugriff hat, sieht er nur die Karten, die seine Rolle erlaubt.
Schreib-Werkzeug liefert `writes_disabled`	`MCP_WRITES_ENABLED=false` ist auf dieser Instanz gesetzt. Lese-Werkzeuge funktionieren weiterhin; bitten Sie einen Operator, Schreibvorgänge bei Bedarf wieder zu aktivieren.
Commit mit `confirm_token_required` abgelehnt	Der Batch liegt über `MCP_BATCH_CONFIRMATION_THRESHOLD` Zeilen. Führen Sie zuerst erneut mit `dry_run=true` aus und geben Sie dann das zurückgelieferte `confirm_token` beim Commit-Aufruf mit.
Verbindung bricht nach 1 Stunde ab	Das KI-Werkzeug sollte die Token-Erneuerung automatisch durchführen. Falls nicht, verbinden Sie sich erneut.

Funktionsweise​

Voraussetzungen​

Einrichtung​

Schritt 1: MCP-Dienst starten​

Schritt 2: Umgebungsvariablen konfigurieren​

Schritt 3: OAuth-Weiterleitungs-URI zur SSO-App hinzufügen​

Schritt 4: MCP in den Admin-Einstellungen aktivieren​

KI-Werkzeuge verbinden​

Claude Desktop​

VS Code (GitHub Copilot / Cursor)​

Lokales Testen (Stdio-Modus)​

Verfügbare Funktionen​

Sicherheit beim Schreiben durch Trockenlauf​

Mutations-Batches (Audit-Trail)​

Lese-Werkzeuge​

Schreib-Werkzeuge​

Typischer Ablauf beim Artefakt-Import​

Schutzmechanismen für Schreib-Werkzeuge​

Ressourcen​

Geführte Prompts​

Berechtigungen​

Sicherheit​

Fehlerbehebung​