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 und ein Administrator sie 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

1. Ein Benutzer fügt die MCP-Server-URL zu seinem KI-Werkzeug hinzu.
2. Bei der ersten Verbindung öffnet das KI-Werkzeug ein Browserfenster für die SSO-Authentifizierung.
3. 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.
4. Das KI-Werkzeug verwendet dieses Token für alle nachfolgenden Anfragen.
5. 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: 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 2: MCP in den Admin-Einstellungen aktivieren

1. Gehen Sie zu Einstellungen im Administrationsbereich und wählen Sie den Reiter AI.
2. Scrollen Sie zum Abschnitt MCP-Integration (KI-Werkzeug-Zugang).
3. Schalten Sie den Schalter auf aktiviert.
4. 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

1. Öffnen Sie Einstellungen > Konnektoren > Benutzerdefinierten Konnektor hinzufügen.
2. Geben Sie die MCP-Server-URL ein: https://ihre-domain.beispiel.de/mcp
3. Klicken Sie auf Verbinden — ein Browserfenster öffnet sich für die SSO-Anmeldung.
4. 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.

---

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:

1. Der Agent ruft list_card_types und get_relation_types auf, um das Metamodell zu verstehen.
2. Der Agent parst die Tabelle (in seinem eigenen Kontext, nicht in MCP) und baut Zeilen-Dicts auf.
3. Optional ruft der Agent resolve_card_refs auf, um zu prüfen, ob namensbasierte Eltern-/Beziehungsreferenzen eindeutig aufgelöst werden können.
4. Der Agent ruft create_cards_bulk(cards=…, dry_run=True) auf und zeigt dem Benutzer die Vorschau.
5. 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.
6. 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. Kontaktieren Sie den Support, um die Löschung von Beziehungen über MCP für Ihre Instanz zu 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.

Diese Schutzmechanismen sind pro Instanz konfiguriert; kontaktieren Sie den Support, um eine Änderung der untenstehenden Standardwerte zu beantragen:

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. Kontaktieren Sie den Support, um dies für vertrauenswürdige Automatisierungs-Pipelines zu 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	Dies deutet darauf hin, dass der MCP-Dienst auf Ihrer Instanz nicht erreichbar ist — kontaktieren Sie den Support.
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 die in den Einstellungen angezeigte MCP-Server-URL mit der von Ihrem KI-Werkzeug verwendeten übereinstimmt und vom Rechner des Benutzers aus erreichbar ist.
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	Schreibvorgänge sind auf dieser Instanz derzeit deaktiviert. Lese-Werkzeuge funktionieren weiterhin; kontaktieren Sie den Support, um 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.