REST- und MCP-API

Voraussetzungen

• Eine E-Mail-Adresse für das knowmind-Konto
• Ein Zugangsschlüssel im Format kmt_… mit read, zum Ablegen zusätzlich write
• Ein HTTP-Client mit TLS in Ihrer Sprache

Schritte

1. 1

   knowmind-Konto anlegen

   Auf knowmind.de die E-Mail-Adresse eintragen. Sie erhalten einen Anmelde-Link per Mail und melden sich damit an. Ein Passwort gibt es nicht.

   Danach legen Sie Ihren Arbeitsbereich an: Name, Kurzname und Tarif. Der Tarif Privat kostet 0 € und genügt für diese Anleitung; welche Tarife es gibt, steht auf der Preisseite.

   Ergebnis: Der Willkommensschirm steht offen, mit den Wegen „Erst einmal schreiben“ und „Mit meinem KI-Werkzeug verbinden“. Drei Startkarten liegen im Arbeitsbereich bereit.

2. 2

   Zugangsschlüssel erzeugen

   Im Cockpit unter Schlüssel einen Schlüssel anlegen: read genügt zum Suchen, write braucht es zum Ablegen und Verknüpfen. Der Schlüssel wird nur einmal angezeigt.

   Hinweis

   Ein Schlüssel je Anwendung

   Legen Sie für jede Anwendung einen eigenen Schlüssel an. Dann lässt sich einer zurückziehen, ohne dass die anderen stehen bleiben. Im Programm gehört er in eine Umgebungsvariable, nicht in den Quelltext.

   Ergebnis: Ein Schlüssel im Format kmt_… liegt vor.

3. 3

   Endpunkt und Anmeldung

   Alle Anfragen gehen gegen https://knowmind.de, die Anmeldung läuft über die Kopfzeile Authorization: Bearer kmt_…. MCP hat eine einzige Adresse, REST je Aufgabe eine; die vollständige Liste führt die REST-Referenz.

   textkopieren

   MCP:    https://knowmind.de/api/mcp/v1
   REST:   https://knowmind.de/api/memory/recall
           https://knowmind.de/api/documents
           https://knowmind.de/api/karten
           https://knowmind.de/api/stats
   Kopf:   Authorization: Bearer kmt_…

   Die MCP-Adresse antwortet als einmalige JSON-Antwort oder als Ereignisstrom, je nachdem, was Ihr Client in der Kopfzeile Accept verlangt. Ohne besondere Angabe kommt reines JSON; mit Accept: text/event-stream der Strom, den manche Connectoren erwarten.

   Ergebnis: Ein Aufruf mit Ihrem Schlüssel liefert die Werkzeugliste; ohne gültigen Schlüssel antwortet knowmind mit HTTP 401.

   bashkopieren

   curl -s -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. 4

   Erster Aufruf: Werkzeuge, Ablegen, Suchen

   Die Werkzeugliste zeigt, was zur Verfügung steht. Danach legen Sie etwas ab und suchen danach — im frischen Arbeitsbereich kommen sonst die drei Startkarten zurück, gekennzeichnet als Startpunkt ohne belastbaren Treffer.

   bashkopieren

   # Werkzeuge auflisten
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   
   # Ablegen
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0", "id": 2, "method": "tools/call",
       "params": {
         "name": "knowmind_store_memory",
         "arguments": {
           "memory_type": "semantic",
           "title": "Rechnungsweg",
           "content": "Rechnungen gehen an die Zentrale, nie an die Filiale.",
           "source": "handbuch"
         }
       }
     }'
   
   # Suchen
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0", "id": 3, "method": "tools/call",
       "params": {
         "name": "knowmind_recall_memories",
         "arguments": { "query": "Wohin gehen Rechnungen?", "k": 5 }
       }
     }'

   Ergebnis: Jede Antwort ist ein JSON-RPC-Objekt mit result oder error. Der abgelegte Inhalt ist im nächsten Aufruf sofort zu finden.

