MCP Server (Model Context Protocol)¶

The MCP server exposes selected Kamerplanter capabilities to external LLM clients (e.g. Claude Desktop, Claude Code, custom agents) via the open Model Context Protocol (MCP), a protocol that lets language models call a system's structured "tools". This lets an LLM client ask directly "Which plants do I need to water today?" and get a structured answer from your real data — without opening a separate app.

What is the MCP server?¶

Unlike the generic REST API, the MCP server does not mirror 1:1 CRUD endpoints — it exposes a curated, semantically high-level tool palette. A tool like get_due_care_tasks encapsulates a whole use case and returns compact, LLM-friendly JSON, instead of the LLM having to chain several REST calls together.

The MCP server is a complementary, purely machine-to-machine interface for external clients — it does not replace the AI assistant built into the app, which supports Kamerplanter users directly with knowledge questions and chat. The two are complementary: the AI assistant is internal, for app users; the MCP server is the external interface through which third-party LLM clients use Kamerplanter as a tool.

Enabling¶

The MCP server is disabled by default. As long as MCP_SERVER_ENABLED is not set to true, all /mcp/* endpoints answer 404 Not Found — the interface effectively does not exist, mirroring the AI assistant's own opt-in mechanism. See Environment Variables — MCP Server for details on the variable.

Transport & Endpoints¶

The MCP server runs in-process with the backend and exposes its tools under /api/v1/mcp/:

Authentication: your own API key¶

The MCP server accepts API keys — your personal one just as much as a service account's. What it never accepts is a JWT access token or an interactive session. The key is sent as an X-API-Key header or as Authorization: Bearer kp_... and always carries the kp_ prefix (see also Authentication — API Keys (M2M Integration)).

You create your personal key yourself via POST /api/v1/auth/api-keys and can revoke it individually at any time, without changing your password.

You only ever see your own data¶

A key grants exactly the gardens (tenants) its account is an active member of, resolved from the same source the regular API uses. Nothing is reachable over MCP that you could not see in the web UI. A garden you are not a member of behaves exactly as if it did not exist (not_found) — the interface will not even reveal that it is there.

Inside a garden, normal visibility applies: in a community garden every member sees the same plants, in the app as well as over MCP.

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

{"urgency": "actionable", "tenant": "my-garden"}

Several gardens: the tenant parameter¶

If you are a member of several gardens, your key covers all of them. Which one a call applies to is decided per call through the tenant argument (the garden's slug). With exactly one membership you may omit it; with several it is required — the server does not guess, it asks you to name the garden. The list_tenants tool tells you which slugs are available.

The order behind this matters: the server resolves the garden first and only then checks what you may do there. Your role can differ per garden — admin in your own, viewer in a community garden. Checked the other way round, you would hold your strongest role everywhere.

Resolving a key's context (M2M)¶

A separate endpoint resolves a raw key into its context — useful for a future standalone MCP process (see the status note above) that cannot validate the key itself:

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

{"api_key": "kp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

Response (200):

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

This endpoint is deliberately restricted to service accounts. An invalid, revoked or personal key returns the same generic 401 Unauthorized here — the API never reveals whether a valid key with different properties exists. The MCP server itself carries no such restriction: your personal key works there.

Obtaining a key¶

Through the UI: Account settings → API keys → create. The key is shown exactly once — afterwards only its hash is stored and it cannot be displayed again. Copy it and paste it straight into your client config. The same table lets you revoke any key individually.

Through the API: POST /api/v1/auth/api-keys with {"label": "claude-code"}. The key immediately covers all your gardens with exactly the roles you hold in each. Pass tenant_scope at creation to limit it to a single garden when a client should only work there.

As a service account — operator step:

For an MCP client to obtain a working key today, the following pieces are needed:

1. A user account with account_type: "service" (no password, no interactive login) — created by the instance operator.
2. A tenant membership for that account with exactly the role (viewer/grower/admin) matching the desired permission level.
3. An API key for that account, technically the same mechanism described under Service Accounts & API Keys — Using the API Key — but since a service account is never logged in interactively, it cannot request the key itself via the /auth/api-keys endpoint; this step, too, currently runs through the operator.

Setting up a client (Claude Code)¶

Claude Code reads MCP servers from an .mcp.json in the project directory (or from your global configuration). Add the Kamerplanter server as an HTTP server:

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

For a local development stack the URL is http://localhost:8000/api/v1/mcp.

Check the connection first¶

Before adding the entry, a direct test is worth the minute — it shows immediately whether the URL and key are right:

# 1. Handshake: does the server answer as an MCP server?
curl -sS -X POST https://kamerplanter.example.com/api/v1/mcp \
  -H "X-API-Key: kp_your_personal_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'

# 2. Which tools does my key unlock?
curl -sS -X POST https://kamerplanter.example.com/api/v1/mcp \
  -H "X-API-Key: kp_your_personal_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. A real call: which gardens does the key cover?
curl -sS -X POST https://kamerplanter.example.com/api/v1/mcp \
  -H "X-API-Key: kp_your_personal_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_tenants","arguments":{}}}'

A 404 on step 1 means the MCP server is not enabled on that instance (MCP_SERVER_ENABLED). A 401 means the key is invalid, revoked or expired.

After that you can simply ask in conversation: "Which plants do I need to water today?" — Claude calls get_due_care_tasks itself. If your key covers several gardens, name the one you mean ("…on my balcony") so the model can fill in the tenant parameter.

Permission model: mcp.read / mcp.write / mcp.setup¶

Every tool requires exactly one of three MCP permissions. These are not granted separately — they are bound to the role your account holds in the garden being addressed, the same role used for human members (Tenants & Gardens):

A call without the required permission is rejected with the error code permission.denied and recorded in the audit log as status: "denied" (see Audit Trail & Privacy). mcp.setup is deliberately the most restrictive class: it governs site creation — an action that can affect an entire plant-data hierarchy — and is therefore reserved for the admin role only.

Because the role applies per garden, the same key can write in your own garden and be refused the very same action in a community garden where you are only a viewer. The tool listing (GET /mcp/tools) therefore shows everything you may do somewhere; the binding check is the one made on the individual call.

Tool Catalog (current state)¶

Read tools (mcp.read)¶

Write tools (mcp.write)¶

Setup tools (mcp.setup)¶

Every tool validates referenced keys (plant, site, location, slot) against the tenant resolved for that call. A foreign key from another tenant consistently returns not_found — never permission.denied — so no tool ever discloses the existence of another tenant's resources.

Growth Phases and Lifecycle¶

The phase logic drives task scheduling, feeding windows, harvest readiness and overwintering (internal reference: REQ-003). Over MCP, only list_phase_definitions was visible of it for a long time — the catalogue of individual building blocks. Not the sequences they are assembled into, not which sequence applies to a species, and not the phase state of an actual plant. An ordinary question such as "is this plant running on the botanically correct phase sequence?" simply could not be answered through it.

Eight tools close that gap. Six read, two write — and each write tool is paired with the read tool that resolves its references and the one that surfaces its result:

Why phase_state says more than "no phase"¶

For a plant without a phase, get_plant returns only current_phase_key: null. That conflates three different situations, each of which calls for something different:

How a species gets its sequence¶

If a species is not explicitly bound, Kamerplanter derives the sequence from its botanical attributes. The rules apply in this order; the first one that matches wins:

1. Short-day ornamentals that are perennial → photoperiodic ornamental cycle (poinsettia, Kalanchoe). Restricting this to perennials is deliberate: annual short-day crops must keep their harvest cycle.
2. Monocarpic perennial epiphytes (bromeliads) → offset cycle: the mother plant dies after flowering and its pups continue.
3. CAM succulents → cycle with a cool, dry winter rest.
4. Growth habit: ferns, bulb geophytes and palms each get their own cycle.
5. Any other perennial → evergreen foliage cycle (the largest indoor group).
6. Known annual or biennial → the annual default cycle, ending in a harvest.
7. Anything else → the evergreen, repeating cycle as well.

Which data feeds that decision — and what happens when a field is missing — is what get_species_info shows: it returns plant_category, photosynthesis_type, growth_habit, indoor_suitable, mature_height_cm and frost_sensitivity. Empty fields are omitted, so a sparse record also reads as sparse — which is itself the answer to "is this record complete enough for a reliable assignment?".

You correct a wrong assignment with assign_species_phase_sequence; list_species_by_phase_sequence tells you which other species sit on the same sequence.

Diary Analysis: External Agents¶

The five *_diary_* tools are the complete technical contract for an externally operated AI agent that analyses diary entries a user has marked (internal reference: REQ-050). The end-user view — how you mark an entry and where you read a result — is documented under Diary. This section covers the other side: the recipe of an agent that fetches, works on, and writes back results for these entries.

The flow¶

1. A user marks a diary entry in the web UI — the entry switches to the requested state.
2. list_pending_diary_analyses (mcp.read) returns the work queue — no free text, no images, so the response stays small.
3. claim_diary_analysis (mcp.write) exclusively claims an entry via a lease (default 15 minutes, ceiling 60 minutes) and returns a lease_token. A second claim attempt on the same entry fails with conflict.already_claimed. If the lease expires without a submitted result, the entry reappears in the work queue.
4. get_diary_entry (mcp.read) returns text, tags, measurements, the environment snapshot (environment) and the plant context — without image data. The snapshot lives in its own field next to measurements, never inside it: measurements is what a human typed, environment is what a device reported, and every reading carries source, measured_at and origin (location | site | weather). environment_status says what an empty list means — no_source ("nothing measures this plant") is a different statement from unavailable ("the reading did not get through").
5. get_diary_entry_photos (mcp.read) returns the photos as image content blocks, so an image-capable model sees them directly (see Image delivery below).
6. The agent calls the language model that the user operates and pays for themselves.
7. submit_diary_analysis (mcp.write) writes back the result with a valid lease_token and sets the state to completed or failed.

Image delivery¶

get_diary_entry_photos is the only tool in the palette whose payload is not entirely contained in structuredContent: the response additionally carries image content blocks (Base64, mimeType: image/webp), one per delivered photo, in the same order as the structured photos field.

Only the existing 512 px or 1280 px WebP renditions are ever delivered — never the original photo. Renditions carry no EXIF data, even when the instance has set STORAGE_STRIP_EXIF=false; that setting only affects the original file (see Environment Variables — Object Storage).

The total payload of one call is capped by MCP_MAX_IMAGE_PAYLOAD_MB (default 4 MB, Base64-encoded; see Environment Variables — MCP Server). Exceeding it returns payload.too_large, naming the affected photos and a smaller rendition that would fit — photos are never silently dropped. If a rendition does not exist yet, the affected photo appears in pending with status: "thumbnail_pending" (generation triggered, retry later) or status: "unavailable" (will never exist, e.g. because the attachment record is missing) — the call itself stays successful in both cases.

Error codes¶

Every error from one of the five tools arrives as a tool result with isError: true, never as a JSON-RPC error — the same contract as the rest of the palette (see Error Handling). error_code is machine-readable and stable, message is for humans and may change.

What a recipe does not have to decide itself¶

• The disclaimer in the result is set server-side — an agent can neither omit nor soften it.
• Whether a user may mark an entry at all is checked server-side on every mcp.write call (role, authorship, diary_ai_analysis consent, operating mode) — a recipe does not need to rebuild that rule.
• An entry without photos is not an error case; get_diary_entry_photos then returns photos: [] with only the text block.

Writing an entry is a different job¶

add_plant_diary_entry (mcp.write) belongs to the general tool palette, not to the five above: it lets an agent document an observation — text, tags, measurements — instead of analysing one. Two boundaries follow from that:

• A newly written entry is not queued for analysis. Marking stays a user action, so an agent cannot create work for itself, and the consent gate on the marking path is never bypassed.
• The tool takes no photo references. Attaching a photo requires having uploaded it yourself (or being a garden lead), and MCP has no upload path — photos reach an entry through the web UI.

What was written is found again with list_diary_entries (mcp.read). It browses the garden's entries by plant, entry type, tag, analysis state and date range, and returns title, tags and measurements per row — but not the free text. That comes from get_diary_entry, a deliberate single read: a browsable list of every observation's prose is a different thing from reading one entry on purpose.

Response Format¶

Every tool returns a compact, LLM-friendly JSON payload with three mandatory fields:

{
  "summary": "3 plants need watering today.",
  "data": { "count": 3, "items": [ /* ... */ ] },
  "links": [
    { "type": "ui", "url": "/t/home/care" },
    { "type": "api", "url": "/api/v1/t/home/care/dashboard" }
  ]
}

