# Company Brain MCP — Connector-Anleitung
Anleitung, um Claude (Web, Desktop) und andere KI-Werkzeuge (Claude Code, Codex CLI, ChatGPT,
Gemini CLI, VS Code, Cursor) mit dem Company Brain der Plattform zu verbinden — Abschnitt
„Externe KI verbinden“.
> Diese Datei ist die kanonische Quelle (SSOT). Der Dienst liefert sie selbst aus:
> `GET /` und `/setup` als HTML, `/setup.md` als Rohtext, ohne Anmeldung.
> Secrets stehen **nicht** in diesem Dokument und werden für den Connector auch nicht gebraucht.
## Was das Company Brain ist
Ein MCP-Server, der das Team-Wissen der Plattform durchsucht (Doku, Steering, Code, Google-Chat-
Threads und gezielt freigegebene Mails). Er liefert **Belege**, keine fertigen Antworten: der aufrufende Agent schreibt die
Antwort selbst. Jede Zeile gehört zu einem Workspace, und jeder Nutzer sieht nur, was ihm dort
erlaubt ist. Die Rechte werden bei jeder Anfrage live aus der Plattform gelesen.
| | dev | prod |
|---|---|---|
| **MCP-Endpoint** | `https://brain.hcai42.com/mcp` | `https://3cbrain.hcai42.com/mcp` |
| **Anmeldung** | Keycloak `https://keycloak.hcai42.com`, Realm `3cors` | Keycloak `https://3ckeycloak.hcai42.com`, Realm `3cors` |
- **Transport:** Streamable HTTP
- **Auth:** OAuth 2.1, Authorization Code + PKCE (nur S256)
- **Authorization Server (Discovery):** der Endpoint-Origin selbst. Die Protected-Resource-Metadata
des MCP-Endpoints liegt unter `/.well-known/oauth-protected-resource/mcp` (`resource` = die
MCP-Endpoint-URL, darauf zeigt die `401` von `/mcp`); `/authorize`, `/token` und `/register`
werden an Keycloak weitergereicht.
## Tools
| Tool | Zweck |
|------|-------|
| `search` | Belege zu einer Frage aus Doku, Team-Chats und Mails (Label `brain`), gerankt, eine Zeile pro Dokument |
| `search_code` | Code-Stellen zu einem Begriff oder Bezeichner: Pfad, Zeilenbereich (`pfad:L10-L42`) und Auszug, eine Zeile pro Datei |
| `get_document` | ein ganzes Dokument per `id` oder `source_ref` + `workspace_id` |
| `who_knows` | wer zu einem Thema schreibt oder Code dazu committet hat, abgeleitet nur aus den für dich sichtbaren Belegen |
| `related` | was mit einem Objekt (UKK aus CorIM/CorDoc) verbunden ist: Struktur und Herkunft, höchstens 40 Nachbarn |
| `lineage` | woraus ein Objekt abgeleitet ist (`derived_from`) und was daraus abgeleitet wurde (`derived_to`) |
| `list_workspaces` | welche Workspaces dein Werkzeug gerade lesen darf (Name, Freigabe, deine Rolle) |
| `list_objects` | die CorDoc-Dokumente dieser Workspaces, neueste zuerst, mit Adresse (`ukk://…/document/…`); `query` sucht im Namen — oder mit `type specification` die Interviewer-Spezifikationen EINES Workspace (`workspace_id` Pflicht, Adresse `ukk://<workspace>/interviewer_specification/<id>`, weitere Seiten über `cursor`) |
| `read_object` | den Text eines Dokuments: neueste Fassung mit Urheber, Zeit und Versionsliste, oder eine bestimmte Version (`…@v1`); oder den Text einer Spezifikation (`ukk://<workspace>/interviewer_specification/<id>`, ohne `@`, mit Titel, Version und Zeit) |
Es gibt kein Rollen-Gate: jeder Nutzer mit Plattform-Konto kommt herein. Was er sieht, entscheiden
seine Workspace-Mitgliedschaften und — für alle neun Werkzeuge — die Freigabe des Workspaces für
externe KI (Seite **Externe KI**, siehe „Externe KI verbinden“).
### Zusammenhänge und Herkunft (`related`, `lineage`)
Beide Werkzeuge brauchen eine **UKK** (`ukk://<workspace>/<typ>/<id>`), die Adresse eines
Wissensobjekts, zum Beispiel einer CorIM-Instanz, eines Elements oder eines CorDoc-Dokuments.
Beispiele für Fragen an deinen Agenten:
- „Was hängt an `ukk://…`?" ruft `related` auf: die Nachbarn des Objekts (Struktur und Herkunft,
höchstens 40) mit je eigener UKK.
- „Woher stammt `ukk://…`?" ruft `lineage` auf: `derived_from` nennt die Quellen (nächste zuerst),
`derived_to` das, was aus dem Objekt entstanden ist.
Bei einem **Dokument** sind die Quellen gleichrangig (Dokument, Modell, Interview) und keine Kette:
jede steht mit Abstand 1 in `derived_from`.
**Woher bekomme ich eine UKK?** Aus dem UKK-Chip in der CorIM-Instanz (Kopieren-Schaltfläche) oder
aus CorDoc, und aus UKKs, die in Inhalten stehen, die `search` findet. Die Treffer von `search`
selbst tragen noch keine UKK; der Agent kann sie nicht daraus ableiten, gib sie ihm mit.
**Was bedeutet `found: false`?** Die UKK ist unbekannt **oder** du bist nicht Mitglied des
zugehörigen Workspaces; beides sieht gleich aus, damit niemand fremde Objekte erkunden kann. Der
Agent sieht nie mehr, als du in CorIM selbst sehen darfst. Zeigt die Antwort zusätzlich
`reason: center_type_not_supported_for_agents`, ist das Objekt eine Spezifikation; sie lässt sich
für Agenten noch nicht als Ausgangspunkt abfragen. `lineage_unavailable: true` heißt: die
Struktur ist da, die Herkunft konnte gerade nicht gelesen werden. Der Werkzeugfehler
`graph_unavailable` ist ein Betriebsfehler, später erneut versuchen.
## Voraussetzung: ein Plattform-Konto, das zum Keycloak-Login passt
Du meldest dich bei Keycloak an. Der Dienst ordnet diesen Login deinem Plattform-Konto zu:
1. über die verknüpfte Keycloak-Identität deines Kontos (der Normalfall, wenn du dich schon einmal
per Keycloak bei der Plattform angemeldet hast), sonst
2. über deine **bestätigte** E-Mail-Adresse, wenn genau ein aktives Plattform-Konto sie trägt.
Beide Wege verlangen ein **aktives** Plattform-Konto: gesperrte oder gelöschte Konten zählen nicht,
auch wenn die Keycloak-Verknüpfung noch besteht (eine Sperre wirkt innerhalb von höchstens
300 Sekunden). Passt nichts oder ist das verknüpfte Konto gesperrt/gelöscht, antwortet der Dienst
mit `403 no_linked_identity` (siehe Fehlerbilder).
## Claude verbinden (Web und Desktop)
1. In Claude **Settings → Connectors → Add custom connector** öffnen.
2. Als URL den MCP-Endpoint eintragen, z. B. `https://brain.hcai42.com/mcp`. Mehr nicht:
Claude registriert sich per Dynamic Client Registration selbst; Client-ID und Secret bleiben leer.
3. **Connect** klicken. Claude leitet zu Keycloak; dort mit dem eigenen `3cors`-Konto anmelden.
4. Keycloak zeigt beim ersten Verbinden eine **Zustimmungsseite** für den neuen Client: zustimmen.
5. Danach stehen die neun Lesewerkzeuge aus der Tabelle oben im Chat zur Verfügung. Claude zeigt
pro Tool einen Schalter.
Die Desktop-App übernimmt Connectoren aus dem Web-Konto; ein eigener Schritt ist nicht nötig.
## Status und "Was ich sehe" prüfen
Die Gateway-Shell zeigt unter **Company Brain** (Sidebar) pro Konto: ob der Connector schon
einmal verbunden hat (seit wann, wie viele Aufrufe), und in welchen Workspaces ein Korpus liegt —
je Workspace die Anzahl Dateien und Abschnitte. Das ist derselbe Stand, den `search` liefert, nur
als Übersicht statt als Suchtreffer. Ein Admin-Konto (`platform.admin`) sieht zusätzlich alle
Korpus-Workspaces und alle verbundenen Nutzer.
## Claude Code und andere CLI-Werkzeuge
CLI-Werkzeuge melden sich über eine Rücksprungadresse auf `localhost` bzw. `127.0.0.1` an. Seit
Externe KI Stufe 1 sind beide Hosts für die Registrierung zugelassen; die Schritte je Werkzeug
stehen im Abschnitt „Externe KI verbinden“.
## Externe KI verbinden
Dein eigenes KI-Werkzeug liest über die **Leseadresse** („3cors lesen“) dieselben Daten wie
oben — nur aus Workspaces, die du lesen darfst **und** die ihr Owner oder Admin für externe KI
auf **lesen** gestellt hat. Es schreibt nichts.
| | dev | prod |
|---|---|---|
| **Leseadresse** | `https://brain.hcai42.com/mcp` | `https://3cbrain.hcai42.com/mcp` |
**Vorher, einmal je Workspace:** Owner oder Admin öffnet in der Gateway-Shell die Seite
**Externe KI** → **Workspaces** und stellt den Workspace auf **lesen**. Auf derselben Seite unter
**Meine Verbindungen** steht die Leseadresse mit Kopier-Schaltfläche, welche deiner Workspaces
lesbar oder gesperrt sind; der Abschnitt **Protokoll** zeigt, was die Werkzeuge getan haben (Owner und Admin sehen die ganze Workspace-Sicht, jede Person ihre eigenen Zeilen). Aufrufe von Personen, die nicht (mehr) Mitglied des Workspace sind, stehen dort ohne Namen als „Person außerhalb des Workspace“ und zählen in der Übersicht nicht mit.
Bei allen Werkzeugen gilt: Adresse eintragen → das Werkzeug öffnet den Browser → mit dem eigenen
`3cors`-Konto bei Keycloak anmelden → auf der **Zustimmungsseite** zustimmen → zurück ins
Werkzeug. Client-ID und Secret bleiben leer (das Werkzeug registriert sich selbst). Danach
`list_workspaces` aufrufen lassen („Welche 3cors-Workspaces kannst du lesen?“) — die Antwort
zeigt, ob alles passt. Die Beispiele nutzen dev; für prod die prod-Adresse einsetzen.
> **Stand der Prüfung:** Adressen, Seitenname, Werkzeugnamen, Zustimmungsseite und Fehlermeldungen
> sind gegen den Code geprüft. Claude Code (2.1.295) und Gemini CLI (0.63) kamen am 2026-10-09
> bis zur Rückkehr aus dem Browser und scheiterten dort an der Aussteller-Prüfung (RFC 9207,
> `iss`); seitdem schaltet das Company Brain `iss` für Werkzeuge mit Rücksprung auf
> `localhost`/`127.0.0.1` ab — dass beide damit durchgehend verbinden, bestätigt Test TC-265.
> Die übrigen Schritte je Werkzeug sind, wo nicht „gemessen“ dabeisteht, aus der Erinnerung
> geschrieben und werden mit TC-265 je Werkzeug bestätigt oder korrigiert.
### claude.ai und Claude Desktop
1. **Settings → Connectors → Add custom connector**, Name `3cors lesen`, URL = Leseadresse.
2. **Connect** → Keycloak-Anmeldung → zustimmen. Die Desktop-App übernimmt den Connector.
### Claude Code
1. `claude mcp add --transport http 3cors-lesen https://brain.hcai42.com/mcp`
2. In Claude Code `/mcp` öffnen, `3cors-lesen` wählen, **Authenticate** → Browser-Anmeldung →
zustimmen. Die Rücksprungadresse ist `http://localhost:<port>/…`.
### Codex CLI
1. In `~/.codex/config.toml` den MCP-Client mit OAuth einschalten (gemessen mit Codex CLI
0.57.0: ohne diese beiden Einträge verweigert `codex mcp login` die Anmeldung):
```toml
experimental_use_rmcp_client = true
[features]
rmcp_client = true
```
2. `codex mcp add 3cors-lesen --url https://brain.hcai42.com/mcp` (oder in derselben Datei
einen Block `[mcp_servers.3cors-lesen]` mit `url = "https://brain.hcai42.com/mcp"`).
3. `codex mcp login 3cors-lesen` → Browser-Anmeldung → zustimmen. Codex registriert sich als
„Codex“ mit Rücksprung auf `http://127.0.0.1:<port>/callback`. Wurde die Registrierung
abgelehnt, weicht Codex auf die Client-ID `mcp-client` aus — die Anmeldung scheitert dann;
erst die beiden Einträge aus Schritt 1 prüfen.
### ChatGPT (Entwicklermodus)
1. **Settings → Apps & Connectors → Advanced settings → Developer mode** einschalten.
2. **Create** (neuer Connector): Name `3cors lesen`, MCP-Server-URL = Leseadresse,
Authentifizierung **OAuth** → anlegen → Keycloak-Anmeldung → zustimmen.
3. Im Chat über **+ → Developer mode** den Connector auswählen.
### Gemini CLI
1. In `~/.gemini/settings.json` unter `mcpServers` eintragen:
`"3cors-lesen": {"httpUrl": "https://brain.hcai42.com/mcp"}`.
2. Gemini CLI in einem **vertrauenswürdigen Ordner** starten (gemessen mit Gemini CLI 0.50.0:
in einem nicht vertrauenswürdigen Ordner sind MCP-Server abgeschaltet — der Server fehlt
dann einfach). Den Ordner beim Start als vertrauenswürdig bestätigen.
3. In Gemini CLI `/mcp auth 3cors-lesen` → Browser-Anmeldung → zustimmen. Der Browser muss auf
demselben Rechner laufen (Rücksprung auf `http://localhost:<port>/oauth/callback`).
### VS Code (Copilot, Agent-Modus)
1. Befehl **MCP: Add Server** → **HTTP** → Leseadresse → Name `3cors-lesen` (oder in
`.vscode/mcp.json`: `"servers": {"3cors-lesen": {"type": "http", "url": "https://brain.hcai42.com/mcp"}}`).
2. **Start** → VS Code fragt nach der Anmeldung → Browser → zustimmen.
### Cursor
1. **Settings → MCP → Add new MCP server** (oder `~/.cursor/mcp.json`:
`"mcpServers": {"3cors-lesen": {"url": "https://brain.hcai42.com/mcp"}}`).
2. Beim Server auf **Login/Connect** klicken → Browser-Anmeldung → zustimmen.
### Stolperfallen
| Bild | Ursache | Was tun |
|---|---|---|
| Registrierung beim Anmeldedienst schlägt fehl | Keycloak lässt nur Rücksprungadressen auf **`claude.ai`, `chatgpt.com`, `localhost` und `127.0.0.1`** zu (die Liste steht versioniert in `scripts/keycloak/realm/provision-rbac.sh`). Ein Werkzeug, das eine andere Adresse registriert (eigene Web-Domain oder ein eigenes URL-Schema), wird abgelehnt. | Die lokale bzw. Browser-Anmeldung des Werkzeugs wählen; bleibt es, Operator informieren — die Liste wird nur bewusst erweitert. |
| Nach der Anmeldung passiert nichts | Die **Zustimmungsseite** wurde geschlossen statt bestätigt. | Verbindung neu starten und zustimmen. |
| CLI-Werkzeug meldet nach der Browser-Anmeldung einen Fehler zum Aussteller (`iss`) | Das Werkzeug hat sich **vor** der Umstellung im Company Brain registriert; nur neue Registrierungen mit Rücksprung auf `localhost`/`127.0.0.1` bekommen die Antwort ohne `iss`. | Die gespeicherte Anmeldung des Werkzeugs für diesen Server löschen (nicht nur den Server entfernen — manche Werkzeuge behalten ihre Registrierung), dann neu anmelden, damit es sich neu registriert (wird mit TC-265 bestätigt). Bleibt der Fehler, Operator informieren (Log `MCP_OAUTH_DCR_ISS_EXCLUDE_FAILED`). |
| `403 no_linked_identity` | Keycloak-Login passt zu keinem aktiven Plattform-Konto. | Siehe „Voraussetzung“ oben. |
| „Diese Funktion ist gerade abgeschaltet.“ | Externes Lesen ist plattformweit abgeschaltet (Admin-Schalter). | Später erneut versuchen oder den Plattform-Admin fragen. |
| `list_workspaces` ist leer, `found: false`, leere Liste | Kein Workspace mit Freigabe **lesen**, oder du bist dort kein Mitglied. Gesperrt und nicht vorhanden sehen absichtlich gleich aus. | Auf **Externe KI → Meine Verbindungen** nachsehen; den Owner um **lesen** bitten. |
| „3cors CorDoc ist gerade nicht erreichbar, nichts wurde gelesen.“ | CorDoc antwortet gerade nicht. | Später erneut versuchen; bleibt es, Operator informieren. |
| `invalid … ab Stufe 4` | Lesbar sind Dokumente und Spezifikationen; Modelle und Elemente folgen. | Ein Dokument (`type document`, `ukk://…/document/…`) oder eine Spezifikation (`type specification`, `ukk://…/interviewer_specification/…`) lesen. |
| „3cors Interviewer ist gerade nicht erreichbar, nichts wurde gelesen.“ | Der Interviewer antwortet gerade nicht (oder eine Antwort war nicht verwertbar). | Später erneut versuchen; bleibt es, Operator informieren. |
| Ein Dokument hat `text: null` | Für die Version gibt es (noch) keinen Text, z. B. ein Scan ohne Textebene (`text_status`). | In CorDoc ansehen; der Text erscheint, sobald er extrahiert ist. |
Jeder Aufruf steht mit Zeit, Werkzeug, Ziel-Adresse, Ergebnis und Client-Name im **Protokoll** —
nie mit Inhalten, Titeln oder Suchbegriffen.
### Restrisiko lokale Anmeldung
CLI-Werkzeuge melden sich über eine Rücksprungadresse auf `localhost` bzw. `127.0.0.1` an. Einen
solchen Client kann **jeder** registrieren, und zwar unter einem Namen, den er selbst wählt. Die
Keycloak-Zustimmungsseite zeigt genau diesen Namen. Das heißt:
- **Nur zustimmen, wenn du die Anmeldung gerade selbst gestartet hast** — in deinem eigenen
Werkzeug, auf deinem eigenen Rechner. Ein Link, der dir geschickt wird und direkt auf eine
Keycloak-Zustimmungsseite führt, ist **nicht** von dir gestartet: abbrechen.
- Der angezeigte Name beweist nichts. „Claude Code“ auf der Zustimmungsseite kann auch ein
fremder Client sein, der sich so genannt hat.
- Im Zweifel: abbrechen, im Werkzeug neu verbinden und dann zustimmen. Unter **Externe KI →
Meine Verbindungen** siehst du, welche Werkzeuge in deinem Namen gelesen haben.
Die Plattform begrenzt das Risiko: Registrierungen bekommen nur die festgelegten Scopes, die Zahl
der Clients ist gedeckelt, jede Registrierung braucht deine Zustimmung, und ein so erteilter
Zugang liest nur Workspaces, die auf **lesen** stehen.
## 3cors schreiben (Externe KI, Stufe 2)
Über die **Schreibadresse** („3cors schreiben“) legt dein KI-Werkzeug Markdown-Dokumente in
CorDoc ab — in deinem Namen, mit Herkunft. Es löscht und überschreibt nie: eine Änderung ist
immer eine **neue Version**, die alten bleiben. Die Schreibadresse ist ein **eigener Connector**
neben der Leseadresse; sie bietet nur die fünf Schreibwerkzeuge, keine Lesewerkzeuge.
| | dev | prod |
|---|---|---|
| **Schreibadresse** | `https://brainwrite.hcai42.com/mcp` | `https://3cbrainwrite.hcai42.com/mcp` |
**Vorher, einmal je Workspace und Person** (Seite **Externe KI** in der Gateway-Shell):
1. Owner oder Admin stellt den Workspace unter **Workspaces** auf **lesen und schreiben**.
2. Owner oder Admin erteilt dir dort eine **Schreibfreigabe** (1 bis 90 Tage, Standard 30). Sie
wirkt nur für Personen ab der Rolle **editor** und nur, solange der Workspace auf „lesen und
schreiben“ steht; läuft sie in 7 Tagen ab, zeigt die Übersicht einen Hinweis.
3. Unter **Meine Verbindungen** stehen die Schreibadresse (mit Kopier-Schaltfläche) und deine
beschreibbaren Workspaces mit Frist.
**Verbinden** wie bei der Leseadresse (Browser-Anmeldung mit dem `3cors`-Konto, zustimmen), nur
mit der Schreibadresse und einem eigenen Namen, z. B. `3cors schreiben`
(Claude Code: `claude mcp add --transport http 3cors-schreiben https://brainwrite.hcai42.com/mcp`).
**Werkzeuge**:
1. `list_writable_workspaces` — „In welche Workspaces darfst du schreiben?“ Antwort: Workspace,
Name, `ukk://<workspace>` und bis wann die Schreibfreigabe gilt.
2. `save_document` — neues Dokument: `workspace_id`, `title` (1–200 Zeichen), `markdown`
(höchstens 1 MiB), optional `note` (Versionsnotiz) und `derived_from` (bis zu 10 Herkunftsadressen
`ukk://<workspace>/document/<id>[@v<n>]` oder `ukk://<workspace>/corim_instance/<id>` desselben
Workspace). Antwort: `ukk://<workspace>/document/<id>@v1` und der Link zum Dokument in CorDoc.
3. `update_document` — neue Version eines Dokuments: `ukk` (z. B. aus `read_object` über die
Leseadresse), `markdown` (der ganze neue Text), optional `note`. Antwort: `…@v<n>` mit
`previous_version`; derselbe Text noch einmal ergibt keine neue Version (`unchanged`).
4. `create_specification` — neue Spezifikation im 3cors Interviewer (Stufe 3): `workspace_id`,
`title` (1–200 Zeichen), `markdown` (höchstens 1 MiB je Aufruf; eine Spezifikation fasst
insgesamt höchstens 2 MiB), optional `derived_from` (1 bis 10
verschiedene Herkunfts-**Dokumente** `ukk://<workspace>/document/<id>[@v<n>]` **desselben**
Workspace — nur Dokumente, keine Modelle). Antwort: `ukk://<workspace>/interviewer_specification/<id>`,
der Link zur Spezifikation und `status: created`. Jeder Aufruf legt eine NEUE Spezifikation an.
Mit `derived_from` prüft CorDoc die Herkunft zuerst (nichts wird angelegt, wenn eine fehlt),
dann entsteht die Spezifikation, dann schreibt CorDoc die Herkunft; ihre UKO-Seite zeigt die
Dokumente als Quelle.
5. `add_to_specification` — hängt einen Abschnitt **ans Ende** einer Spezifikation: `ukk`
(`ukk://<workspace>/interviewer_specification/<id>`, ohne `@`), `section_title` (1–200
Zeichen), `markdown` (höchstens 1 MiB je Aufruf; alle Abschnitte zusammen höchstens 2 MiB).
Bisheriger Text bleibt unverändert; Antwort `status: appended`.
In CorDoc trägt die Version die Quelle **Externe KI** und das Zeichen „über <Werkzeug> · <Person>“;
sie wird auf das Speicherkontingent der Person gebucht, die geschrieben hat. Eine Spezifikation
steht im Interviewer mit dem Verlaufseintrag „über <Werkzeug> · <Person>“; sie kostet kein
Speicherkontingent.
| Antwort | Bedeutung | Was tun |
|---|---|---|
| „keine_schreibfreigabe: Du hast in diesem Workspace keine Schreibfreigabe. Owner oder Admin können sie unter Externe KI erteilen. …“ | Keine, abgelaufene oder widerrufene Schreibfreigabe, oder deine Rolle ist unter editor. | Owner oder Admin um eine Schreibfreigabe bitten (der Link in der Antwort führt zur Seite). |
| „freigabe_nur_lesen: Dieser Workspace ist für externe KI nur zum Lesen freigegeben. …“ | Der Workspace steht auf **lesen**. | Owner oder Admin bitten, ihn auf „lesen und schreiben“ zu stellen. |
| „not_found: Workspace oder Dokument nicht gefunden.“ | Workspace oder Dokument gibt es nicht, du bist kein Mitglied, der Workspace steht auf **aus**, oder es ist ein CorMed-Dokument — absichtlich nicht unterscheidbar. | Adresse prüfen; `list_writable_workspaces` aufrufen lassen. |
| „derived_from_not_found: Mindestens eine Herkunftsadresse wurde nicht gefunden, nichts wurde gespeichert.“ | Eine Herkunft liegt nicht im Ziel-Workspace oder existiert nicht. | Herkunftsadressen aus demselben Workspace nehmen. |
| „derived_from: nur Dokumente und Modelle“ | Andere Objektarten sind als Herkunft nicht möglich. | Nur `document`- oder `corim_instance`-Adressen angeben. |
| „Speicherkontingent erschöpft.“ | Dein Speicherbudget ist aufgebraucht (EF-4); nichts wurde gespeichert. | Kontingent prüfen oder erhöhen lassen. |
| „Zu viele Schreibaufrufe, bitte kurz warten.“ | Mehr als 30 Schreibaufrufe pro Minute (EF-3). | Eine Minute warten. |
| „Diese Funktion ist gerade abgeschaltet.“ | Schreiben ist plattformweit abgeschaltet (Admin-Schalter, unabhängig vom Lesen) — oder die Schreibadresse ist falsch eingerichtet (EF-2). | Später erneut versuchen oder den Plattform-Admin fragen; Lesen über die Leseadresse geht weiter. |
| „3cors CorDoc ist gerade nicht erreichbar, nichts wurde gespeichert.“ | Die Anfrage hat CorDoc nicht erreicht (keine Verbindung innerhalb von 5 Sekunden), oder CorDoc meldet selbst eine Störung (EF-1) — sicher nichts gespeichert. | Später erneut versuchen; bleibt es, Operator informieren. |
| „Keine rechtzeitige Antwort von 3cors CorDoc. Ob gespeichert wurde, ist unklar - prüfe mit list_objects, bevor du erneut speicherst.“ | Die Anfrage ging an CorDoc, aber keine gültige Antwort kam rechtzeitig (innerhalb von 30 Sekunden) zurück — CorDoc kann das Dokument oder die Version trotzdem gespeichert haben. | Mit `list_objects` nachsehen, ob es schon da ist; nur wenn nicht, erneut speichern (sonst entsteht ein Duplikat). |
| „derived_from_incomplete: Dokument angelegt, Herkunft nicht vollständig gespeichert: ukk://…“ | Das Dokument ist gespeichert, aber nicht jede Herkunft. | Das Dokument nicht noch einmal anlegen; Operator informieren. |
| „stored_unsettled: Dokument gespeichert, Abrechnung steht noch aus: ukk://…@v<n>“ | Das Dokument bzw. die Version ist gespeichert (die Adresse nennt sie); nur die Buchung auf das Speicherkontingent ist noch nicht abgeschlossen. | Nicht erneut speichern (sonst entsteht ein Duplikat); mit der genannten Adresse weiterarbeiten. Wiederholt es sich, Operator informieren. |
| „not_found: Workspace oder Spezifikation nicht gefunden.“ | Spezifikation oder Workspace gibt es nicht, du bist kein Mitglied, oder die Spezifikation gehört einer anderen Person ohne Workspace — absichtlich nicht unterscheidbar. | Adresse prüfen; mit `list_objects` (`type specification`) nachsehen. |
| „no_workspace: Diese Spezifikation gehört zu keinem Workspace und kann nicht ergänzt werden, nichts wurde geändert.“ | Die Spezifikation liegt außerhalb jedes Workspace (nur persönlich). | Sie im Interviewer einem Workspace zuordnen, dann erneut. |
| „conflict: Die Spezifikation wurde gleichzeitig geändert, nichts wurde gespeichert. Bitte erneut versuchen.“ | Jemand hat die Spezifikation im selben Moment geändert (zweimal in Folge). | Den Aufruf wiederholen. |
| „derived_from: nur Dokumente desselben Workspace“ / „derived_from_invalid: höchstens 10 verschiedene Adressen ukk://<workspace>/document/<id>[@v<n>] desselben Workspace“ | Die Herkunft einer Spezifikation sind nur Dokumente des Ziel-Workspace (keine Modelle, kein anderer Workspace, keine Dubletten). | Nur `document`-Adressen desselben Workspace angeben. |
| „ukk_invalid: erwartet ukk://<workspace>/interviewer_specification/<id>“ | `add_to_specification` bekam keine Spezifikations-Adresse (Dokument-Adresse, `@`-Zusatz, Tippfehler). | Die Adresse aus der Antwort von `create_specification` oder aus `list_objects` (`type specification`) nehmen, ohne `@`. |
| „section_title_invalid: 1 bis 200 druckbare Zeichen“ | Die Überschrift des Abschnitts ist leer, zu lang, mehrzeilig oder besteht nur aus `#`. | Eine einzeilige Überschrift mit Text angeben. |
| „markdown_invalid: Der Text ist zu groß oder leer: höchstens 1 MiB je Aufruf, die Spezifikation insgesamt höchstens 2 MiB. Nichts wurde gespeichert.“ | Der Interviewer hat den Text abgelehnt: ein Aufruf trägt höchstens 1 MiB, und alle Abschnitte einer Spezifikation zusammen höchstens 2 MiB — der neue Abschnitt hätte diese Grenze überschritten (oder der Text war leer). | Text kürzen oder aufteilen; ist die Spezifikation voll, eine neue anlegen (`create_specification`, mit `derived_from` auf die Quellen). |
| „workspace_id_invalid“ / „title_invalid“ / „section_title_invalid“ + „: von 3cors Interviewer abgelehnt, nichts wurde gespeichert.“ | Der Interviewer hat ein Feld abgelehnt, das die Brain-Prüfung noch durchgelassen hat. | Das genannte Feld prüfen (Workspace-UUID, Titel/Überschrift 1–200 druckbare Zeichen). |
| „derived_from_incomplete: Spezifikation angelegt, Herkunft nicht vollständig gespeichert: ukk://…“ | Die Spezifikation ist angelegt (die Adresse nennt sie), aber nicht jede Herkunft wurde in CorDoc gespeichert. | Die Spezifikation NICHT noch einmal anlegen; Operator informieren. |
| „3cors Interviewer ist gerade nicht erreichbar, nichts wurde gespeichert.“ | Die Anfrage hat den Interviewer nicht erreicht, oder er meldet selbst eine Störung — sicher nichts gespeichert. | Später erneut versuchen; bleibt es, Operator informieren. |
| „Keine rechtzeitige Antwort von 3cors Interviewer. Ob gespeichert wurde, ist unklar - prüfe mit list_objects, bevor du erneut speicherst.“ | Die Anfrage ging an den Interviewer, aber keine gültige Antwort kam rechtzeitig zurück — die Spezifikation oder der Abschnitt kann trotzdem gespeichert sein. | Mit `list_objects` (`type specification`) bzw. `read_object` nachsehen; nur wenn nichts da ist, erneut speichern. |
Jeder Schreibaufruf steht mit Zeit, Werkzeug, Ziel-Adresse, Ergebnis und Client-Name im
**Protokoll** (Verbindung „schreiben“) — nie mit Titel, Text oder Notiz.
## Fehlerbilder
| Antwort | Bedeutung | Was tun |
|---|---|---|
| `401 {"error": "unauthorized"}` + `WWW-Authenticate` mit `resource_metadata` | Kein, abgelaufenes oder fremdes Token (falsche Audience, falscher Issuer, falscher Token-Typ, alter `cbt_`-Token). | Connector neu verbinden. Tritt es sofort nach dem Login auf, fehlt der Audience-Scope in Keycloak — Operator informieren (`docs/KEYCLOAK-SETUP.md`). |
| `403 {"error": "no_linked_identity"}` | Login gültig, aber kein Plattform-Konto zuordenbar — **oder** das verknüpfte/per E-Mail gefundene Konto ist gesperrt oder gelöscht. | Einmal per Keycloak an der Plattform anmelden (verknüpft die Identität) oder die E-Mail im Plattform-Konto bestätigen. Bei einer Sperre: Operator fragen, ob sie beabsichtigt ist — sie wirkt hier innerhalb von höchstens 300 Sekunden. |
| `421 Misdirected Request` | Host-Header nicht zugelassen (Schutz gegen DNS-Rebinding). | Genau die URL aus der Tabelle oben verwenden, keine IP und keinen anderen Namen. |
| `429 {"error": "rate_limited"}` + `Retry-After` | Zu viele Anfragen: `/mcp` 60 pro Minute je IP und 120 pro Minute je Nutzer, `/token` + `/register` 10 pro Minute je IP. | So viele Sekunden warten, wie `Retry-After` angibt. |
| Claude: „Registrierung beim Anmeldedienst … fehlgeschlagen" (Referenz `ofid_…`) | Die Dynamic Client Registration wurde von Keycloak abgelehnt. Bekannter Fall (2026-09-25, behoben): Claude schickt `scope: openid …`; Keycloaks Registrierungs-Policy kennt `openid` nicht als Client-Scope, und mit einer expliziten Scope-Liste haengt Keycloak dem neuen Client keine Realm-Default-Scopes an (kein `company-brain-audience` ⇒ Token ohne `aud` ⇒ „Autorisierung fehlgeschlagen"). Der Dienst entfernt das `scope`-Feld seither vor dem Weiterreichen. | Connector entfernen und neu anlegen (Claude registriert sich frisch). Bleibt es: Operator prüft `docker logs 3cors-keycloak` auf `CLIENT_REGISTER_ERROR` (Policy „Allowed Client Scopes" / „Trusted Hosts"). Notlösung: eine vom Operator vorregistrierte OAuth-Client-ID in den Connector-Einstellungen eintragen. |
| `503 {"error": "unavailable"}` | Der Dienst hat den Keycloak-Discovery-Endpunkt noch nicht geladen oder `COMPANY_BRAIN_PUBLIC_URL`/`COMPANY_BRAIN_OAUTH_ISSUER` fehlt (`/health` zeigt `checks.oauth` als `oauth_not_configured` oder `oauth_metadata_unavailable`). | Kurz erneut versuchen (Retry alle 30 s intern); bleibt es bestehen, Operator informieren. |
| Verbunden, aber leere Treffer | Der Korpus deines Workspace ist leer oder du bist in keinem ingestierten Workspace Mitglied. | Auf der Company-Brain-Seite in der Gateway-Shell nachsehen, welche Workspaces überhaupt einen Korpus haben ("Was ich sehe"). Fehlt deiner in der Liste: über den Mitgliedschafts-Link dort (oder den Operator) eine Mitgliedschaft anfragen, sonst Operator nach dem Korpus-Stand fragen (unten). |
Weitere Hinweise: Clients cachen die Tool-Liste nach dem Verbinden. Nach einer Änderung am Dienst
den Connector neu verbinden, um eine frische `tools/list` zu bekommen.
## Korpus-Pflege (Operator)
Der Korpus wird per One-Shot-Job geladen, nie beim Deploy. Der Job ersetzt pro Workspace und
Quelle den ganzen Stand in einer Transaktion; gelöschte Dateien werden als gelöscht markiert.
- **dev:** aus dem **Primary-Checkout** (nicht aus einem Worktree, dessen `.git` außerhalb des
Mounts liegt) den Ingest-Service des Compose-Projekts `3cors-company-brain` mit Profil `ingest`
starten. Befehl und Optionen: `3cors-company-brain/SERVICE.md`, Abschnitt „Ingest".
- **prod:** derselbe Job aus `/opt/3cors` (`HOST_PROJECT_DIR=/opt/3cors`), mit den Prod-Compose-Dateien
und dem Ziel-Workspace aus der verschlüsselten Prod-Umgebung. Nur mit Freigabe des Owners
(Rule 36).
- Zugriffsbeschränkte Dokumente tragen im Frontmatter `company_brain_acl: [<email>, …]`. Eine
E-Mail ohne Plattform-Konto überspringt die Datei (fail-closed).
## Google Chat und Gmail live anbinden (Owner)
Seit Slice 1.E (Teil A) liest der Worker `company-brain-sync` laufend mit — alle 5 Minuten:
- **Google Chat:** neue Threads aus Spaces, in denen die Chat-App **CorA** Mitglied ist **und**
die der Owner registriert hat. Lesen darf einen Thread nur, wer Mitglied des Space ist; hat ein
Mitglied kein Plattform-Konto, wird der Space nicht eingelesen (fail-closed). Es gibt keine
Historie: gelesen wird ab dem Zeitpunkt der Registrierung.
- **Gmail:** jede Mail im Postfach des Owners, die das Label **`brain`** traegt — je Mail ein
Dokument. Lesen duerfen nur die **internen** Beteiligten (Absender, Empfaenger, Cc) und der Owner;
externe Adressen bekommen nie Zugriff. Label entfernen = Mail verschwindet beim naechsten Lauf
wieder aus dem Brain.
### Einmalige Voraussetzungen
Alle Schritte macht der Owner; Werte gehoeren ausschliesslich in die verschluesselte Umgebung
(SOPS), nie in ein Dokument, einen Chat oder ein Ticket.
1. **Google-Workspace-Konto** (kein privates Gmail) mit Admin-Rechten — Chat-API und
Directory gibt es nur in Workspace.
2. **Admin-Freigabe** im Google-Workspace-Admin fuer den App-Scope
`chat.app.messages.readonly`. Ohne sie liest der Worker keine einzige Chat-Nachricht.
3. **GCP-Projekt:** Chat API, Gmail API und Admin SDK API aktivieren; OAuth-Consent-Screen auf
**Internal** stellen (dann braucht `gmail.readonly` keinen Google-Review).
4. **Chat-App** in der Chat-API-Konfiguration anlegen (Name „CorA") und einen
**Service-Account-Key** fuer sie erzeugen. Fuer die Antworten im Chat (Abschnitt „CorA im
Space") zusaetzlich die Verbindung einstellen — siehe dort.
5. **OAuth-Client** vom Typ **Desktop** anlegen (Client-ID + Secret).
6. In SOPS eintragen: `COMPANY_BRAIN_GOOGLE_CLIENT_ID`, `COMPANY_BRAIN_GOOGLE_CLIENT_SECRET`,
`COMPANY_BRAIN_CHAT_APP_SA_JSON`, `COMPANY_BRAIN_LIVE_WORKSPACE_ID` (Ziel-Workspace, vorher per
SQL bestaetigen), `COMPANY_BRAIN_SYNC_BILLING_USER_ID` (wer die Anreicherung bezahlt) und
`COMPANY_BRAIN_INTERNAL_DOMAINS` (eigene Mail-Domains, Komma-Liste — leer heisst: jede Mail
sieht nur der Owner). Danach den Worker-Container **neu erzeugen** (nicht nur neu starten),
damit er die Werte wirklich hat.
7. **Einmaliger Consent** im Worker-Container, headless:
`python -m app.google_consent --paste` (per `docker exec -it`). Die angezeigte URL oeffnen,
zustimmen, die URL der Weiterleitungsseite zurueckkopieren (die Seite selbst darf leer bleiben).
Die Ausgabe ist **nur** der Refresh-Token — direkt als `COMPANY_BRAIN_GOOGLE_REFRESH_TOKEN` in
SOPS, nirgendwo sonst hin. Danach den Worker erneut neu erzeugen.
8. **CorA in einen Space holen** — ist der Event-Endpoint eingerichtet (Abschnitt „CorA im
Space"), registriert sich der Space dabei selbst im Live-Workspace. Ohne Endpoint von Hand:
`python -m app.sync chat-space add spaces/<id> --workspace-id <uuid>`.
9. **Pruefen:** `python -m app.google_consent --check` — jede Zeile `PASS` (schlaegt fehl, solange
CorA in keinem Space ist). Dann eine Test-Mail mit `brain` labeln und nach dem naechsten Lauf per
`search` suchen.
Solange Schritt 6/7 fehlen, meldet der Worker `unconfigured` und ruft Google gar nicht auf.
### Space hinzufuegen, entfernen, Historie
- Hinzufuegen: CorA in den Space holen. Mit eingerichtetem Event-Endpoint genuegt das; sonst
zusaetzlich `chat-space add` (auch fuer einen anderen Workspace als den Live-Workspace).
- Entfernen (Einwilligung widerrufen): CorA aus dem Space entfernen — mit Event-Endpoint wird
der Space sofort deaktiviert — oder `python -m app.sync chat-space remove spaces/<id>`; der
naechste Lauf markiert alle Dokumente des Space als geloescht.
- Aeltere Nachrichten nur auf ausdrueckliche Anweisung des Owners:
`python -m app.sync chat-space backfill spaces/<id> --since <datum>` (kostet Anreicherung).
- Befehle, Zustaende und Diagnose: `3cors-company-brain/SERVICE.md`, Abschnitt „Live sync".
### Bekannte Grenzen
- Nachtraeglich bearbeitete oder geloeschte Chat-Nachrichten werden nur innerhalb der letzten
14 Tage erkannt.
- Im Chat-Verlauf kann statt des Namens eine Kennung `users/<id>` stehen.
- Die Anmeldung beim Dienst bleibt unveraendert (Keycloak, siehe oben); fuer Chat und Mail braucht
kein Teammitglied einen eigenen Schritt.
- CorA (Workspace-Add-on) antwortet ohne Zwischenmeldung: die Antwort erscheint nach einigen
Sekunden als neue Nachricht im Hauptverlauf des Space (nicht eingeklappt im Thread der Frage).
## CorA im Space (Fragen im Chat)
Seit Slice 1.E Teil B beantwortet CorA Fragen direkt in Google Chat: `@CorA <Frage>` in einem
Space, einer Gruppenunterhaltung oder im Direktchat mit CorA. CorA antwortet nach einigen
Sekunden im Hauptverlauf mit einer Antwort und der Liste der Quellen (Titel + Space bzw.
Betreff).
**Wer was sieht (nicht verhandelbar):**
- **Space und Gruppenunterhaltung:** CorA antwortet NUR aus Dokumenten, die **jedes** aktuelle
menschliche Mitglied lesen darf. Ein Dokument, das nur der Fragende sehen darf, wird hier nie
zitiert — frag dafuer im Direktchat.
- **Direktchat mit CorA:** deine eigenen Rechte, wie bei der Suche in Claude.
- Ist ein Mitglied (oder der Fragende) keinem 3cors-Konto zugeordnet, antwortet CorA mit
„In diesem Space sind Mitglieder ohne 3cors-Konto — ich antworte hier nicht" — ohne Suche,
ohne KI-Aufruf, ohne Kosten. Derselbe Text erscheint, solange ein NEUES Mitglied noch nicht
eingelesen ist (bis zu 5 Minuten nach dem Beitritt); dann einfach erneut fragen.
- Den Direktchat kann nur nutzen, wer in mindestens einem registrierten Space ist (nur daraus
kennt CorA die Zuordnung Google-Konto → 3cors-Konto).
- Mehr als 50 Mitglieder (`COMPANY_BRAIN_CHAT_MAX_MEMBERS`): CorA antwortet nicht.
- Keine Treffer, die alle lesen duerfen: „Dazu habe ich nichts gefunden …" — ebenfalls ohne
KI-Aufruf.
**Kosten:** Jede Antwort wird dem **Fragenden** abgerechnet (Dienst `brain_answer`, App
`company-brain`, im Live-Workspace). Reicht das Guthaben nicht, antwortet CorA „Guthaben reicht
nicht fuer eine Antwort". Wer sehr schnell hintereinander fragt (oder ein Space sehr viele Fragen
stellt), wird kurz gebremst; bei hoher Gesamtlast antwortet CorA „Gerade ausgelastet, bitte gleich
nochmal".
**Woher CorA weiss, wer fragt:** nicht aus dem Ereignis selbst. CorA liest Space-Art, Absender und
Fragetext mit dem eigenen App-Konto bei Google nach (Space, Nachricht, im Direktchat die
Mitgliedschaft). Passt etwas nicht zusammen, kommt die Ablehnung — ohne Suche, ohne Kosten.
**CorA hinzufuegen und entfernen:** CorA in einen Space holen = Einwilligung: CorA begruesst mit
„Ich lese ab jetzt mit …" und liest ab jetzt neue Threads (keine Historie). CorA entfernen =
Einwilligung widerrufen: der Space wird sofort deaktiviert, der naechste Lauf (≤ 5 min) entfernt
seine Dokumente aus dem Brain. Direkt- und Gruppenchats werden nie eingelesen.
### Einrichtung der Verbindung (Owner, einmalig)
In der Google-Cloud-Konsole, Chat API → **Konfiguration** der App „CorA":
1. **Verbindungseinstellungen:** HTTP-Endpoint-URL
`https://brain.hcai42.com/v1/chat/events` (dev) bzw. `https://3cbrain.hcai42.com/v1/chat/events`
(prod) — bei einem Add-on ist genau diese URL die Token-Zielgruppe
(`COMPANY_BRAIN_CHAT_EVENTS_AUDIENCE`).
2. **Projektnummer eintragen (Pflicht, beide App-Typen):** die Nummer des Google-Cloud-Projekts der
App (Konsole → Projekt-Dashboard, „Projektnummer", nur Ziffern) in
`COMPANY_BRAIN_CHAT_PROJECT_NUMBER`. Jedes Token muss an DIESES Projekt gebunden sein. Ohne
Nummer antwortet der Dienst auf echte Google-Ereignisse mit 503 (unsignierte Aufrufe weiter 401).
3. **Authentifizierungs-Zielgruppe — je nach App-Typ:**
- als **Google-Workspace-Add-on** gebaut: nichts umstellen. Google signiert als Service-Agent
des Add-ons (`service-<Projektnummer>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`, in der
Konsole unter den HTTP-Deployments als „Service Account Email"); der Dienst leitet diese
Adresse aus der Projektnummer ab.
- klassische **HTTP-Chat-App**: **„Authentication Audience" auf „Project Number" umstellen.**
Mit „HTTP-Endpoint-URL" signiert Google als `[email protected]` — diesen
Absender teilen ALLE Chat-Apps aller Kunden; jede fremde App, die auf unsere URL zeigt,
bekaeme ein gleich gueltiges Token. Der Dienst lehnt diese Form deshalb mit 401 ab.
Welche Form ankommt, zeigt das Log beim ersten echten Ereignis: EINE Warnung
`CHAT_EVENT_TOKEN_REJECTED reason=... mode=... iss=... aud=... email=...`
(`python scripts/cli.py logs company-brain --since 30m`) — dort stehen Absender und Zielgruppe
(bei „Project Number" die Projektnummer), nie das Token selbst. Optional kann
`COMPANY_BRAIN_CHAT_EVENTS_ISSUER_EMAILS` (Komma-Liste) die zwei erlaubten Absender weiter
EINSCHRAENKEN, nie erweitern; leer = beide. Beide Formen der Ereignisse versteht der Dienst.
4. **Container-Umgebung** (SOPS, danach `company-brain` **neu erzeugen**, nicht nur neu starten):
`COMPANY_BRAIN_CHAT_PROJECT_NUMBER` (Schritt 2),
`COMPANY_BRAIN_LIVE_WORKSPACE_ID` und `COMPANY_BRAIN_CHAT_APP_SA_JSON` (dieselben Werte wie
beim Worker) sowie `LITELLM_MASTER_KEY` / `LITELLM_CONSUMER_KEY_COMPANY_BRAIN` fuer die
abgerechneten Antworten. Das Owner-Token (`COMPANY_BRAIN_GOOGLE_REFRESH_TOKEN`) gehoert NIE in
diesen Container.
Pruefen: ein unsignierter `POST https://brain.hcai42.com/v1/chat/events` muss `401` liefern (nicht
404). Danach im Test-Space `@CorA` fragen.
## Diagnose
- Discovery prüfen: `curl https://brain.hcai42.com/.well-known/oauth-protected-resource/mcp`
(`resource` muss `https://brain.hcai42.com/mcp` sein)
- Health: `curl https://brain.hcai42.com/health`
- Logs: `python scripts/cli.py logs company-brain --since 30m`
- Live-Worker: Container-Health von `3cors-company-brain-sync`; der Grund steht je Lauf in
`docker logs 3cors-company-brain-sync` (`status=unconfigured|healthy|auth_failed`).