Referenz

MCP-Werkzeuge

knowmind stellt elf 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_list_recent

Scope: readseit 0.4.0

Listet die zuletzt angelegten Dokumente und Erinnerungen des Arbeitsbereichs, sortiert nach Anlagedatum absteigend (created_at). Quelle ist der Dokument-Korpus — dieselbe Basis, die der Recall durchsucht. Graph-Entitäten ohne Zeitstempel erscheinen nicht; die Anzahl weicht darum bewusst von knowmind_stats (memories) ab.

Parameter

Name	Typ	Pflicht	Default	Hinweis
k	integer	nein	10	Anzahl der neuesten Einträge (1 bis 50)

Beispiel — Anfrage

json

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

Beispiel — Antwort

json

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "items": [
      {
        "id": "5a3c9f2e-1b7d-4c21-9e0a-8f6d2b3c4e5f",
        "title": "Einarbeitungs-Handbuch v3",
        "status": "indexed",
        "indexed_chunks": 23,
        "created_at": "2026-06-10T07:12:44Z",
        "updated_at": "2026-06-10T07:12:51Z",
        "kind": "document"
      }
    ],
    "count": 1
  }
}

Fehlerfälle

Code	Bedeutung
-32002	Scope read fehlt
401	Bearer-Token fehlt oder ungültig

knowmind_store_memory

Scope: writeseit 0.2.0

Legt eine neue Erinnerung dauerhaft im Arbeitsbereich an: Postgres-Dokument, Vektor-Index und Graph-Knoten. Danach ist der Eintrag per knowmind_recall und knowmind_list_recent auffindbar. Append-only: Einträge gleichen Titels werden NICHT ersetzt — Versionierung übernimmt knowmind_update_fact. Sha-identischer Inhalt wird idempotent erkannt (Antwortfeld unchanged). Für längere Texte mit Upsert-per-Titel ist knowmind_upload_document das richtige Werkzeug.

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": "5a3c9f2e-1b7d-4c21-9e0a-8f6d2b3c4e5f",
    "id": "5a3c9f2e-1b7d-4c21-9e0a-8f6d2b3c4e5f",
    "title": "QM-Schulung Pflicht",
    "status": "indexed",
    "chunks_written": 1,
    "embedding_provider": "fastembed"
  }
}

Fehlerfälle

Code	Bedeutung
-32002	Scope write fehlt
-32603	content_required (content fehlt oder leer), too_large (Inhalt über 1.000.000 Zeichen), ingest_failed (Memory-Service-Fehler — nichts wird vorgetäuscht, der Eintrag bleibt als failed markiert)
401	Bearer-Token fehlt oder ungültig

knowmind_upload_document

Scope: writeseit 0.2.0

Ingestet einen längeren Text dauerhaft als Dokument. knowmind teilt den Text in Abschnitte, erzeugt pro Abschnitt einen Vektor und legt einen Graph-Knoten an. Upsert-per-Titel (Server-Default): existiert bereits ein Dokument gleichen Titels, ersetzt die neue Version die alte — gelöscht wird erst nach erfolgreichem Ingest, die ersetzten IDs stehen in replaced_document_ids.

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": {
    "memory_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "title": "Einarbeitungs-Handbuch v3",
    "status": "indexed",
    "chunks_written": 23,
    "embedding_provider": "fastembed",
    "replaced_document_ids": ["1f2e3d4c-5b6a-4d7c-9e8f-a0b1c2d3e4f5"]
  }
}

Fehlerfälle

Code	Bedeutung
-32002	Scope write fehlt
-32603	content_required (content fehlt oder leer), too_large (Inhalt über 1.000.000 Zeichen), ingest_failed (Memory-Service-Fehler)
401	Bearer-Token fehlt oder ungültig

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_list_recent

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