Referenz

MCP-Werkzeuge

knowmind stellt zehn MCP-Werkzeuge über JSON-RPC 2.0 unter https://knowmind.de/api/mcp/v1 bereit. Diese Referenz dokumentiert jede Signatur, jeden Parameter, das Rückgabe-Schema, ein vollständiges Beispiel und die typischen Fehlerfälle. MCP-Protokoll-Version: 2025-06-18.

Allgemeines

Endpunkt: POST https://knowmind.de/api/mcp/v1
Authentifizierung: Authorization: Bearer kmt_…
Inhalt: JSON-RPC-2.0-Request mit method: "tools/call" und Parametern in params.arguments.
Antwort-Format: JSON-RPC-Response. Bei Accept: text/event-stream liefert der Endpunkt Streamable-HTTP-Frames (SSE) — für native Custom-Connectoren in Claude.ai und ChatGPT.
Scope-Modell: read genügt für Recall- und List-Tools; write für Anlage und Pflege; admin für Tarif-relevante Aktionen. Scopes werden serverseitig pro Tool-Call geprüft.
Tenant-Isolation: Ein Token gehört genau zu einem Arbeitsbereich. Cross-Tenant-Zugriff ist auf Datenbank-Ebene ausgeschlossen.

knowmind.recall

Scope: readseit 0.3.0

Hybrid-Recall gegen den Wissenskorpus Ihres Arbeitsbereichs. Kombiniert Volltext (BM25 mit deutschem Analyzer), Vektor (multilingual-e5-large, 1024 Dimensionen) und Graph-Hops im Wissensgraph. Cross-Encoder-Rerank für die Top-Treffer.

Parameter

Name	Typ	Pflicht	Default	Hinweis
query	string	ja	—	Natürlichsprachliche Frage
k	integer	nein	5	Anzahl Treffer (1 bis 25)
hops	integer	nein	2	Tiefe der Graph-Hops (0 bis 3)

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "knowmind.recall",
    "arguments": {
      "query": "Wer ist Ansprechpartnerin für die Einarbeitung?",
      "k": 5,
      "hops": 2
    }
  }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hits": [
      {
        "memory_id": "memory_einarbeitung_2026_03",
        "title": "Einarbeitungs-Verantwortliche Q2 2026",
        "content": "Anna Müller ist Ansprechpartnerin für die Einarbeitung neuer Service-Mitarbeitender, vertreten durch Tomasz Kowalski.",
        "score": 0.93,
        "source": "internal-handbook-v3"
      }
    ],
    "elapsed_ms": 187
  }
}

Fehlerfälle

Code	Bedeutung
-32602	Invalid params (query fehlt oder leer)
-32000	Service-Token unconfigured oder Provider-Fehler
401	Bearer-Token fehlt oder ungültig
429	Rate-Limit überschritten

knowmind.recall_at_time

Scope: readseit 0.3.0

Punkt-in-Zeit-Recall (bi-temporal). Liefert ausschließlich Erinnerungen, die zum angegebenen Zeitpunkt gültig waren — also valid_from kleiner-gleich as_of und (valid_to größer as_of oder valid_to ungesetzt). Geeignet für die Frage „Was wusste der Wissensspeicher am 14. März?".

Parameter

Name	Typ	Pflicht	Default	Hinweis
query	string	ja	—	Natürlichsprachliche Frage
as_of	string (ISO 8601)	nein	now	Zeitpunkt der Gültigkeit, z. B. 2026-03-14T00:00:00Z
k	integer	nein	5	Anzahl Treffer (1 bis 25)

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "knowmind.recall_at_time",
    "arguments": {
      "query": "Tarif-Stand Müller GmbH",
      "as_of": "2026-03-14T00:00:00Z",
      "k": 3
    }
  }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "hits": [
      {
        "memory_id": "memory_mueller_tarif_v2",
        "title": "Tarif Müller GmbH ab 01.02.2026",
        "content": "Müller GmbH läuft auf Tarif Business mit fünf Plätzen.",
        "valid_from": "2026-02-01T00:00:00Z",
        "valid_to": "2026-04-01T00:00:00Z",
        "score": 0.88
      }
    ]
  }
}

Fehlerfälle

