Integration über APIs und MCP

Integration über APIs und MCP

0:00 Willkommen zu Modul neun. Bis hierher kann Lotsenhaus schreiben, zusammenfassen und mit dem Richtlinienlotsen Fragen zu internen Regeln beantworten. Das ist nützlich, aber es bleibt Lesen in einem abgeschlossenen Raum. Spannend wird es, sobald der Assistent in die Systeme hineinreicht, mit denen Brandtner Fördertechnik tatsächlich arbeitet: etwa den Status eines Tickets im Störmelder abfragen oder eine Priorität ändern.

0:24 Genau dort steigt aber auch das Risiko. In diesem Modul sortieren wir die Integrationsmuster, binden Werkzeuge über OpenAPI und über MCP an, klären, wie die Identität einer Person beim Werkzeug ankommt, und sorgen dafür, dass schreibende Aktionen erst nach einer Freigabe laufen. Am Ende hängt der Störmelder kontrolliert an Lotsenhaus.

Integration über APIs und MCP

0:44 Der vierte Tag öffnet die Plattform nach außen. Der Satz auf dieser Folie ist dabei unser Maßstab für den ganzen Tag: Ein Werkzeug darf nie mehr können als der Mensch, in dessen Namen es aufgerufen wird. Das klingt selbstverständlich, ist es technisch aber nicht. Ein Sprachmodell hat keine eigenen Rechte, und ein Werkzeug weiß zunächst nicht, wer vor dem Bildschirm sitzt.

1:05 Diese Lücke schließen wir heute Schritt für Schritt.

Integrationsmuster

1:09 Bevor wir über Protokolle reden, eine Stufe darüber: Was soll die Anbindung überhaupt leisten? Davon hängt mehr ab als von der Technik dahinter. Diese Tabelle ordnet jede Anbindung nach ihrer Wirkung, und die Reihenfolge ist eine Steigerung. Beim Dokumentimport kopieren Sie Inhalte in die Wissensbasis, so wie wir es mit den Richtlinien getan haben.

1:30 Das Risiko ist leise: Die Kopie veraltet, und die Rechte der Quelle bleiben unterwegs liegen. Die Live-Abfrage holt dagegen aktuelle Daten, etwa den Status von SM-4711, und kann dabei mehr herausgeben als gewollt. Beim schreibenden Werkzeug schließlich verändert der Assistent etwas im Zielsystem. Hier zählt jeder doppelte Aufruf.

1:50 Behalten Sie die Fußzeile im Kopf: Wie viel Aufwand Freigabe und Betrieb kosten, entscheidet das Muster, nicht die Technik, mit der Sie es anbinden. Jetzt zur Technik, und Open WebUI bietet vier Wege. Die Logik dahinter ist die Frage, wo der Code läuft. Ein Workspace Tool ist Python direkt im Prozess von Open WebUI, praktisch für kleine Logik, bei der Geheimnisse auf dem Server bleiben.

2:16 Ein OpenAPI Tool Server ist ein eigener Dienst, den die Plattform per HTTP anspricht, der natürliche Weg für vorhandene REST-Dienste. MCP über Streamable HTTP passt, wenn es bereits einen MCP-Server gibt. Und mcpo ist ein Übersetzer für MCP-Server, die kein HTTP sprechen. Die Fußzeile nimmt die Empfehlung vorweg: Für die meisten Installationen nennt die Doku OpenAPI als bevorzugten Weg.

2:43 Warum also OpenAPI für Lotsenhaus? Der wichtigste Grund ist unspektakulär: Brandtner muss nichts Neues erfinden. Ein OpenAPI-Dienst ist eine ganz normale REST-API, und für die gibt es im Unternehmen schon Anmeldung über SSO, API-Gateways, Protokollierung und Quoten. Statuscodes, Idempotenz und Caching funktionieren so, wie Ihr Team es kennt. Dazu kommt Ordnung im Betrieb.

3:06 Der Dienst bringt seine Abhängigkeiten selbst mit, statt Pakete in den Container von Open WebUI zu drücken, wo sie sich gegenseitig stören können. Und Sie können jeden Endpunkt testen, ohne dass überhaupt ein Modell beteiligt ist. Das ist ein echter Gewinn, denn Fehler lassen sich dann klar zuordnen. Integration geht auch in die andere Richtung. Open WebUI ist selbst eine API, und zwar eine OpenAI-kompatible.

