MCP-Server (Model Context Protocol)¶

Der MCP-Server macht ausgewählte Kamerplanter-Funktionen für externe LLM-Clients (z. B. Claude Desktop, Claude Code, eigene Agenten) nutzbar — über das offene Model Context Protocol (MCP), ein Protokoll, mit dem Sprachmodelle strukturierte "Werkzeuge" (Tools) eines Systems aufrufen können. So kann ein LLM-Client zum Beispiel direkt fragen "Welche Pflanzen muss ich heute gießen?" und bekommt eine strukturierte Antwort aus deinen echten Daten — ohne dass du dafür eine eigene App öffnen musst.

Was ist der MCP-Server?¶

Anders als die generische REST-API spiegelt der MCP-Server keine 1:1-CRUD-Endpunkte, sondern stellt eine kuratierte, semantisch hochstufige Werkzeugpalette bereit: Ein Werkzeug wie get_due_care_tasks kapselt einen kompletten Anwendungsfall und liefert kompaktes, LLM-freundliches JSON zurück — statt dass das LLM mehrere REST-Aufrufe verketten müsste.

Der MCP-Server ist eine ergänzende, rein maschinelle Schnittstelle für externe Clients — er ersetzt nicht den in die Anwendung eingebauten KI-Assistenten, der Kamerplanter-Nutzer:innen direkt in der App bei Wissensfragen und Chat unterstützt. Beide Funktionen sind komplementär: Der KI-Assistent ist intern für App-Nutzer:innen gedacht, der MCP-Server ist die externe Schnittstelle, über die fremde LLM-Clients Kamerplanter als Werkzeug benutzen.

Aktivieren¶

Der MCP-Server ist standardmäßig deaktiviert. Solange MCP_SERVER_ENABLED nicht auf true gesetzt ist, antworten alle /mcp/*-Endpunkte mit 404 Not Found — die Schnittstelle existiert dann faktisch nicht, analog zum Freischalt-Mechanismus des KI-Assistenten. Details zur Umgebungsvariable siehe Umgebungsvariablen — MCP-Server.

Transport & Endpunkte¶

Der MCP-Server läuft im Backend-Prozess mit und stellt seine Werkzeuge über drei Endpunkte unter /api/v1/mcp/ bereit:

Authentifizierung: nur Service Accounts¶

Der MCP-Server akzeptiert ausschließlich API-Keys von Service Accounts (account_type: "service") — niemals ein persönliches Nutzerkonto und niemals ein JWT-Access-Token. Der Key wird als X-API-Key-Header oder als Authorization: Bearer kp_... gesendet und trägt immer das Präfix kp_ (siehe auch Authentifizierung — API-Keys (M2M-Integration)).

POST /api/v1/mcp/tools/get_due_care_tasks
X-API-Key: kp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{"urgency": "actionable"}

Ein separater Endpunkt löst einen rohen Key in seinen Kontext auf — nützlich für einen zukünftigen eigenständigen MCP-Prozess (siehe Statushinweis oben), der den Key nicht selbst validieren kann:

POST /api/v1/auth/service-accounts/validate
Content-Type: application/json

{"api_key": "kp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

Antwort (200):

{
  "service_account_key": "sa-abc123",
  "display_name": "Diagnose-Bot",
  "tenant_key": "t-home",
  "tenant_slug": "home",
  "role": "viewer",
  "mcp_permissions": ["mcp.read"]
}

Ein ungültiger, widerrufener oder nicht-service Key liefert in beiden Fällen denselben generischen 401 Unauthorized — die API verrät nie, ob überhaupt ein gültiger Key mit anderen Eigenschaften existiert.

Service-Account-Key beziehen (aktueller Stand)¶

Damit ein MCP-Client heute einen funktionierenden Key bekommt, sind folgende Zutaten nötig:

1. Ein Nutzerkonto mit account_type: "service" (kein Passwort, kein interaktiver Login) — vom Betreiber der Instanz angelegt.
2. Eine Mandanten-Mitgliedschaft dieses Kontos mit genau der Rolle (viewer/grower/admin), die dem gewünschten Berechtigungsniveau entspricht — ein Service Account ist immer an genau einen Mandanten gebunden.
3. Ein API-Key für dieses Konto, technisch derselbe Mechanismus wie unter Service Accounts & API-Keys — API-Key verwenden beschrieben — da ein Service Account jedoch nie interaktiv angemeldet ist, kann er den Key nicht selbst über den /auth/api-keys-Endpunkt anfordern; auch dieser Schritt läuft heute über den Betreiber.

Berechtigungsmodell: mcp.read / mcp.write / mcp.setup¶

Jedes Werkzeug verlangt genau eine von drei MCP-Berechtigungen. Diese sind nicht separat vergebbar, sondern direkt an die Mandanten-Rolle des Service Accounts gekoppelt — dieselbe Rolle, die auch für menschliche Mitglieder gilt (Mandanten & Gärten):

Ein Aufruf ohne die erforderliche Berechtigung wird mit dem Fehlercode permission.denied abgelehnt und im Audit-Log als status: "denied" festgehalten (siehe Audit-Trail & Datenschutz). mcp.setup ist absichtlich die restriktivste Klasse: Sie steuert Standort-Anlage — Zugriffe, die eine ganze Pflanzendaten-Hierarchie betreffen können — und ist deshalb ausschließlich der Rolle admin vorbehalten.

Werkzeug-Katalog (aktueller Stand)¶

Lese-Werkzeuge (mcp.read)¶

Schreib-Werkzeuge (mcp.write)¶

Setup-Werkzeug (mcp.setup)¶

Jedes Werkzeug prüft die referenzierten Schlüssel (Pflanze, Standort, Bereich, Slot) grundsätzlich gegen den Mandanten des aufrufenden Service Accounts. Ein Fremdschlüssel aus einem anderen Mandanten liefert konsequent not_found — niemals permission.denied — damit kein Werkzeug die Existenz fremder Ressourcen verrät.

Antwortformat¶

Jedes Werkzeug liefert ein kompaktes, LLM-freundliches JSON mit drei Pflichtfeldern:

{
  "summary": "3 Pflanzen müssen heute gegossen werden.",
  "data": { "count": 3, "items": [ /* ... */ ] },
  "links": [
    { "type": "ui", "url": "/t/home/care" },
    { "type": "api", "url": "/api/v1/t/home/care/dashboard" }
  ]
}

