Eigen Mesh MCP-Tools-Referenz

Kurz gesagt: Die Memory-Operationen, die dein KI-Assistent über HTTP MCP aufrufen kann — capture, search, edit und delete — mit Argumenten und Antwortformaten.

Alle Tools benötigen Authorization: Bearer <api-key>. Endpoint: https://<your-app-origin>/api/mcp.

HTTP MCP stellt vier Tools bereit. Der In-App-Chat-Agent hat zusätzliche Notes-Tools (create_text_file, search_text_files usw.), die nicht über HTTP MCP verfügbar sind.

Antworten sind JSON. Embedding-Vektoren sind nie in Tool-Ergebnissen enthalten — siehe Embeddings-Grenze.

Für wen das relevant ist

Integratoren, die MCP-Clients anbinden oder Tool-Verträge validieren
Operatoren, die prüfen, welche Daten das Deployment über MCP verlassen

capture_thought

Speichert einen neuen rohen Gedanken. Tier 1 liefert sofort nach dem Persistieren des Texts zurück; die Tier-2-Anreicherung (Klassifizierung, Embedding, Graph-Verknüpfungen) läuft im Hintergrund.

Argument	Typ	Erforderlich	Beschreibung
`raw`	string	Ja	Nicht leerer, getrimmter Gedankentext
`captured_at`	string	Nein	ISO-8601-Zeitpunkt der Erfassung für rückdatierte Erinnerungen
`as_user`	boolean	Nein	Bei `true` wird als Erinnerung des menschlichen Nutzers gespeichert (z. B. wenn er dich gebeten hat, dir das zu merken). Wird es bei MCP-API-Key-Auth weggelassen, wird als agentenerstellt gespeichert
`author`	string	Nein	Optionaler Override des API-Key-Präfixes zur Zuordnung der Urheberschaft

Rückgabe: Teilmenge des Thought-Objekts — id, normalisierter Text, category, Metadaten. Natürlichsprachliche Zusammenfassung des gespeicherten Ergebnisses.

Fehler: 401 bei fehlender Autorisierung; Validierungsfehler, wenn raw leer ist.

retrieve_thoughts

Liest gespeicherte Thoughts. Standardmäßig werden nutzererstellte, offene Erinnerungen zurückgegeben (agentenerstellte sowie abgeschlossene/archivierte werden ausgeschlossen).

Suchmodus (mit query, Default order=relevance): hybride semantische, lexikalische und vorberechnete Graph-Nachbarschaftssuche über offene Thoughts, plus lexikalische Suche über angehängte Textnotizen.

Browse-Modus (ohne query oder mit order=created_at): neueste offene Thoughts zuerst — ersetzt das alte Tool list_thoughts. Paginierung über cursor_created_at + cursor_id.

Argument	Typ	Erforderlich	Beschreibung
`query`	string	Nein	Suchtext. Weglassen, um zuletzt erfasste Thoughts zu durchstöbern
`order`	string	Nein	`relevance` (Default, erfordert `query`) oder `created_at` (neueste zuerst)
`top_k`	number	Nein	Maximale Anzahl Ergebnisse (Default 10)
`threshold`	number	Nein	Filter nach normalisiertem Score im Bereich `[0, 1]`
`mode`	string	Nein	`fast` oder `full`
`detail`	string	Nein	`snippet` oder `full`
`author`	string	Nein	`user` (Default), `agent` oder `all`
`include_agent`	boolean	Nein	Kurzform für `author=all`
`cursor_created_at`	string	Nein	Paginierungs-Cursor (ISO) beim Browsen
`cursor_id`	string	Nein	Paginierungs-Cursor (Thought-UUID) beim Browsen

Rückgabe: Array von Thought-Treffern mit normalizedText, category, score und Metadaten. Query-Embeddings werden in-process nur für die SQL-Distanzberechnung erzeugt — sie werden nicht zurückgegeben.

edit_thought

Natürlichsprachliche Bearbeitung eines bereits committeten Thoughts. Umfasst Textänderungen und Lifecycle-Updates (als erledigt markieren, archivieren, wieder öffnen).

Argument	Typ	Erforderlich	Beschreibung
`thought_id`	string	Ja	UUID des Ziel-Thoughts
`edit_request`	string	Nein	Bearbeitungswunsch in normaler Sprache
`raw_text`	string	Nein	Direkter Textersatz (überspringt die LLM-Verarbeitung)

Rückgabe: { "ok": true, "thought": { ... } } oder ein Hinweis, dass nichts gefunden wurde.

Nebeneffekte: Erneutes Embedding, Aktualisierung des Graph-Knotens, erneuter Abgleich der Relationen, Protokollierung der Aktivität.

delete_thought

Archiviert (soft-remove) einen Thought, der dem Aufrufer gehört. Reversibel — gehört zur selben Familie wie edit „archive" / „nicht relevant".

Argument	Typ	Erforderlich	Beschreibung
`thought_id`	string	Ja	UUID des Ziel-Thoughts

Rückgabe: Erfolgsbestätigung oder Hinweis, dass nichts gefunden wurde.

Fundierte Antworten (kein dediziertes MCP-Tool)

HTTP MCP stellt kein answer_question bereit. Um eine Nutzerfrage aus dem Memory zu beantworten:

Rufe retrieve_thoughts mit der Frage als query auf
Formuliere die Antwort in deinem Client anhand der zurückgegebenen Thought-Texte und Zitate

Die In-App-Chat-UI (/chat) macht das intern über ihre Agent-Tool-Loop.

Beispiel: JSON-RPC-Ablauf

MCP-Clients senden JSON-RPC-2.0-Nachrichten. Konzeptuelles tools/call-Payload:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "capture_thought",
    "arguments": {
      "raw": "Remember: team standups are Tuesdays at 10am."
    }
  }
}

Das exakte Wire-Format folgt der MCP-Streamable-HTTP-Spezifikation; Client-Bibliotheken übernehmen die Serialisierung.

Fehlercodes

HTTP	Bedeutung
401	Fehlender oder ungültiger API-Key
400	Validierungsfehler (leere Query, `top_k` außerhalb des zulässigen Bereichs usw.)
500	Pipeline-Fehler (LLM-Gateway nach Retries nicht erreichbar, DB-Fehler)

LLM-Aufrufe werden genau 3 Mal wiederholt und liefern danach einen expliziten Fehler zurück — kein stiller Fallback.

Troubleshooting

Siehe Troubleshooting — Abschnitt MCP zu 401-Fehlern und leeren Ergebnissen.