3:32 Ein Skript oder ein Fachsystem kann also den Richtlinienlotsen ansprechen, als wäre er ein Modell, und bekommt die Antwort samt Wissensbasis zurück. Im Beispiel fragt ein einfacher HTTP-Aufruf gegen die Testinstanz, ob RL-07 für Mietwagen gilt. Worauf es ankommt, steht in der Beschriftung: Der API-Schlüssel handelt als sein Nutzer. Er hat genau dessen Rechte, nicht mehr und nicht weniger.

3:57 Deshalb sind API Keys auch nicht einfach verfügbar. Der Admin schaltet sie global frei, und alle anderen brauchen dafür eine eigene Berechtigung.

MCP anbinden

4:07 MCP ist das Protokoll, über das gerade alle reden. Schauen wir uns an, was Open WebUI davon wirklich unterstützt und wo die Grenzen liegen. Das Model Context Protocol ist so etwas wie ein gemeinsamer Stecker für Werkzeuge. Ein Server bietet Fähigkeiten an, und jeder Client, der das Protokoll spricht, kann sie nutzen. Open WebUI unterstützt MCP seit Version 0.6.31 nativ, allerdings mit einer wichtigen Einschränkung: nur über den Transport Streamable HTTP. Alles andere braucht einen Übersetzer.

4:40 Bemerkenswert ist auch, wer anbinden darf. MCP-Server legen ausschließlich Administratoren an, im Admin-Bereich unter den externen Tool-Servern. Normale Nutzer können keine eigenen registrieren. Für ein Plattformteam ist das eine gute Nachricht, denn so bleibt die Liste der angebundenen Systeme an einer Stelle unter Kontrolle.

5:02 Diese Tabelle beantwortet eine Frage, die über die Sicherheit der ganzen Anbindung entscheidet: Was kommt beim MCP-Server an? Von oben nach unten wächst die Aussagekraft. Ohne Token weiß der Server gar nichts, das taugt höchstens im internen Netz. Bearer schickt einen festen Schlüssel, also ein technisches Konto, das für alle gleich aussieht.

5:22 Session reicht das Sitzungstoken von Open WebUI weiter. Erst mit den OAuth-Varianten erreicht den Server ein Token, das tatsächlich eine Person beim Identitätsanbieter ausweist. Und achten Sie auf die Fußzeile, eine typische Falle: Bearer ohne eingetragenen Schlüssel sendet einen leeren Header, und viele Server lehnen dann jede Verbindung ab.

5:43 Für stoermelder-tools stehen beide Wege offen, und dieser Vergleich zeigt, dass es kein Besser oder Schlechter gibt, sondern einen Unterschied im Charakter. OpenAPI ist zustandslos, mit festen, deklarierten Endpunkten und einem großen Werkzeugkasten für Doku, Tests und Sicherheitsprüfungen. Dafür fließen Ereignisse nur in eine Richtung, gestreamte Ausgabe gibt es nicht. MCP arbeitet mit Sitzungen, kann mehr und streamt auf Transportebene.

6:11 Interessant ist die erste Zeile. Bei OpenAPI dürfen Nutzer mit der passenden Berechtigung eigene Server anlegen, bei MCP nur Administratoren. Für Lotsenhaus bleibt OpenAPI der Standard, die MCP-Variante dient uns als Vergleich. Viele MCP-Server sprechen kein HTTP, sondern laufen als lokaler Prozess über Standardein- und -ausgabe. Für Open WebUI sind sie so unerreichbar.

6:35 Hier kommt mcpo ins Spiel, ein Dolmetscher, der sich vor einen solchen Server setzt und dessen Fähigkeiten als OpenAPI-Endpunkte anbietet. Im Compose-Beispiel startet mcpo als eigener Dienst, schützt sich mit einem API-Schlüssel und ruft dahinter den Startbefehl des Störmelder-MCP-Servers auf. Der Clou steht in der Beschriftung: Angebunden wird das Ergebnis als OpenAPI-Server, nicht als MCP.

7:01 Damit gelten alle Vorteile, die wir eben für OpenAPI gesehen haben, auch für Server, die ursprünglich nur lokal liefen. Vier Fallen, die in der Praxis viel Zeit kosten. Wer einen MCP-Server versehentlich mit dem Typ OpenAPI anlegt, bekommt keine Fehlermeldung, sondern eine Ladeanzeige, die nie endet. Wer ein Werkzeug mit OAuth 2.1 als Standard an ein Modell hängt, erlebt Abbrüche, weil die Person sich vorher nicht angemeldet hat. Besonders tückisch ist der dritte Punkt.