Code	Bedeutung
-32602	Invalid params (query fehlt, as_of nicht ISO 8601)
401	Bearer-Token fehlt oder ungültig

knowmind.list_relations

Scope: readseit 0.3.0

Liefert alle ein- und ausgehenden typisierten Beziehungen einer Erinnerung. Pro Beziehung: Typ, Quell- und Ziel-Knoten, Anlage-Zeitpunkt.

Parameter

Name	Typ	Pflicht	Default	Hinweis
memory_id	string	ja	—	ID der Erinnerung, deren Beziehungen abgefragt werden

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "knowmind.list_relations",
    "arguments": { "memory_id": "memory_workshop_2026_03_12" }
  }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "outgoing": [
      { "rel_type": "FOR_CLIENT", "to": "memory_mueller_kunde" },
      { "rel_type": "REFERENCES", "to": "memory_qm_handbuch" }
    ],
    "incoming": [
      { "rel_type": "SUPERSEDES", "from": "memory_workshop_2026_03_19" }
    ]
  }
}

Fehlerfälle

Code	Bedeutung
-32602	Invalid params (memory_id fehlt)
404	Erinnerung nicht gefunden

knowmind.health

Scope: —seit 0.1.0

Liefert Service-Status. Erreichbar mit jedem Token. Keine Tenant-Daten.

Parameter

Name	Typ	Pflicht	Default	Hinweis
Keine Parameter

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": { "name": "knowmind.health", "arguments": {} }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "status": "ok",
    "service": "memory",
    "version": "0.3.0"
  }
}

Fehlerfälle

Code	Bedeutung
503	Service nicht erreichbar (Memory-Service, Postgres oder Graph)

knowmind.stats

Scope: readseit 0.2.0

Aktuelle Korpus-Statistik für den Arbeitsbereich des Tokens: Anzahl Erinnerungen, Anzahl Beziehungen, Anzahl Chunks im Vektor-Index.

Parameter

Name	Typ	Pflicht	Default	Hinweis
Keine Parameter

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": { "name": "knowmind.stats", "arguments": {} }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "memories": 1219,
    "edges": 5512,
    "chunks": 3214
  }
}

Fehlerfälle

Code	Bedeutung
401	Bearer-Token fehlt oder ungültig

knowmind.store_memory

Scope: writeseit 0.2.0

Legt eine neue Erinnerung im Arbeitsbereich an. Wenn der Inhalt länger als ein einzelner Abschnitt ist, sollten Sie statt dessen knowmind.upload_document verwenden — es erzeugt Chunks und mehrere Vektoren.

Parameter

Name	Typ	Pflicht	Default	Hinweis
title	string	nein	—	Kurz-Titel der Erinnerung
content	string	ja	—	Vollständiger Text
memory_type	string (enum)	nein	semantic	semantic, episodic, procedural, reference
tags	string[]	nein	—	Schlagworte für Filterung
source	string	nein	—	Quelle, frei-text

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "knowmind.store_memory",
    "arguments": {
      "title": "QM-Schulung Pflicht",
      "content": "Alle Service-Mitarbeitenden absolvieren die QM-Schulung jährlich.",
      "memory_type": "procedural",
      "tags": ["qm","schulung"],
      "source": "internal-handbook"
    }
  }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "memory_id": "memory_qm_pflicht_2026_05",
    "created_at": "2026-05-23T11:42:08Z"
  }
}

Fehlerfälle

Code	Bedeutung
-32602	Invalid params (content fehlt, memory_type außerhalb der Enum-Liste)
402	Tarif-Limit erreicht (z. B. 100 Erinnerungen im Privat-Tarif)
403	Scope write fehlt

knowmind.upload_document

Scope: writeseit 0.2.0

Ingestet einen längeren Text als Dokument. knowmind teilt den Text in semantische Abschnitte, erzeugt pro Abschnitt einen Vektor und legt eine Document-Memory mit HAS_CHUNK-Beziehungen an.

Parameter

Name	Typ	Pflicht	Default	Hinweis
title	string	nein	—	Dokument-Titel
content	string	ja	—	Volltext des Dokuments
source	string	nein	—	Quellenangabe (URL, Pfad)

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "knowmind.upload_document",
    "arguments": {
      "title": "Einarbeitungs-Handbuch v3",
      "content": "Kapitel 1 — Onboarding-Ablauf …",
      "source": "internal-handbook-v3.md"
    }
  }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "document_id": "doc_einarbeitung_v3_2026_05",
    "chunks": 23,
    "status": "indexed"
  }
}

