MCP-Server anbinden

Für KI-Agenten: maschinenlesbare Version unter https://app.miovea.com/wiki/erste-schritte/mcp-anbinden.md

miovea stellt einen MCP-Server bereit, über den ein Agent mit denselben Operationen arbeitet wie die App: Kunden, Vorgänge, Dokumente, Krankheitsbilder, Fragebögen, Versand und Voten, lesend und schreibend.

Verbindung

Server-URL: https://app.miovea.com/api/mcp
Transport: Streamable HTTP, zustandslos, MCP-Spezifikation 2026-07-28; ältere Clients (2025er-Protokoll) werden weiter bedient
Anmeldung: OAuth 2.1; Client-Registrierung per Client ID Metadata Document oder Dynamic Client Registration. Beim ersten Verbinden öffnet sich ein Browser-Login mit dem miovea-Konto des Nutzers. Der Consent-Screen fragt die Berechtigung user:org:read ab; dort wählt der Nutzer die Organisation, in der der Agent arbeitet.
Für MCP braucht es keine API-Keys. API-Keys gelten nur für die REST-API.

Beispiel für Claude Code:

claude mcp add --transport http miovea https://app.miovea.com/api/mcp

In claude.ai und Claude Desktop: Einstellungen → Connectors → „Add custom connector“ → Server-URL. In Cursor: Settings → MCP → „Add new MCP server“ → Typ „streamableHttp“ → Server-URL.

Organisation, Rolle und Richtlinie

Alle Daten gehören einer Organisation. Der Agent sieht nur die Organisation, die beim Verbinden gewählt wurde, und handelt mit der Rolle des Nutzers: Admin (org:admin) oder Mitglied (org:member). Einstellungen der Organisation, etwa Vermittlernummern, E-Mail-Vorlagen oder der Plan, ändern nur Admins.
Die Agenten-Richtlinie der Organisation legt fest, ob Agenten schreiben (agent_writes), endgültig löschen (allow_irreversible) und an Versicherer versenden (allow_external) dürfen und welche Bereiche gesperrt sind (blocked_domains). Ändern kann sie nur ein Admin in der App unter Einstellungen, Reiter KI-Zugriff.
Versand durch Agenten läuft im Namen des Standardabsenders der Organisation, den ein Admin im Reiter KI-Zugriff festlegt.
Jede Änderung steht mit dem Kanal „KI-Agent“ im Verlauf.

Verbindungen von vor der Umstellung auf Organisationen müssen einmal neu autorisiert werden. Ohne Organisation im Token antwortet der Server mit organization_required oder unauthorized; der Client startet dann den Login erneut, und der Nutzer wählt im Consent-Screen die Organisation.

`get_context`	einmal je Sitzung: Konto, Organisation, Rolle, Agenten-Richtlinie, `rules`, `start_here` und `essentials` (vollständige Verträge der wichtigsten Operationen, direkt aufrufbar)
`search_operations`	Operationen nach Stichworten suchen; `include_schema: true` liefert die ersten drei Treffer mit Vertrag
`describe_operations`	vollständige Verträge für bis zu 20 Operations-Keys: Eingabe, Ausgabe, Regeln, Beispiele
`invoke`	eine Operation ausführen: `operation_key` und `arguments` nach dem Vertrag (snake_case)
`read_guide`	Guide einer Domäne als Markdown lesen, z. B. `questionnaires`, `dispatch`, `getting_started`; ohne `topic` die Liste
`report_feedback`	fehlende Operationen oder unklare Verträge an das miovea-Team melden

Code	Bedeutung	Was tun
`unauthorized`	Verbindung nicht (mehr) angemeldet	OAuth-Verbindung neu autorisieren
`organization_required`	Token ohne Organisation	neu autorisieren und im Consent-Screen die Organisation wählen
`not_found`	Datensatz existiert nicht oder gehört zu einer anderen Organisation; die Zeile `<pfad>: <grund>` nennt das Argument	ID prüfen, über die passende list-Operation neu suchen
`operation_not_found`	Operations-Key unbekannt	mit `search_operations` den richtigen Key suchen
`validation_error`	Argument passt nicht zum Vertrag; je ungültigem Pfad eine Zeile	Wert korrigieren, Vertrag mit `describe_operations` prüfen
`confirmation_required`	Operation mit `requires_confirmation: true` (nicht umkehrbar oder `external: true`), Vorschau in `details.preview`	Vorschau dem Nutzer zeigen, nach Zustimmung mit `confirm: true` wiederholen
`conflict`	Zustand lässt die Aktion nicht zu, z. B. Vorgang archiviert oder `expected_revision` veraltet	neu lesen, Zustand prüfen
`forbidden`	Rolle reicht nicht, z. B. Mitglied statt Admin	Nutzer informieren, nicht wiederholen
`policy_denied`	Agenten-Richtlinie sperrt die Aktion, Regel in `details.rule`	Nutzer bitten, die Aktion in der App auszuführen
`billing_quota_exceeded`, `billing_feature_required`, `subscription_required`	Kontingent ausgeschöpft, Funktion nicht im Tarif oder kein aktives Abo	Nutzer informieren
`idempotency_conflict`	derselbe `idempotency_key` mit anderen Argumenten	für eine neue Änderung einen neuen Key wählen
`operation_in_progress`	dieselbe Anfrage läuft noch	kurz warten, mit demselben `idempotency_key` wiederholen
`rate_limited`	mehr als 300 lesende oder 60 schreibende Aufrufe pro Minute je Verbindung	kurz warten, dann wiederholen
`internal_error`, `upstream_failed`, `upstream_unavailable`	Fehler im Dienst oder bei einem externen Anbieter	einmal mit demselben `idempotency_key` wiederholen, sonst `report_feedback`

MCP-Server anbinden

Verbindung

Organisation, Rolle und Richtlinie

Die sechs Tools

Fehlerformat

Fehlercodes