Licensed to be used in conjunction with basebox, only.
// integration
Architektur
Gilt für
Produkt: Cloud · Server · Zielgruppe: Entwickler / Integrator · Platform Operator
Wie ein Konnektor zwischen basebox und einem externen System sitzt: MCP-Gateway, Egress-Allowlist, Freigabe je App, und wo Zugangsdaten liegen. Wer diese Grenzen kennt, baut den Server automatisch so, dass er sicher betrieben werden kann.
Das Bild
flowchart LR
subgraph BB["basebox-Umgebung"]
AISRV["AISRV<br/>MCP-Gateway · Zugriffskontrolle · Zugangsdaten je Nutzer"]
DB[("basebox-DB<br/>Einstellungen je Nutzer<br/>Werkzeugfreigaben je App")]
MCP["Ihr MCP-Server<br/>Container · Service mcp-<name><br/>HTTP /mcp"]
AISRV --- DB
AISRV -->|"POST /mcp<br/>Authorization: <Nutzer-Token>"| MCP
end
MCP -->|"nur dieser Host<br/>(Egress-Allowlist)"| EXT["Zielsystem<br/>Wiki · Tickets · Fachanwendung"]
MCP -. "blockiert" .-x OTHER["alles andere"]
style AISRV fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
style MCP fill:#dcefe2,stroke:#3a7a49,color:#1d1e1c
style EXT fill:#dbeafe,stroke:#1e40af,color:#1d1e1cDie Bausteine
AISRV (MCP-Gateway). Validiert das Nutzer-Token, lädt aus der basebox-Datenbank die Zugangsdaten dieses Nutzers für Ihren Konnektor und die Werkzeugfreigaben der aktuellen App, bildet die Schnittmenge, bietet dem Modell die erlaubten Werkzeuge an, fängt Aufrufe ab, setzt den Authorization-Header und ruft Ihren Server auf. Es rahmt Ihr Ergebnis als Daten ein und protokolliert den Aufruf im Audit-Log.
Ihr MCP-Server. Ein Container im basebox-Cluster (auf Server per Helm als byo-Konnektor; Service mcp-<name>, Endpunkt http://mcp-<name>:<port>/mcp) oder – wo vorhanden – ein vom Anbieter gehosteter MCP-Endpunkt. Er übersetzt Werkzeugaufrufe in API-Aufrufe des Zielsystems und Antworten in begrenzte, strukturierte Ergebnisse.
Das Zielsystem. Setzt seine eigenen Berechtigungen durch, weil es die Anfrage mit den Zugangsdaten der Person erhält.
Wo Zugangsdaten liegen
| Art | Ort | Wer sieht sie |
|---|---|---|
| Persönliche Zugangsdaten (Token je Nutzer) | basebox-Datenbank, Tabelle der Nutzereinstellungen; nur schreibend, nie an den Browser zurück, in Logs ausgeblendet | Niemand – auch kein Administrator; Ihr Server erhält sie je Anfrage im Header |
| Maschinelle Zugangsdaten (Servicekonto, API-Schlüssel des Konnektors) | Kubernetes-Secret, per valueFrom.secretKeyRef als Umgebungsvariable in Ihren Container |
Platform Operator |
| Konfiguration (Basis-URL, Endpunkte) | Helm-Values (global.<system>.…) bzw. Admin-Oberfläche |
Platform Operator, Administrator |
Ihr Server speichert keine persönlichen Zugangsdaten. Er verwendet den Header für genau diesen Aufruf und vergisst ihn.
Netzwerkgrenzen
- Eingehend erreicht Ihren Server nur AISRV innerhalb des Clusters (ClusterIP). Kein Ingress, keine Freigabe nach außen.
- Ausgehend darf Ihr Server nur sein Zielsystem erreichen. Das MCP-Gateway erzwingt eine Egress-Allowlist; Network Policy, DNS, TLS-Vertrauen und Firewall müssen genau diesen Pfad erlauben. Bauen Sie den Server so, dass er nichts anderes braucht – keine Telemetrie, keine Schriftarten, keine Drittanbieter-SDKs, die nach Hause telefonieren.
- TLS zum Zielsystem ist Pflicht, wenn der Pfad das Cluster verlässt. Private CAs importieren Sie in den Container-Truststore.
Zustand und Nebenläufigkeit
- Keine Sitzungen. Jede Anfrage ist vollständig: Header, Werkzeug, Parameter. Ohne Cookies, ohne Login-Zustand.
- Kein Cache über Nutzer hinweg. Was Nutzer A abgerufen hat, darf Nutzer B nicht aus einem Cache erhalten. Wenn Sie cachen, dann nur innerhalb einer Anfrage.
- Parallel und idempotent. Mehrere Nutzer rufen gleichzeitig auf; lesende Werkzeuge müssen beliebig wiederholbar sein.
- Horizontal skalierbar. Ohne Zustand können mehrere Replikate laufen.
Betriebliche Anforderungen
| Anforderung | Umsetzung |
|---|---|
| HTTP-Transport | MCP über HTTP auf dem konfigurierten Port, Pfad /mcp |
| Non-Root | Container läuft ohne Root-Rechte, schreibgeschütztes Dateisystem, wo möglich |
| Probes | Readiness und Liveness (tcpSocket oder HTTP) im Helm-Eintrag konfigurierbar |
| Konfiguration | Über Umgebungsvariablen; Secrets aus Kubernetes-Secrets |
| Logging | Strukturiert nach stdout; nie Header, Tokens, Passwörter oder Dokumentinhalte; Zugangsdaten höchstens auf DEBUG in Diagnoseläufen |
| Fehler | Fehler des Zielsystems (401, 403, 404, 5xx) werden zu Werkzeugergebnissen mit klarer Ursache, nicht zu Abstürzen |
| Größenlimits | Ergebnisse je Werkzeugaufruf begrenzen (Zeichen, Treffer); große Dokumente paginieren oder kürzen |
Was zu basebox gehört – und was zu Ihnen
| basebox | Ihr Konnektor |
|---|---|
| Token-Validierung, Nutzeridentität | API-Aufrufe ans Zielsystem |
| Zugangsdaten je Nutzer speichern und einsetzen | Header unverändert weiterreichen |
| Freigabe je Organisation und je App | Werkzeuge klar beschreiben |
| Schreibwerkzeuge standardmäßig sperren | Lese- und Schreibwerkzeuge sauber trennen |
| Ergebnisse als Daten rahmen | Reinen Text ohne aktive Inhalte liefern |
| Audit-Log je Aufruf | Strukturiertes Betriebslog ohne Geheimnisse |
| Egress-Allowlist erzwingen | Nur das Zielsystem brauchen |
Weiter: Authentifizierung · MCP-Server anbinden