Fehlerfälle

Code	Bedeutung
-32602	Invalid params (content fehlt)
402	Tarif-Limit erreicht
413	Inhalt zu groß (> 10 MB)

knowmind.update_fact

Scope: writeseit 0.3.0

Bi-temporales Update einer bestehenden Erinnerung: das Original bekommt valid_to gleich jetzt, eine neue Version mit valid_from gleich jetzt wird angelegt und per SUPERSEDES-Beziehung verknüpft. Damit bleibt die Historie auditierbar — alte Aussagen werden nicht gelöscht, sondern als überholt markiert.

Parameter

Name	Typ	Pflicht	Default	Hinweis
target_id	string	ja	—	ID der zu aktualisierenden Erinnerung
new_title	string	ja	—	Titel der neuen Version
new_content	string	ja	—	Inhalt der neuen Version
update_reason	string	nein	—	Begründung, z. B. „Adresse geändert"

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "knowmind.update_fact",
    "arguments": {
      "target_id": "memory_mueller_adresse_v1",
      "new_title": "Anschrift Müller GmbH ab 01.06.2026",
      "new_content": "Müller GmbH, Industriestraße 7, 32756 Detmold.",
      "update_reason": "Adresse geändert zum 01.06.2026"
    }
  }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "old_memory_id": "memory_mueller_adresse_v1",
    "new_memory_id": "memory_mueller_adresse_v2",
    "supersedes_edge": "edge_supersedes_2026_05_23"
  }
}

Fehlerfälle

Code	Bedeutung
-32602	Invalid params (Pflichtfeld fehlt)
404	target_id nicht gefunden
403	Scope write fehlt

knowmind.link

Scope: writeseit 0.3.0

Legt eine typisierte Beziehung zwischen zwei Erinnerungen an. Inverse-Beziehung wird automatisch materialisiert. Zulässige Edge-Typen siehe Referenz Beziehungstypen.

Parameter

Name	Typ	Pflicht	Default	Hinweis
from_id	string	ja	—	Memory-ID des Quell-Knotens
to_id	string	ja	—	Memory-ID des Ziel-Knotens
rel_type	string	ja	—	Edge-Typ in UPPER_SNAKE_CASE (z. B. OWNS, FOR_CLIENT, SUPERSEDES)

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "knowmind.link",
    "arguments": {
      "from_id": "memory_workshop_2026_03_12",
      "to_id":   "memory_mueller_kunde",
      "rel_type": "FOR_CLIENT"
    }
  }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "edge_id": "edge_for_client_2026_05_23",
    "inverse_edge_id": "edge_has_workshop_2026_05_23"
  }
}

Fehlerfälle

Code	Bedeutung
-32602	Invalid params
400	SHACL-Constraint verletzt (z. B. unzulässiger rel_type für die Domain)
404	from_id oder to_id nicht gefunden

knowmind.unlink

Scope: writeseit 0.3.0

Löscht eine typisierte Beziehung zwischen zwei Erinnerungen. Inverse-Beziehung wird mit gelöscht.

Parameter

Name	Typ	Pflicht	Default	Hinweis
from_id	string	ja	—	Memory-ID des Quell-Knotens
to_id	string	ja	—	Memory-ID des Ziel-Knotens
rel_type	string	ja	—	Edge-Typ

Beispiel — Anfrage

json

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "knowmind.unlink",
    "arguments": {
      "from_id": "memory_workshop_2026_03_12",
      "to_id":   "memory_mueller_kunde",
      "rel_type": "FOR_CLIENT"
    }
  }
}

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": { "deleted": true }
}

Fehlerfälle

Code	Bedeutung
404	Beziehung nicht gefunden

Allgemeines

knowmind.recall

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.recall_at_time

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.list_relations

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.health

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.stats

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.store_memory

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.upload_document

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.update_fact

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.link

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

knowmind.unlink

Parameter

Beispiel — Anfrage

Beispiel — Antwort

Fehlerfälle

Weiterführend