Technische Dokumentation

BUBU Brain verbinden.

MCP einrichten, den passenden Header erstellen und die Schnittstellen verwenden.

Verbinden

1
Server eintragen
Die Werte in die MCP-Einstellungen deiner Plattform übernehmen.
Name
BUBU BRAIN
Server-URL
https://bubu-brain.com/mcp
Name
```
BUBU BRAIN
```
Server-URL
```
https://bubu-brain.com/mcp
```
2
API-Key einsetzen
Deinen Schlüssel eintragen. Die Headerzeile wird sofort erstellt.
Header (optional)
X-API-Key: DEIN_API_KEY
Ein Header pro Zeile · KEY: Wert
Dein API-Key
Headerzeile für das Header-Feld
```
X-API-Key: DEIN_API_KEY
```
Die erzeugte Zeile vollständig in „Header (optional)“ einfügen. Kein „Bearer “ davor ergänzen.
3
Speichern und verbinden
Server aktivieren und Änderungen speichern. Die Grundregeln darunter einmal in den Agenten-Anweisungen hinterlegen. Danach den Verbindungsstatus abfragen.
Server aktivieren
Änderungen speichern
Frage für deinen Chat
```
Rufe bubu_health am verbundenen BUBU-Brain-MCP-Server auf und zeige mir den Status. Führe keine Schreiboperation aus.
```
Der Aufruf liefert den Betriebsstatus. Eine reine Textbestätigung ohne Tool-Aufruf prüft die Verbindung nicht.

Dein API-Key wird hier ausschließlich lokal verarbeitet. Diese Seite speichert und überträgt ihn nicht.

Zwei getrennte Header-Felder?

Header-Name

X-API-Key

Header-Wert

Im Wert-Feld steht ausschließlich dein API-Key. Die Feldnamen und Speicheraktionen können je nach Plattform anders heißen.

Verbindungsdaten gehören in die MCP-Einstellungen. Arbeitsanweisungen für den Agenten gehören in dessen Anweisungsfeld. Dein API-Key gehört nicht in den Chat.

Persönliche Agenten-Regeln

Kopiere diesen Block einmal in die dauerhaften Agenten-, Projekt- oder Workspace-Anweisungen. So legst du Speichern und Abrufen als Arbeitsweise fest.

BUBU Brain in den Verbindungs- oder Workspace-Einstellungen freigeben.
Den Regelblock kopieren und als dauerhafte Anweisung hinterlegen.
Eine Nachricht speichern lassen und den Originalwortlaut in einem neuen Chat abrufen.

Stellt deine Plattform die BUBU-Brain-Verbindung in neuen Chats automatisch bereit, ist keine erneute manuelle Auswahl nötig. Die Regeln allein aktivieren keine fehlende Verbindung und erteilen keine Tool-Berechtigungen.

Regeln zum Kopieren

Nutze BUBU Brain als Gesprächsgedächtnis in jedem Chat.

• Rufe zu Chatbeginn und bei Rückbezügen den passenden gespeicherten Kontext mit bubu_recall ab.
• Speichere jede zugängliche Nutzernachricht und jede eigene sichtbare Antwort vollständig und wortgetreu mit bubu_ingest_turn. Keine Zusammenfassung und kein Relevanzfilter.
• Vergib eindeutige IDs pro Chat und Beitrag. Behalte sie bei Wiederholungen derselben Speicherung unverändert bei.
• Speichere keine Passwörter, Tokens, API-Keys, leeren Nachrichten oder internen System- und Laufzeitinhalte.
• Trenne abgerufenen Originalwortlaut von deinen Schlussfolgerungen. Erfinde keine Erinnerungen. Zeige bei Verlaufsfragen Quellen und zeitliche Reihenfolge.
• Berichtige gespeicherte Einträge nur nach meiner ausdrücklichen Bestätigung.
• Melde fehlende Tools sowie Abruf- oder Speicherfehler offen. Bestätige eine Speicherung erst nach erfolgreicher Tool-Rückmeldung.

Server-URL und API-Key gehören in die MCP-Verbindungseinstellungen, nicht in diesen Regelblock.

Authentifizierung

MCP und REST verwenden unterschiedliche Authentifizierungsregeln. Für beide Schnittstellen kannst du den API-Key als eigenen X-API-Key-Header senden.

