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 unter /api/v1/mcp/ bereit:

Authentifizierung: dein eigener API-Key¶

Der MCP-Server akzeptiert API-Keys — deinen persönlichen ebenso wie den eines Service Accounts. Niemals akzeptiert werden ein JWT-Access-Token oder eine interaktive Sitzung. 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)).

Deinen persönlichen Key erstellst du dir selbst über POST /api/v1/auth/api-keys; du kannst ihn jederzeit einzeln widerrufen, ohne dein Passwort zu ändern.

Du siehst ausschließlich deine eigenen Daten¶

Ein Key gewährt genau die Gärten (Mandanten), in denen sein Konto aktives Mitglied ist — aufgelöst über dieselbe Quelle, auf die auch die normale API zugreift. Über MCP ist dadurch nichts erreichbar, was du nicht auch in der Weboberfläche siehst. Ein Garten, in dem du nicht Mitglied bist, verhält sich exakt so, als gäbe es ihn nicht (not_found) — die Schnittstelle verrät also nicht einmal seine Existenz.

Innerhalb eines Gartens gilt die normale Sichtbarkeit: In einem Gemeinschaftsgarten sehen alle Mitglieder dieselben Pflanzen, in der App wie über MCP.

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

{"urgency": "actionable", "tenant": "mein-garten"}

Mehrere Gärten: der tenant-Parameter¶

Bist du Mitglied in mehreren Gärten, gilt dein Key für alle. Welcher gemeint ist, entscheidest du pro Aufruf über das Argument tenant (den Slug des Gartens). Bei genau einer Mitgliedschaft kannst du es weglassen; bei mehreren ist es Pflicht — der Server rät nicht, sondern fordert dich auf, den Garten zu benennen. Welche Slugs zur Verfügung stehen, verrät dir das Werkzeug list_tenants.

Wichtig ist die Reihenfolge dahinter: Der Server bestimmt erst den Garten und prüft danach, was du dort darfst. Denn deine Rolle kann sich je Garten unterscheiden — im eigenen Garten Admin, im Gemeinschaftsgarten nur Betrachter. Umgekehrt geprüft, hättest du überall die stärkste deiner Rollen.

Key-Kontext auflösen (M2M)¶

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",
  "tenants": [
    {
      "tenant_key": "t-home",
      "tenant_slug": "home",
      "role": "viewer",
      "mcp_permissions": ["mcp.read"]
    }
  ]
}

Dieser Endpunkt ist bewusst auf Service Accounts beschränkt. Ein ungültiger, widerrufener oder persönlicher Key liefert hier denselben generischen 401 Unauthorized — die API verrät nie, ob überhaupt ein gültiger Key mit anderen Eigenschaften existiert. Für den MCP-Server selbst gilt diese Einschränkung nicht: dort funktioniert dein persönlicher Key.

Key beziehen¶

Über die Oberfläche: Kontoeinstellungen → API-Schlüssel → Anlegen. Der Schlüssel wird genau einmal angezeigt — danach ist nur noch sein Hash gespeichert, er lässt sich nicht erneut anzeigen. Kopieren und direkt eintragen. In derselben Tabelle kannst du jeden Schlüssel einzeln widerrufen.

Über die API: POST /api/v1/auth/api-keys mit {"label": "claude-code"}. Der Schlüssel gilt sofort für alle deine Gärten mit genau den Rollen, die du dort hast. Mit tenant_scope begrenzt du ihn beim Anlegen auf einen einzigen Garten, wenn ein Client nur dort arbeiten soll.

Als Service Account — Betreiber-Schritt:

Damit ein maschineller 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.
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.

Client einrichten (Claude Code)¶

Claude Code liest MCP-Server aus einer .mcp.json im Projektverzeichnis (oder aus deiner globalen Konfiguration). Trage den Kamerplanter-Server als HTTP-Server ein:

{
  "mcpServers": {
    "kamerplanter": {
      "type": "http",
      "url": "https://kamerplanter.example.com/api/v1/mcp",
      "headers": {
        "X-API-Key": "kp_dein_persoenlicher_api_key"
      }
    }
  }
}

Für eine lokale Entwicklungsumgebung ist die URL http://localhost:8000/api/v1/mcp.