summary is a one-sentence recap for the LLM, data is the structured result, links point the end user at the relevant place in the UI or the REST API.

Dry Run and Idempotency¶

Every write tool accepts two additional, optional arguments:

• dry_run: bool (default false) — when true, only the planned effect is returned, without persisting anything. This lets an LLM client show a planned action to the human for confirmation before actually executing it.
• idempotency_key: str (optional) — identical keys from the same service account, tenant and tool return the original result again within 24 hours, instead of creating a second resource. This protects against duplicate actions on LLM retries (e.g. when a network response is lost).

A replayed response is recognizable by "idempotent_replay": true:

{
  "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" }]
}

Idempotency records are automatically deleted after 24 hours.

Audit Trail and Privacy¶

Every tool call is logged — whether it succeeded, was denied for lacking permission, or was a dry_run. The entry records the service account, tenant, tool name, a SHA-256 hash of the arguments (never plaintext), response size, duration and status — never the API key itself, and no personal free-text content such as diary entries.

A service account can inspect its own call history via the get_mcp_activity tool or directly over REST:

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

The response contains the most recent entries (tool name, status, response size, duration, error class, timestamp) — no plaintext arguments. Audit entries are automatically removed after 90 days (see Privacy & GDPR).

Frequently Asked Questions¶

See Also¶

• Service Accounts & API Keys
• Authentication
• Diary — User Guide
• AI Assistant — User Guide
• Environment Variables — MCP Server
• Privacy & GDPR
• Error Handling
• MCP Tools for Development (not to be confused)