Schnittstelle	Header	Verwendung
`/mcp`	`X-API-Key: DEIN_API_KEY`	API-Key als eigener Header
`/mcp`	`Authorization: Bearer DEIN_API_KEY`	Alternative am MCP-Endpunkt
`/v1/stats`	`X-API-Key: DEIN_API_KEY`	Für /v1/stats erforderlich
`/v1/stats`	`Authorization: Bearer …`	Für /v1/stats nicht verwendbar

Die Bearer-Alternative am MCP-Endpunkt ist keine Anleitung zur Bearer-Authentifizierung von REST /v1. Sende einen Auth-Header passend zur verwendeten Schnittstelle.

MCP-Aufrufe

Sende JSON-RPC-Objekte per HTTPS POST an den MCP-Endpunkt. Verwende Content-Type: application/json und Accept: application/json, text/event-stream.

HTTP-Header

POST /mcp HTTP/1.1
Host: bubu-brain.com
Content-Type: application/json
Accept: application/json, text/event-stream
X-API-Key: DEIN_API_KEY

Verbindung initialisieren

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "bubu-client",
      "version": "1.0"
    }
  }
}

Tools auflisten

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Betriebsstatus abrufen

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "bubu_health",
    "arguments": {}
  }
}

Antwortformat

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "BUBU Brain health: ok"
      }
    ],
    "isError": false
  }
}

isError gehört in das result-Objekt, neben content. Prüfe zusätzlich das error-Feld der JSON-RPC-Antwort; ein HTTP-Status 200 allein bedeutet nicht, dass der Aufruf erfolgreich war.

MCP-Tools

Die folgenden Eingabefelder stammen aus dem MCP-Tool-Katalog. Lade mit tools/list die Schemas für deinen Client.

Alle folgenden Tools werden per POST an https://bubu-brain.com/mcp aufgerufen. Der Tool-Name steht in params.name, seine Eingaben in params.arguments.

API-Key für cURL setzen

export BUBU_API_KEY='DEIN_API_KEY'

Ersetze den Platzhalter durch deinen Schlüssel. Die folgenden cURL-Aufrufe lesen ihn aus BUBU_API_KEY. Der Schlüssel gehört in den HTTP-Header, nicht in arguments.

bubu_health

Betriebsstatus des Memory-Service abrufen.

Liest den Betriebsstatus. arguments bleibt ein leeres Objekt.

Keine Eingabefelder. Verwende arguments: {}.

JSON-RPC-Request

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "bubu_health",
    "arguments": {}
  }
}

Vollständiger cURL-Aufruf

curl --request POST \
  --url https://bubu-brain.com/mcp \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "X-API-Key: $BUBU_API_KEY" \
  --data-binary '{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "bubu_health",
    "arguments": {}
  }
}'

bubu_stats

Sessions und Nachrichten im aktiven Memory-Fenster zählen.

Liest die Statistik. arguments bleibt ein leeres Objekt.

Keine Eingabefelder. Verwende arguments: {}.

JSON-RPC-Request

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "bubu_stats",
    "arguments": {}
  }
}

Vollständiger cURL-Aufruf

curl --request POST \
  --url https://bubu-brain.com/mcp \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "X-API-Key: $BUBU_API_KEY" \
  --data-binary '{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "bubu_stats",
    "arguments": {}
  }
}'

bubu_recall

Gespeicherte Beiträge über eine Keyword-Suche abrufen.

Sucht nach den angegebenen Keywords. limit und offset steuern die Seite; window begrenzt das Zeitfenster. Übernimm für spätere Eintragsaufrufe die id=… aus einem Treffer, nicht seine Listennummer.

Parameter	Typ	Pflicht	Werte / Grenzen
`query`	string	Ja	—
`limit`	integer	Nein	minimum=1; maximum=100
`offset`	integer	Nein	minimum=0; maximum=900
`from`	string	Nein	—
`to`	string	Nein	—
`window`	string	Nein	1h, 1d, 1w, 30d, all

Für die Suche entweder window oder from/to verwenden. Eine Timeline entsteht, indem dein Agent die abgerufenen Beiträge nach ihrem Zeitpunkt ordnet. Erfasst werden dabei die tatsächlich abgerufenen Beiträge.

JSON-RPC-Request

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "bubu_recall",
    "arguments": {
      "query": "Projekt Atlas Budget",
      "limit": 5,
      "offset": 0,
      "window": "30d"
    }
  }
}

Vollständiger cURL-Aufruf

curl --request POST \
  --url https://bubu-brain.com/mcp \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "X-API-Key: $BUBU_API_KEY" \
  --data-binary '{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "bubu_recall",
    "arguments": {
      "query": "Projekt Atlas Budget",
      "limit": 5,
      "offset": 0,
      "window": "30d"
    }
  }
}'