Vorher prüfen, ob die Verbindung steht¶

Bevor du den Eintrag hinzufügst, lohnt ein direkter Test — er zeigt sofort, ob URL und Key stimmen:

# 1. Handschlag: Antwortet der Server als MCP-Server?
curl -sS -X POST https://kamerplanter.example.com/api/v1/mcp \
  -H "X-API-Key: kp_dein_persoenlicher_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'

# 2. Welche Werkzeuge schaltet mein Key frei?
curl -sS -X POST https://kamerplanter.example.com/api/v1/mcp \
  -H "X-API-Key: kp_dein_persoenlicher_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Ein echter Aufruf: Welche Gärten deckt der Key ab?
curl -sS -X POST https://kamerplanter.example.com/api/v1/mcp \
  -H "X-API-Key: kp_dein_persoenlicher_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_tenants","arguments":{}}}'

Kommt bei Schritt 1 ein 404, ist der MCP-Server auf dieser Instanz nicht freigeschaltet (MCP_SERVER_ENABLED). Ein 401 bedeutet, dass der Key ungültig, widerrufen oder abgelaufen ist.

Danach kannst du im Dialog direkt fragen: "Welche Pflanzen muss ich heute gießen?" — Claude ruft get_due_care_tasks selbst auf. Deckt dein Key mehrere Gärten ab, nenne den gewünschten mit ("…in meinem Balkongarten"), damit das Modell den tenant-Parameter füllen kann.

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

Jedes Werkzeug verlangt genau eine von drei MCP-Berechtigungen. Diese sind nicht separat vergebbar, sondern an die Rolle gekoppelt, die dein Konto in dem gerade angesprochenen Garten hat — 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.

Weil die Rolle je Garten gilt, kann derselbe Key in deinem eigenen Garten schreiben und im Gemeinschaftsgarten, in dem du nur Betrachter bist, dieselbe Aktion verweigert bekommen. Die Werkzeug-Übersicht (GET /mcp/tools) zeigt deshalb alles, was du irgendwo darfst; verbindlich ist die Prüfung beim einzelnen Aufruf.

Werkzeug-Katalog (aktueller Stand)¶

Lese-Werkzeuge (mcp.read)¶

Schreib-Werkzeuge (mcp.write)¶

Setup-Werkzeuge (mcp.setup)¶

Jedes Werkzeug prüft die referenzierten Schlüssel (Pflanze, Standort, Bereich, Slot) grundsätzlich gegen den für diesen Aufruf aufgelösten Mandanten. Ein Fremdschlüssel aus einem anderen Mandanten liefert konsequent not_found — niemals permission.denied — damit kein Werkzeug die Existenz fremder Ressourcen verrät.

Wachstumsphasen und Lebenszyklus¶

Die Phasen-Logik steuert Aufgabenplanung, Düngefenster, Erntebereitschaft und Überwinterung (interne Referenz: REQ-003). Über MCP war davon lange nur list_phase_definitions sichtbar — der Katalog der einzelnen Bausteine. Nicht die Abfolgen, zu denen sie zusammengesetzt sind, nicht welche Abfolge für eine Art gilt, und nicht der Phasenstand einer konkreten Pflanze. Eine gewöhnliche Frage wie „läuft diese Pflanze auf der botanisch richtigen Phasen-Abfolge?" war darüber schlicht nicht zu beantworten.

Acht Werkzeuge schließen diese Lücke. Sechs lesen, zwei schreiben — und jedes Schreib-Werkzeug ist mit dem Lese-Werkzeug gepaart, das seine Verweise auflöst, und dem, das sein Ergebnis wiederfindet:

Warum phase_state mehr sagt als „keine Phase"¶

get_plant liefert für eine Pflanze ohne Phase nur current_phase_key: null. Darin stecken aber drei verschiedene Zustände, die jeweils etwas anderes verlangen:

Wie eine Art zu ihrer Abfolge kommt¶

Ist eine Art nicht ausdrücklich gebunden, leitet Kamerplanter die Abfolge aus ihren botanischen Merkmalen ab. Die Regeln greifen in dieser Reihenfolge; die erste, die passt, gewinnt:

