Licensed to be used in conjunction with basebox, only.
// integration
Konnektoren entwickeln
Gilt für
Produkt: Cloud · Server · Zielgruppe: Entwickler / Integrator
basebox-Konnektoren sind MCP-Server. Dieser Abschnitt erklärt, wie Sie einen bauen, der zu basebox passt: Architektur, Authentifizierung je Nutzer, lesende und schreibende Werkzeuge, Berechtigungen und die mitgelieferten Konnektoren als Vorlage. Wer sich an die Regeln hält, bekommt einen Konnektor, der in jeder App freigegeben werden kann, ohne dass Administratoren oder Datenschutz nachfragen müssen.
Was ein Konnektor in basebox ist
Ein Konnektor ist ein MCP-Server (Model Context Protocol), der dem Assistenten Werkzeuge bereitstellt – etwa „Seite suchen", „Issue lesen", „Postfach durchsuchen". Der Anwendungsserver AISRV ist der MCP-Client: Er holt die Werkzeugliste, bietet sie dem Modell an, fängt Aufrufe ab, setzt die Zugangsdaten des Nutzers ein, ruft den Server per HTTP auf und rahmt das Ergebnis als Daten ein. Wie das im Detail läuft: MCP-Client · Autorisierungsablauf.
Die sechs Regeln
| Regel | Was sie bedeutet | Seite |
|---|---|---|
| 1. Zustandslos zwischen basebox und Zielsystem | Der Server hält keine Sitzungen, keinen Cache über Nutzer hinweg, keine Kopie von Berechtigungen | Architektur |
| 2. Zugangsdaten durchreichen, nicht besitzen | Persönliche Tokens kommen je Anfrage im Authorization-Header an und gehen unverändert ans Zielsystem; nie speichern, nie loggen |
Authentifizierung |
| 3. Lesen liefert kleine, strukturierte Daten | Suchen, Abrufen, Auflisten mit begrenzten Ergebnissen als reiner Text mit stabilen Verweisen | Lesezugriff |
| 4. Schreiben ist getrennt und explizit | Eigene Werkzeuge für Änderungen, idempotent, ohne Massenoperationen; in basebox je App standardmäßig aus | Schreibzugriff |
| 5. Das Zielsystem entscheidet über Rechte | Verweigert es, gibt der Konnektor das als Ergebnis zurück – er umgeht nichts | Berechtigungen |
| 6. Nur ein Ziel im Netz | Der Server erreicht genau sein Zielsystem; das MCP-Gateway blockiert alles andere | Architektur |
Der Weg zum fertigen Konnektor
- Zielsystem prüfen. Hat es eine API mit Authentifizierung je Nutzer, Suche und gezielten Abruf? Siehe Fachsysteme → Was ein System mitbringen sollte.
- Zugangsmodell festlegen – persönliche Zugangsdaten (Regelfall) oder Servicekonto (nur für allgemein zugängliche Inhalte).
- Werkzeuge entwerfen – zuerst nur lesend. Namen, Beschreibungen und Parameter so, dass ein Sprachmodell sie richtig einsetzt.
- Server bauen – HTTP-Transport auf
/mcp, Non-Root-Container, Readiness- und Liveness-Probe, keine Zugangsdaten in Logs. - Lokal gegen das Zielsystem testen – mit einem Token, das wenig darf, und prüfen, dass Verweigerungen sauber zurückkommen.
- Bereitstellen – auf basebox Server per Helm als
byo-Konnektor durch den Platform Operator (MCP-Server anbinden); in der Cloud in Abstimmung mit basebox. - Freigeben lassen – der Administrator konfiguriert, testet die Verbindung und gibt den Konnektor je App frei.
- Erst dann Schreibwerkzeuge ergänzen, wenn der Bedarf klar ist.
Was Sie nicht bauen müssen
- Rechteverwaltung – die bleibt beim Zielsystem.
- Nutzerverwaltung oder Login-Masken – Nutzer tragen ihr Token in basebox ein; basebox liefert es Ihnen je Anfrage.
- Prompt-Injection-Schutz im Sinne von Filtern – basebox rahmt Ihre Ergebnisse als Daten. Ihr Beitrag: reiner Text, begrenzte Größe, keine aktiven Inhalte.
- Audit-Logging – basebox protokolliert jeden Werkzeugaufruf mit Nutzer, Werkzeug, Ziel, Ergebnis und Zeitstempel.
Vorlagen
Die mitgelieferten Konnektoren zeigen die Muster: Websuche (ein Anbieter, Egress-Allowlist, Nur-Text-Ergebnisse), DokuWiki (persönliche Zugangsdaten, Suche und Lesen), YouTrack (gehosteter MCP, permanentes Token, Lesen und – freigegeben – Schreiben), E-Mail (persönlicher Postfachzugang), Rechner (ohne Anmeldung). Ausgearbeitet unter Beispiele.
Weiter: Architektur