bubu_write

Eine eigenständige Notiz speichern; Gesprächsbeiträge gehören in bubu_ingest_turn.

Schreibt eine eigenständige Notiz. Verwende für Gesprächsbeiträge bubu_ingest_turn. Vergib für einen neuen Schreibvorgang einen eigenen idempotency_key; bei einem Retry desselben Vorgangs bleibt er gleich.

Parameter	Typ	Pflicht	Werte / Grenzen
`content`	string	Ja	—
`type`	string	Nein	—
`sourceId`	string	Nein	—
`idempotency_key`	string	Nein	—

JSON-RPC-Request

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "bubu_write",
    "arguments": {
      "content": "Projekt Atlas: Das Budget beträgt 12.000 EUR.",
      "type": "note",
      "idempotency_key": "atlas-budget-notiz-001"
    }
  }
}

Vollständiger cURL-Aufruf

curl --request POST \
  --url https://bubu-brain.com/mcp \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "X-API-Key: $BUBU_API_KEY" \
  --data-binary '{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "bubu_write",
    "arguments": {
      "content": "Projekt Atlas: Das Budget beträgt 12.000 EUR.",
      "type": "note",
      "idempotency_key": "atlas-budget-notiz-001"
    }
  }
}'

bubu_ingest_turn

Einen Gesprächsbeitrag mit Session- und Turn-ID speichern.

Schreibt einen vollständigen Gesprächsbeitrag. Verwende pro Konversation eine eigene session_id und pro Beitrag eine eigene turn_id. Bei einem Retry bleiben IDs und Inhalt unverändert. Das Beispiel speichert einen einzelnen User-Beitrag.

Parameter	Typ	Pflicht	Werte / Grenzen
`session_id`	string	Ja	—
`turn_id`	string	Ja	—
`role`	string	Ja	user, assistant, system
`content`	string	Ja	—
`timestamp`	string	Nein	—
`project_id`	string	Nein	—

JSON-RPC-Request

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "bubu_ingest_turn",
    "arguments": {
      "session_id": "atlas-gespraech-001",
      "turn_id": "atlas-gespraech-001-user-001",
      "role": "user",
      "content": "Für Projekt Atlas bleibt das Budget bei 12.000 EUR."
    }
  }
}

Vollständiger cURL-Aufruf

curl --request POST \
  --url https://bubu-brain.com/mcp \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "X-API-Key: $BUBU_API_KEY" \
  --data-binary '{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "bubu_ingest_turn",
    "arguments": {
      "session_id": "atlas-gespraech-001",
      "turn_id": "atlas-gespraech-001-user-001",
      "role": "user",
      "content": "Für Projekt Atlas bleibt das Budget bei 12.000 EUR."
    }
  }
}'

bubu_verify

Eine Integritätsprüfung anfordern.

Ohne Eingaben wird der aktuelle Integritätsfingerprint angefordert. Für einen einzelnen Eintrag nutze entry_id; alternativ sessionId zusammen mit timestamp. Die beiden Adressierungsarten nicht kombinieren.

Parameter	Typ	Pflicht	Werte / Grenzen
`entry_id`	string	Nein	—
`sessionId`	string	Nein	—
`timestamp`	string	Nein	—

JSON-RPC-Request

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "bubu_verify",
    "arguments": {}
  }
}

Vollständiger cURL-Aufruf

curl --request POST \
  --url https://bubu-brain.com/mcp \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "X-API-Key: $BUBU_API_KEY" \
  --data-binary '{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "bubu_verify",
    "arguments": {}
  }
}'

bubu_correct

Den Inhalt eines gespeicherten Eintrags berichtigen.

Ändert die ausgelieferte Fassung eines vorhandenen Eintrags. Ersetze <ENTRY_ID> durch die 64-stellige hexadezimale id=… eines Recall-Treffers. Lege den bisherigen und den vollständigen neuen Text vor dem Aufruf zur Bestätigung vor. content ist der vollständige Ersatztext.

Parameter	Typ	Pflicht	Werte / Grenzen
`entry_id`	string	Ja	—
`content`	string	Ja	—
`reason`	string	Nein	—

Vor einer Berichtigung den bisherigen Text, die Entry-ID und den vollständigen Ersatztext zur Bestätigung vorlegen.

JSON-RPC-Request

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "bubu_correct",
    "arguments": {
      "entry_id": "<ENTRY_ID>",
      "content": "Projekt Atlas: Das freigegebene Budget beträgt 13.000 EUR.",
      "reason": "Korrektur der Budgetangabe"
    }
  }
}