1. Kurztag-Zierpflanzen, die mehrjährig sind → photoperiodischer Zierpflanzen-Zyklus (Weihnachtsstern, Kalanchoe). Die Einschränkung auf Mehrjährige ist Absicht: einjährige Kurztag-Nutzpflanzen sollen ihren Erntezyklus behalten.
2. Monokarpe mehrjährige Aufsitzerpflanzen (Bromelien) → Kindel-Zyklus: Die Mutterpflanze stirbt nach der Blüte, der Nachwuchs führt weiter.
3. CAM-Sukkulenten → Zyklus mit kühl-trockener Winterruhe.
4. Wuchsform: Farne, Zwiebelpflanzen und Palmen bekommen ihren jeweils eigenen Zyklus.
5. Jede weitere mehrjährige Art → immergrüner Blattschmuck-Zyklus (die größte Gruppe im Zimmer).
6. Bekannt ein- oder zweijährig → der einjährige Standardzyklus mit Ernte am Ende.
7. Alles andere → ebenfalls der immergrüne, sich wiederholende Zyklus.

Welche Angaben in diese Entscheidung eingehen — und was passiert, wenn eine davon fehlt — zeigt get_species_info: Es liefert plant_category, photosynthesis_type, growth_habit, indoor_suitable, mature_height_cm und frost_sensitivity. Leere Felder werden weggelassen; ein dünn besetzter Datensatz sieht also auch dünn aus — was selbst schon die Antwort auf „reicht dieser Datensatz für eine verlässliche Zuordnung?" ist.

Eine falsche Zuordnung korrigierst du mit assign_species_phase_sequence; welche Arten sonst noch auf derselben Abfolge sitzen, verrät list_species_by_phase_sequence.

Tagebuch-Analyse: externe Agenten¶

Die fünf *_diary_*-Werkzeuge sind der vollständige technische Vertrag für einen extern betriebenen KI-Agenten, der Tagebuch-Einträge analysiert, die ein Nutzer markiert hat (interne Referenz: REQ-050). Die Endnutzer-Sicht — wie du einen Eintrag markierst und wo du ein Ergebnis liest — steht unter Tagebuch. Dieser Abschnitt beschreibt die Gegenseite: das Rezept eines Agenten, der diese Einträge abholt, bearbeitet und das Ergebnis zurückschreibt.

Der Ablauf¶

1. Ein Nutzer markiert einen Tagebuch-Eintrag in der Weboberfläche — der Eintrag wechselt in den Zustand requested.
2. list_pending_diary_analyses (mcp.read) liefert den Arbeitsvorrat — ohne Freitext und ohne Bilder, damit die Antwort klein bleibt.
3. claim_diary_analysis (mcp.write) beansprucht einen Eintrag exklusiv über ein Lease (Vorgabe 15 Minuten, Obergrenze 60 Minuten) und liefert einen lease_token. Ein zweiter Beanspruchungsversuch auf denselben Eintrag scheitert mit conflict.already_claimed. Läuft das Lease ab, ohne dass ein Ergebnis zurückgeschrieben wurde, erscheint der Eintrag wieder im Arbeitsvorrat.
4. get_diary_entry (mcp.read) liefert Text, Tags, Messwerte, den Umgebungs-Schnappschuss (environment) und den Pflanzenkontext — ohne Bilddaten. Der Schnappschuss steht in einem eigenen Feld neben measurements, nie darin: measurements ist, was ein Mensch getippt hat, environment ist, was ein Gerät gemeldet hat, und jeder Wert trägt source, measured_at und origin (location | site | weather). environment_status sagt, was eine leere Liste bedeutet — no_source („nichts misst diese Pflanze") ist etwas anderes als unavailable („die Messung kam nicht durch").
5. get_diary_entry_photos (mcp.read) liefert die Fotos als Bild-Content-Blöcke, damit ein bildverstehendes Modell sie direkt sieht (siehe Bild-Auslieferung unten).
6. Der Agent ruft das Sprachmodell auf, das der Nutzer selbst betreibt und bezahlt.
7. submit_diary_analysis (mcp.write) schreibt das Ergebnis mit gültigem lease_token zurück und setzt den Zustand auf completed oder failed.

Bild-Auslieferung¶