7:31 Ohne fest gesetzten WEBUI_SECRET_KEY kann Open WebUI nach einem Neustart die gespeicherten OAuth-Tokens nicht mehr lesen, und alle müssen sich neu verbinden. Und viele Werkzeuge auf einem Server brauchen beim Start Zeit. Zehn Sekunden sind der Standard, danach bricht die Initialisierung ab.

Identität und Berechtigung

7:50 Jetzt zur Kernfrage des Tages. Ein Werkzeug soll im Namen einer Person handeln. Also muss es erfahren, wer diese Person ist, und zwar so, dass man sich darauf verlassen kann. Diese Tabelle sortiert die Wege nach einer einzigen Frage: Kann das Werkzeug der Angabe trauen? Die einfachste Variante schickt Kennung, Mailadresse, Rolle und Namen als Header mit. Das ist bequem, aber ein Header ist wie ein Namensschild, das jeder selbst beschriften kann.

8:18 Wer den Tool-Server erreicht, kann sich als beliebige Person ausgeben. Besser ist das signierte JWT, ein Ausweis mit Siegel, den der Dienst mit einem gemeinsamen Geheimnis prüft. Am stärksten sind die OAuth-Varianten, weil das Zielsystem das Token selbst beim Identitätsanbieter prüfen kann. Und Bearer steht unten aus gutem Grund: Ein Schlüssel für alle ist ein technisches Konto, keine Person.

8:42 Hier steckt ein Gedanke, der für alle Integrationen gilt. Eine Anweisung im Systemprompt wie „Ändere nur eigene Tickets“ ist ein frommer Wunsch, keine Kontrolle. Prompts lassen sich umgehen. Die eigentliche Entscheidung muss dort fallen, wo die Daten liegen: stoermelder-tools fragt bei jedem Aufruf im Störmelder nach, ob die anfragende Person dieses Ticket überhaupt sehen darf.

9:03 Dazu kommen die Rechte in Open WebUI selbst. Externe Tool-Server sind Admin-Ressourcen, ohne Freigabe sehen sie nur Administratoren, deshalb geben wir gezielt für lh-it frei. Und ein am Modell hinterlegtes Workspace Tool wirkt nur für Nutzer, die das Tool auch selbst lesen dürfen. Ein Ausschnitt aus der Spezifikation von stoermelder-tools, und er zeigt, wie viel Sicherheit schon im Vertrag stecken kann.

9:27 Jede Operation wird für das Modell zu einem eigenen Werkzeug, mit sprechendem Namen und kurzer Beschreibung. Daran orientiert sich das Modell, wenn es entscheidet, was es aufruft. Interessant ist der Parameter für die Ticketnummer. Er ist nicht einfach irgendein Text, sondern muss dem Muster einer Störmelder-Nummer folgen.

9:46 Wichtig ist, wer das prüft: der Server, nicht das Modell. Das Modell liest die Spezifikation als Hinweis, der Dienst setzt sie durch. Und die Doku rät zu einer eigenen operationId je Endpunkt, damit die Werkzeuge eindeutig bleiben. Diese fünf Schritte sind so etwas wie die Pförtnerroutine des Dienstes, und die Reihenfolge hat einen Sinn.

10:07 Zuerst die Frage, wer da kommt: Das signierte JWT wird geprüft und die Person ausgelesen. Dann die Frage, ob diese Person darf, und zwar im Störmelder selbst. Wenn nicht, gibt es eine klare Ablehnung. Erst danach werden die Eingaben validiert. Beim Ergebnis gilt Sparsamkeit, nur die nötigen Felder und wenige Treffer, denn alles, was zurückkommt, landet im Kontext des Modells.

10:30 Fehler schließlich kommen als verständliche Meldung, nie als Stacktrace. Und beachten Sie die Fußzeile: Open WebUI hat zwar ein Zeitlimit, der Dienst braucht trotzdem eigene Grenzen.

Schreibende Aktionen

10:42 Lesen ist das eine. Sobald ein Werkzeug etwas verändert, wird aus einem Auskunftssystem ein Mitarbeiter mit Handlungsbefugnis. Und dafür braucht es andere Regeln. Der Schlüsselbegriff heißt Idempotenz, und er ist einfacher, als er klingt. Denken Sie an einen Lichtschalter mit den Stellungen An und Aus. Ob Sie ihn einmal oder dreimal auf An drücken, das Licht brennt. Ein Klingelknopf dagegen klingelt bei jedem Druck erneut.

