MCP-Server

LandNutzen stellt seine Funktion „Adresse → Nutzungspotenzial-Report" auch als MCP-Server bereit, damit KI-Agenten sie per Tool-Discovery nutzen können (AI-Parität, ADR-0018). Der Server ist ein dünner Client auf die v1-API — keine eigene Logik, dadurch verhaltensgleich mit UI und API (ADR-0020).

Transport

Zwei gleichwertige Transporte über denselben Thin-Client-Code:

stdio (lokaler Prozess) — für Claude Desktop / Claude Code ohne Hosting; Konfiguration via ENV.
Streamable HTTP (gehostet, POST /api/mcp) — kein lokaler Prozess nötig, der Client verbindet sich direkt mit dem Deployment. Stateless (serverless-tauglich); Auth via Bearer-Key im Authorization-Header.

Tools

Tool	Eingabe	Ergebnis
`generate_report`	`{ address: string }`	vollständiges Report-JSON (REPORT-SPEC)
`report_summary`	`{ address: string }`	Kompaktfassung: Ampel + erwartete Kosten je Szenario, Förder-IDs, degradierte Layer
`export_report`	`{ address: string }`	persistierter Report → teilbarer Permalink + PDF-URL (ADR-0022)

Diese rufen POST /api/v1/report. report_summary verdichtet nur vorhandene Felder — keine neuen Zahlen.

Admin-Tools (get_usage, set_model, set_budget) rufen /api/v1/admin/* und benötigen einen Key mit admin-Scope (ADR-0024); ohne Scope antworten sie mit 403.

Konfiguration (ENV)

Variable	Default	Zweck
`LANDNUTZEN_API_BASE`	`https://landnutzen.vercel.app/api/v1`	API-Basis
`LANDNUTZEN_API_KEY`	–	optional; `Bearer`-Key → höheres Tageslimit + Audit (ADR-0019)

Einbinden

Voraussetzung: Repo geklont, npm install ausgeführt.

Claude Desktop / Claude Code

In die MCP-Konfiguration aufnehmen (Pfad zum Repo anpassen):

{
  "mcpServers": {
    "landnutzen": {
      "command": "node",
      "args": ["/ABSOLUTER/PFAD/landnutzen/mcp/landnutzen-mcp.mjs"],
      "env": {
        "LANDNUTZEN_API_BASE": "https://landnutzen.vercel.app/api/v1"
      }
    }
  }
}

Mit API-Key zusätzlich "LANDNUTZEN_API_KEY": "ln_…" im env-Block.

Remote (HTTP, ohne lokalen Prozess)

Der gehostete Endpoint spricht das Streamable-HTTP-Protokoll unter https://landnutzen.vercel.app/api/mcp. Ein MCP-Client verbindet sich direkt — kein Klonen, kein lokaler Node-Prozess:

{
  "mcpServers": {
    "landnutzen": {
      "type": "http",
      "url": "https://landnutzen.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer ln_…" }
    }
  }
}

Der Authorization-Bearer-Key wird an die v1-API durchgereicht (höheres Tageslimit + Audit, ADR-0019); ohne Header läuft der Zugang anonym mit IP-Tageslimit. Admin-Tools brauchen einen Key mit admin-Scope. (Die genauen Client-Felder — z. B. type: "http" — variieren je MCP-Client; entscheidend sind URL + Bearer-Header.)

Schnelltest (ohne Client)

npm run mcp        # startet den Server auf stdio (Ctrl-C beendet)

Vollständige E2E-Specs (Server, tools/list, generate_report) decken beide Transporte ab: stdio in tests/e2e/mcp.spec.ts, Streamable HTTP in tests/e2e/mcp-http.spec.ts (npm run test:e2e).

Fehlerverhalten

API-Fehler werden in klare MCP-Fehlermeldungen übersetzt:

429 Tageslimit — Hinweis auf Retry-After und API-Key
401 Key ungültig/widerrufen — Hinweis Key prüfen/weglassen
5xx/400 Status + Server-Meldung durchgereicht

Grenzen

Identisch zur API: Widmung ist Indikation (nicht rechtsverbindlich), Kostenrahmen sind Grob-Schätzungen, nicht verfügbare Layer stehen unter meta.degraded. Quellen/Lizenzen je Report unter sources — siehe Datenquellen & Lizenzen.