Vollständiger cURL-Aufruf

curl --request POST \
  --url https://bubu-brain.com/mcp \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "X-API-Key: $BUBU_API_KEY" \
  --data-binary '{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "bubu_correct",
    "arguments": {
      "entry_id": "<ENTRY_ID>",
      "content": "Projekt Atlas: Das freigegebene Budget beträgt 13.000 EUR.",
      "reason": "Korrektur der Budgetangabe"
    }
  }
}'

bubu_list_consents

Consent und effektive Berechtigungen der Verbindung anzeigen.

Liest die Zustimmungen des KI-Gedächtnisses und die effektiven Rechte der Verbindung. arguments bleibt ein leeres Objekt.

Keine Eingabefelder. Verwende arguments: {}.

JSON-RPC-Request

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "bubu_list_consents",
    "arguments": {}
  }
}

Vollständiger cURL-Aufruf

curl --request POST \
  --url https://bubu-brain.com/mcp \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "X-API-Key: $BUBU_API_KEY" \
  --data-binary '{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "bubu_list_consents",
    "arguments": {}
  }
}'

REST /v1

REST-Aufrufe werden direkt an die jeweilige /v1-Route gesendet. Für die Statistikroute wird X-API-Key benötigt.

Endpunkt	Methode	Authentifizierung	Zweck
`https://bubu-brain.com/v1/health`	GET	Kein Auth-Header erforderlich	Gateway-Status
`https://bubu-brain.com/v1/stats`	GET	`X-API-Key`	Statistik des KI-Gedächtnisses

Statistik abrufen

curl --request GET \
  --url https://bubu-brain.com/v1/stats \
  --header "X-API-Key: $BUBU_API_KEY"

Ein JSON-RPC-Body gehört zum MCP-Endpunkt /mcp. Die hier gezeigten REST-Aufrufe sind GET-Anfragen.

Fehler beheben

Prüfe den HTTP-Status und den Antwortinhalt. Authentifizierungsfehler werden nicht durch unverändertes Wiederholen des Aufrufs behoben.

Antwort	Bedeutung	Nächster Schritt
MCP · HTTP 401 · MISSING_KEY	Kein Schlüssel übergeben	X-API-Key-Header eintragen
MCP · HTTP 200 · JSON-RPC UNAUTHORIZED (-32001)	Übergebene Zugangsdaten abgewiesen	Schlüssel und Headerwert prüfen
REST /v1/stats · HTTP 401 · MISSING_KEY	X-API-Key fehlt; ein Bearer-Header ersetzt ihn hier nicht	X-API-Key-Header eintragen
REST /v1/stats · HTTP 401 · UNAUTHORIZED	Übergebene Zugangsdaten abgewiesen	Schlüssel und Headerwert prüfen

OAuth-Metadaten

Der MCP-Endpunkt veröffentlicht Metadaten für OAuth-fähige Clients. Die API-Key-Einrichtung oben benötigt keinen OAuth-Token in der Headerzeile.

Geschützte Ressourcen-Metadaten

https://bubu-brain.com/.well-known/oauth-protected-resource/mcp

Authorization-Server

https://auth.bubu-brain.com

Eine vorhandene OAuth-Verbindung und ein eigener X-API-Key-Header sind unterschiedliche Konfigurationen. Folge für die OAuth-Einrichtung dem vorgesehenen Ablauf deines Clients.

BUBU Brain verbinden.

Verbinden

Server eintragen

API-Key einsetzen

Speichern und verbinden

Persönliche Agenten-Regeln

Regeln zum Kopieren

Authentifizierung

MCP-Aufrufe

HTTP-Header

Verbindung initialisieren

Tools auflisten

Betriebsstatus abrufen

Antwortformat

MCP-Tools

API-Key für cURL setzen

JSON-RPC-Request

Vollständiger cURL-Aufruf

JSON-RPC-Request

Vollständiger cURL-Aufruf

JSON-RPC-Request

Vollständiger cURL-Aufruf

JSON-RPC-Request

Vollständiger cURL-Aufruf

JSON-RPC-Request

Vollständiger cURL-Aufruf

JSON-RPC-Request

Vollständiger cURL-Aufruf

JSON-RPC-Request

Vollständiger cURL-Aufruf

JSON-RPC-Request

Vollständiger cURL-Aufruf

REST /v1

Statistik abrufen

Fehler beheben

OAuth-Metadaten

Geschützte Ressourcen-Metadaten

Authorization-Server