Wie ein Agent über die sechs MCP-Tools jede Operation findet und aufruft, die wichtigsten Operationen je Bereich und die IDs, die sie liefern und brauchen.
Prinzip
Der MCP-Server hat genau sechs Tools: get_context, search_operations, describe_operations, invoke, read_guide und report_feedback. Alle Fähigkeiten von miovea sind Operationen mit einem Key wie customers.list, einem festen Vertrag (Eingabe und Ausgabe in snake_case) und einer Art: read (lesen), write (ändern), queued_write (Hintergrundauftrag) oder external_write (externer Dienst). external: true im Vertrag kennzeichnet jede Wirkung nach außen, auch E-Mail-Versand an Versicherer und Kunden; requires_confirmation: true heißt, dass die Operation erst nach Bestätigung läuft. Ausgeführt wird jede Operation mit invoke.
Der kürzeste Weg:
get_context einmal je Sitzung. Die essentials darin sind vollständige Verträge und direkt aufrufbar, z. B. , , .
customers.list
preinquiries.get
questionnaires.answers.set
Für alles andere search_operations mit query und include_schema: true; die ersten drei Treffer kommen mit Vertrag.
Fehlende Verträge liefert describe_operations mit operation_keys (bis 20 je Aufruf).
invoke mit operation_key und arguments.
Vor dem ersten Schreiben in einer unbekannten Domäne read_guide mit der Domäne als topic.
Idempotenz. Jede schreibende Operation bekommt in arguments einen eigenen idempotency_key je beabsichtigter Änderung. Nach Netzfehlern oder operation_in_progress denselben Key wiederholen; die Antwort kommt dann mit replayed: true. Für eine neue Änderung einen neuen Key wählen.
Bestätigung. Operationen mit requires_confirmation: true im Vertrag, etwa customers.delete, org.api_keys.revoke, send_packages.send oder threads.reply, antworten zuerst mit confirmation_required und details.preview. Die Vorschau dem Nutzer zeigen und erst nach seiner ausdrücklichen Zustimmung denselben Aufruf mit confirm: true wiederholen.
Hintergrundaufträge. Operationen der Art queued_write (z. B. documents.import.start, questionnaires.prefill.start) liefern eine job_id. Den Stand fragt jobs.get mit job_id ab (queued, running, retrying, succeeded, failed, cancelled, expired); nicht neu starten.
Patch.update- und patch-Operationen ändern nur die genannten Felder; null leert ein Feld. expected_revision aus dem letzten Lesen schützt vor parallelen Änderungen (conflict).
Bündeln.batch.invoke führt bis zu 50 Operationen in einem Aufruf aus; questionnaires.answers.set schreibt bis zu 200 Antworten.
Überblick und Wissensbasis
Operation
Zweck
me.get
Rolle, effektive Rechte und Agenten-Richtlinie des aktuellen Zugangs
dashboard.summary
Startseite ohne Parameter: Kennzahlen (Kunden, offene Vorgänge, davon mit Handlungsbedarf, Dokumente, zu prüfende Dokumente), offene Vorgänge, zuletzt bearbeitete Kunden, fällige Aufgaben, letzte Änderungen
changes.list
Änderungen der Organisation seit einem Stand; since aus next_since übernehmen
wiki.tree
Verzeichnis aller Wiki-Seiten mit path
wiki.get
eine Wiki-Seite als Markdown, z. B. { "path": "fragebogen/live-fragebogen" }
wiki.search
Wissensbasis nach Begriffen durchsuchen, z. B. { "query": "Kundenlink" }; liefert Pfad und Textausschnitt
Kunden
Operation
Zweck
customers.list
Kunden auflisten, zuletzt geändert zuerst; search trifft Name und E-Mail, filters z. B. { "field": "consentStatus", "op": "eq", "value": "granted" }
customers.get
Stammdaten mit revision, Kennzahlen und den Vorgängen des Kunden (cases)
customers.health.get
Dokumente mit Auslesestatus und Krankheitsbilder. Siehe Gesundheitsdaten
customers.create
Kunden anlegen; bei gleichem Namen und Geburtsdatum kommt der bestehende Kunde zurück (matched_existing)
customers.update
Stammdaten, Geschlecht und eigene Felder ändern (Patch)
customers.consent.set
Einwilligung erfassen oder widerrufen, z. B. { "customer_id": "…", "granted": true }; ohne Einwilligung keine Uploads
notes.create, customer_tasks.create
Notiz bzw. Wiedervorlage in der Kundenakte
customers.delete
Kunde endgültig löschen; nur nach Bestätigung (confirm: true)
Vorgänge und Aufgaben
Operation
Zweck
preinquiries.list
Vorgänge auflisten; filterbar nach status, customer_id und case_number. Archivierte nur mit status: "archived". Die Vorgangs-ID steht in id
preinquiries.get
ein Vorgang mit open_tasks, Zielversicherern (targets) und Voten (votes)
preinquiries.create
Vorgang starten, z. B. { "customer_id": "…", "product_scope": "pkv" } (pkv, bu, pkv_bu); ein offener Vorgang derselben Produktlinie wird wiederverwendet
preinquiries.setup.complete
Einrichtung abschließen, der Fragebogen ist danach bereit
preinquiries.archive, preinquiries.reopen
Vorgang abschließen bzw. wieder öffnen
preinquiries.checklist.get
Schritte mit Status und blockierenden Aufgaben
preinquiries.history
Verlauf des Vorgangs mit Akteur (user, agent, api_key, customer, system) und Kanal (app, rest, mcp)
work_items.list
manuelle Aufgaben und Wiedervorlagen; filterbar nach sources, priorities, customer_ids und due (overdue, today, week, none)
tasks.create
eigene Aufgabe anlegen, z. B. { "title": "Antrag prüfen", "customer_id": "…", "priority": "high" }
work_items.complete
Aufgabe oder Wiedervorlage erledigen, mit source und source_id aus work_items.list
Dokumente und Auslese
Operation
Zweck
documents.upload.init
15 Minuten gültige Upload-URL; Datei per HTTP PUT senden, upload aus der Antwort aufbewahren. Die URL nie dem Nutzer zeigen
documents.import.start
Auslese für hochgeladene Krankenakten starten (Hintergrundauftrag); awaiting_blackout heißt: erst über die Schwärzung entscheiden (documents.blackout.queue oder documents.blackout.release, meist durch den Makler in der App)
documents.status
Auslese-, Schwärzungs- und Prüfstatus eines Dokuments
documents.list
Dokumente eines Kunden oder Vorgangs
Diagnosen und Krankheitsbilder
Operation
Zweck
facts.list
Befunde eines Kunden; unassigned_only: true zeigt Befunde ohne Krankheitsbild
facts.create, facts.update, facts.certainty.set
Befunde als Maklereingabe erfassen und pflegen
facts.dismiss, facts.restore
Befunde ausblenden und wiederherstellen
icd.search
Code und Bezeichnung gegen ICD-10-GM abgleichen
conditions.get
Krankheitsbild mit Befund-IDs, Standardangaben und Feldschema (fields)
conditions.compose
Krankheitsbild aus Befunden bilden; Name und Körperbereich schlägt die KI vor
conditions.rename, conditions.details.patch
Bezeichnung, Bereich und Standardangaben ändern (Patch)
Versionsverlauf, Vorschau mit fingerprint, Zurücksetzen mit diesem fingerprint
Details im Guide health (read_guide).
Fragebogen und Kundenlinks
Operation
Zweck
questionnaires.get
Fragebogen lesen: ohne section_key die Sektionsübersicht, mit section_key die sichtbaren Fragen; search, unanswered_only und question_keys filtern sektionsübergreifend
Einige Operationen sind dem Menschen in der App vorbehalten (access: human): API-Keys erzeugen und rotieren, die Agenten-Richtlinie ändern, ein E-Mail-Postfach mit Passwort verbinden, Checkout und Kundenportal der Abrechnung, Einladungslinks einlösen, die Einwilligung zur Produktanalyse. Den Nutzer bitten, das dort zu erledigen. Die Operationen des Kundenlinks (public.*) ruft nur der Kunde über seinen Link auf.
IDs
ID
Woher
customer_id
customers.list (id), oder aus preinquiries.list und preinquiries.get
preinquiry_id
id aus preinquiries.list und preinquiries.get, oder cases[].id aus customers.get. Alle Operationen nennen diese ID in Ein- und Ausgaben preinquiry_id; der eigene Schlüssel eines Objekts heißt immer id
case_number
sprechende Vorgangsnummer wie MV-7K4H-2QX9, als Filter in preinquiries.list
target_id, vote_id
aus preinquiries.get
cluster_id, document_id
conditions[].id bzw. documents[].id aus customers.health.get
fact_id
aus facts.list
job_id
aus Operationen der Art queued_write, für jobs.get
Alle IDs außer case_number sind UUIDs.
Listen und Blättern
Listen-Operationen nehmen limit (1 bis 100, Standard 50) und liefern next_cursor. Ist er nicht null, gibt es weitere Ergebnisse: denselben Aufruf mit cursor: <next_cursor> wiederholen.
Über MCP kommen Listen immer platzsparend als columns und rows, auch mit null oder einer Zeile, dazu next_cursor und has_more. Ist eine Seite zu groß, steht zusätzlich truncated: true mit rows_page, rows_kept und result_hint darin, und next_cursor zeigt auf die erste fehlende Zeile; weiterlesen, solange next_cursor gesetzt ist, statt denselben Aufruf zu wiederholen.
Fehler
Fehler kommen zeilenweise als <code>: <message> mit operation:, hint:, je ungültigem Argument <pfad>: <grund> und request_id:. Alle Codes und was zu tun ist: MCP-Server anbinden.
Ein fremder Datensatz liefert not_found, nicht forbidden. Aus einem not_found darfst du deshalb nicht schließen, dass der Datensatz nicht existiert, sondern nur, dass du ihn in dieser Organisation nicht sehen kannst.