get_diary_entry_photos ist das einzige Werkzeug der Palette, dessen Nutzdaten nicht vollständig in structuredContent liegen: Die Antwort trägt zusätzlich image-Content-Blöcke (Basis-64, mimeType: image/webp), einen je geliefertem Foto, in derselben Reihenfolge wie im strukturierten photos-Feld.

Ausgeliefert werden ausschließlich die vorhandenen 512- oder 1280-px-WebP-Renditions — niemals das Originalfoto. Renditions tragen keine EXIF-Daten, auch dann nicht, wenn die Instanz STORAGE_STRIP_EXIF=false gesetzt hat; jenes Setting betrifft nur die Originaldatei (siehe Umgebungsvariablen — Object Storage).

Die Gesamt-Nutzlast eines Aufrufs ist über MCP_MAX_IMAGE_PAYLOAD_MB gedeckelt (Vorgabe 4 MB, Base-64-kodiert; siehe Umgebungsvariablen — MCP-Server). Wird sie überschritten, antwortet das Werkzeug mit payload.too_large und benennt die betroffenen Fotos sowie eine kleinere Rendition, mit der der Abruf passen würde — es wird nie still gekürzt. Fehlt eine Rendition noch, erscheint das betroffene Foto in pending mit status: "thumbnail_pending" (Erzeugung angestoßen, später erneut abrufbar) oder status: "unavailable" (wird nie entstehen, z. B. weil der Anhang fehlt) — der Aufruf selbst bleibt in beiden Fällen erfolgreich.

Fehlercodes¶

Jeder Fehler eines der fünf Werkzeuge kommt als Werkzeug-Ergebnis mit isError: true, nie als JSON-RPC-error — derselbe Vertrag wie für die übrige Palette (siehe Fehlerbehandlung). error_code ist maschinenlesbar und stabil, message ist für Menschen gedacht und darf sich ändern.

Was ein Rezept nicht selbst entscheiden muss¶

• Der Vorbehalt (disclaimer) im Ergebnis wird serverseitig gesetzt — ein Agent kann ihn weder weglassen noch abschwächen.
• Ob ein Nutzer überhaupt markieren darf, prüft der Server bei jedem mcp.write-Aufruf serverseitig (Rolle, Autorschaft, Einwilligung diary_ai_analysis, Betriebsmodus) — ein Rezept muss diese Regel nicht nachbilden.
• Ein Eintrag ohne Fotos ist kein Fehlerfall; get_diary_entry_photos liefert dann photos: [] mit nur dem Text-Block.

Einen Eintrag schreiben ist eine andere Aufgabe¶

add_plant_diary_entry (mcp.write) gehört zur allgemeinen Werkzeug-Palette, nicht zu den fünf oben: Damit dokumentiert ein Agent eine Beobachtung — Text, Tags, Messwerte — statt sie zu analysieren. Daraus folgen zwei Grenzen:

• Ein neu geschriebener Eintrag wird nicht zur Analyse eingereiht. Das Markieren bleibt eine Nutzerhandlung; ein Agent kann sich also keine eigene Arbeit erzeugen, und die Einwilligungsprüfung auf dem Markier-Pfad wird nie umgangen.
• Das Werkzeug nimmt keine Foto-Referenzen entgegen. Ein Foto anzuhängen setzt voraus, es selbst hochgeladen zu haben (oder die Rolle Leitung zu tragen), und MCP hat keinen Upload-Weg — Fotos kommen über die Weboberfläche an den Eintrag.

Wiederfinden lässt sich das Geschriebene mit list_diary_entries (mcp.read). Das Werkzeug durchsucht die Einträge des Gartens nach Pflanze, Eintragstyp, Tag, Analyse-Zustand und Zeitraum und liefert je Zeile Titel, Tags und Messwerte — den Freitext aber nicht. Der kommt aus get_diary_entry, einem bewussten Einzelabruf. Eine durchblätterbare Liste aller Beobachtungstexte wäre etwas anderes als das gezielte Lesen eines Eintrags.

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 Kontos, 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 Konto, 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 Konto 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
• Tagebuch — Benutzerhandbuch
• KI-Assistent — Benutzerhandbuch
• Umgebungsvariablen — MCP-Server
• Datenschutz & DSGVO
• Fehlerbehandlung
• MCP-Werkzeuge für die Entwicklung (nicht zu verwechseln)