11:09 Genau dieser Unterschied zählt bei Sprachmodellen, denn die wiederholen Aufrufe, wenn eine Antwort ausbleibt oder ein Lauf neu startet. Die Priorität von SM-4711 auf hoch setzen ist ein Lichtschalter. Einen Kommentar ohne eindeutigen Schlüssel hinzufügen ist eine Klingel, und am Ende steht derselbe Kommentar dreimal im Ticket.

11:29 Deshalb gilt: Erst wenn Wiederholen harmlos ist, darf ein Modell handeln. Eine Freigabe lässt sich an vier Stellen einbauen, und jede hat ihren Preis. Die Tool Permissions halten vor jedem Aufruf an und fragen nach Erlauben oder Ablehnen. Das ist der allgemeinste Weg, aber experimentell und standardmäßig aus. Ein Python-Werkzeug kann selbst einen Bestätigungsdialog auslösen, das gilt dann nur für dieses eine Werkzeug.

11:55 Eine Action Function ist ein Knopf an der Nachricht, den ein Mensch drückt, das Modell kann sie gar nicht aufrufen. Und schließlich das Zielsystem selbst: Das Werkzeug legt nur einen Vorschlag an, bestätigt wird im Störmelder. Die Fußzeile enthält eine harte Grenze. Automationen und Channels fragen nie nach. Hier wird die Theorie konkret, und das Muster ist eine Abstufung nach Wirkung.

12:18 Ein Entwurf für eine Richtlinienänderung schadet erst einmal niemandem, denn lh-wissen prüft vor der Veröffentlichung. Ein Kommentar im Ticket braucht ein Erlauben im Chat und dazu einen Schlüssel gegen Dubletten, Sie erinnern sich an die Klingel. Die Prioritätsänderung verlangt beides, das Erlauben im Chat und das Recht im Störmelder. Und die Terminverschiebung in der Projektplanung bleibt im Pilot schlicht abgeschaltet.

12:42 Auch das ist eine legitime Entscheidung. Die Fußzeile formuliert eine Regel, die Sie sich merken sollten: Lesen und Schreiben nie in derselben Operation mischen. Die vier Fallen dieses Kapitels haben einen gemeinsamen Kern: Man glaubt, eine Freigabe zu haben, die es gar nicht gibt. Eine Bitte im Systemprompt hält das Modell nicht davon ab, den Aufruf trotzdem abzusetzen.

13:03 In einem temporären Chat gibt es keinen Ort, an dem die Rückfrage gespeichert werden könnte, also greifen die Tool Permissions dort nicht. Den Modus mit Rückfrage wählt außerdem jede Person selbst, er ist keine Vorgabe, auf die Sie sich verlassen können. Und Automationen laufen grundsätzlich ohne Rückfrage. Ein schreibendes Werkzeug gehört dort nicht hin. Die verlässliche Bremse bleibt deshalb das Recht im Zielsystem.

Übung

13:29 Genug der Theorie. Jetzt bringen wir alles zusammen, was dieser Tag aufgebaut hat, an einem System, das bei Brandtner jeden Tag gebraucht wird. In dieser Übung geht es nicht darum, irgendeinen Dienst einzuhängen. Sie üben, ein Fachsystem so anzubinden, dass drei Dinge zusammenspielen: Die Identität kommt sauber an, das Zielsystem entscheidet über die Berechtigung, und Open WebUI holt vor jeder Änderung eine Freigabe ein.

13:55 Im Labor läuft stoermelder-tools als simulierter OpenAPI Tool Server, eine MCP-Variante steht zum Vergleich bereit. Fertig sind Sie, wenn sich SM-4711 per Chat abfragen lässt, eine Prioritätsänderung erst nach dem Erlauben durchgeht und ein Konto ohne Recht eine klare Ablehnung bekommt. Gerade dieser letzte Fall ist der wichtigste Beweis.

14:16 Der Weg beginnt mit Lesen, nicht mit Klicken. Schauen Sie in die Spezifikation und trennen Sie, welche Operationen nur lesen und welche etwas verändern. Dann legen Sie den Tool-Server im Admin-Bereich an und geben ihn für lh-it frei. Schalten Sie die Identitätsweitergabe ein und prüfen Sie im Dienst, wer dort tatsächlich ankommt.

14:36 Danach aktivieren Sie die Tool Permissions und testen die Prioritätsänderung einmal mit Erlauben und einmal mit Ablehnen. Zum Schluss die Gegenprobe mit einem Konto ohne Recht. Wer früher fertig ist, bindet die MCP-Variante an. Im nächsten Modul erweitern wir Open WebUI selbst und lassen erste agentische Abläufe laufen.