summary ist eine Ein-Satz-Zusammenfassung für das LLM, data das strukturierte Ergebnis, links verweisen den Endnutzer auf die passende Stelle in der Oberfläche bzw. der REST-API.

Dry-Run und Idempotenz¶

Jedes Schreibwerkzeug akzeptiert zwei zusätzliche, optionale Argumente:

• dry_run: bool (Standard false) — bei true wird nur der geplante Effekt zurückgeliefert, ohne dass irgendetwas gespeichert wird. Damit kann ein LLM-Client eine geplante Aktion erst dem Menschen zur Bestätigung vorlegen, bevor er sie tatsächlich ausführt.
• idempotency_key: str (optional) — identische Keys desselben Service Accounts, Mandanten und Werkzeugs liefern innerhalb von 24 Stunden das ursprüngliche Ergebnis erneut, statt eine zweite Ressource anzulegen. Das schützt vor Doppel-Aktionen bei LLM-Retries (z. B. wenn eine Netzwerkantwort verloren geht).

Eine Wiederholungs-Antwort ist an "idempotent_replay": true erkennbar:

{
  "summary": "Confirmed 'watering' for plant 'p-42'.",
  "data": { "plant_key": "p-42", "reminder_type": "watering" },
  "dry_run": false,
  "idempotency_key": "confirm-2026-07-12-001",
  "idempotent_replay": true,
  "links": [{ "type": "ui", "url": "/t/home/care" }]
}

Idempotenz-Datensätze werden automatisch nach 24 Stunden gelöscht.

Audit-Trail und Datenschutz¶

Jeder Werkzeug-Aufruf wird protokolliert — unabhängig davon, ob er erfolgreich war, wegen fehlender Berechtigung abgelehnt wurde oder ein dry_run war. Der Eintrag enthält Service Account, Mandant, Werkzeugname, einen SHA-256-Hash der Argumente (niemals Klartext), Antwortgröße, Dauer und Status — nie den API-Key selbst und keine personenbezogenen Freitextinhalte wie Tagebucheinträge.

Ein Service Account kann seinen eigenen Aufrufverlauf über das Werkzeug get_mcp_activity oder direkt per REST einsehen:

GET /api/v1/privacy/mcp-activity
Authorization: Bearer <access_token>

Die Antwort enthält die letzten Einträge (Werkzeugname, Status, Antwortgröße, Dauer, Fehlerklasse, Zeitstempel) — keine Argumente im Klartext. Audit-Einträge werden nach 90 Tagen automatisch entfernt (siehe Datenschutz & DSGVO).

Häufige Fragen¶

Siehe auch¶

• Service Accounts & API-Keys
• Authentifizierung
• KI-Assistent — Benutzerhandbuch
• Umgebungsvariablen — MCP-Server
• Datenschutz & DSGVO
• Fehlerbehandlung
• MCP-Werkzeuge für die Entwicklung (nicht zu verwechseln)