5. 5

   Dasselbe im Programm

   TypeScript (Node 20 oder neuer):

   tskopieren

   const TOKEN = process.env.KNOWMIND_TOKEN!;
   const MCP = "https://knowmind.de/api/mcp/v1";
   
   async function werkzeug(name: string, args: Record<string, unknown>) {
     const antwort = await fetch(MCP, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${TOKEN}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         jsonrpc: "2.0",
         id: 1,
         method: "tools/call",
         params: { name, arguments: args },
       }),
     });
     if (!antwort.ok) throw new Error(`knowmind: HTTP ${antwort.status}`);
     return antwort.json();
   }
   
   const treffer = await werkzeug("knowmind_recall_memories", {
     query: "Wer hat den Müller-Vertrag verfasst?",
     k: 5,
   });
   console.log(treffer);

   Python:

   pythonkopieren

   import os, requests
   
   TOKEN = os.environ["KNOWMIND_TOKEN"]
   MCP = "https://knowmind.de/api/mcp/v1"
   KOPF = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
   
   def werkzeug(name: str, args: dict) -> dict:
       antwort = requests.post(
           MCP,
           headers=KOPF,
           json={
               "jsonrpc": "2.0",
               "id": 1,
               "method": "tools/call",
               "params": {"name": name, "arguments": args},
           },
           timeout=10,
       )
       antwort.raise_for_status()
       return antwort.json()
   
   print(werkzeug("knowmind_recall_memories", {"query": "DSGVO-Schulung?", "k": 5}))

   Ergebnis: Dieselben Treffer wie über curl, mit dem Schlüssel aus der Umgebungsvariablen.

6. 6

   Fragegrenze einplanen

   Die Fragegrenze gilt für die Werkzeuge, die das Gedächtnis befragen; Ablegen, Verknüpfen und die Auskunft über den Bestand zählen nicht mit. Die beiden Wege melden sie unterschiedlich:

   • REST antwortet mit HTTP 429 und nennt in der Kopfzeile Retry-After die Wartezeit in Sekunden.
   • MCP antwortet mit HTTP 200 und im Inhalt einem error-Feld mit der Kennung -32004 und einem Satz, den das KI-Werkzeug weitergeben kann. Eine Wartelogik am Statuscode greift hier nicht; prüfen Sie das error-Feld.

   Warten Sie die genannte Zeit ab, mit etwas Streuung, und wiederholen Sie höchstens dreimal. Welche Grenzen Ihr Tarif hat, steht unter Grenzwerte.

Welches Werkzeug sich wie anmeldet

• Claude Desktop, Claude.ai, Claude Code und ChatGPT melden sich über Ihr knowmind-Konto an, mit der Freigabe im Browser. Einen Schlüssel legen Sie dafür nicht an.
• Cursor, Gemini CLI, die Kommandozeile und n8n arbeiten mit einem Zugangsschlüssel. Beim Einrichten über den Willkommensschirm erzeugt knowmind ihn mit.
• Eigene Anwendungen senden den Schlüssel bei jedem Aufruf in der Kopfzeile, wie in den Beispielen oben.

Weitere Werkzeuge mit MCP

Wer einen MCP-Server über HTTP mit eigener Kopfzeile aufnehmen kann, kann knowmind anbinden, auch ohne eigene Anleitung — etwa LM Studio oder Continue. Viele dieser Werkzeuge lesen dafür eine JSON-Datei nach diesem Muster:

{
  "mcpServers": {
    "knowmind": {
      "url": "https://knowmind.de/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer kmt_…"
      }
    }
  }
}

Wo die Datei liegt und wie die Felder heißen, steht in der Dokumentation des Werkzeugs. knowmind erhält die Suchanfrage und liefert die Treffer; die übrige Unterhaltung mit dem Modell erhält knowmind nicht. Unterstützt ein Werkzeug nur lokal gestartete Server, dient die Kommandozeile mit knowmind mcp als Vermittlung.

Prüfung des Ergebnisses

Fehlerbehebung