MCP & API/DokumentationBETA

MCP & REST-API Dokumentation

Vollständige Referenz für die rentab.ly MCP-Integration und REST API v1. 23 Tools, scope-basierte Berechtigungen, konsistente Fehlerbehandlung.

Die API befindet sich in der Beta-Phase und ist nur für freigeschaltete Accounts verfügbar.

MCP Protocol 2024-11-05 REST API v1.0.0 Server: rentably v1.0.0

OpenAPI Spec Anmelden

Schnellstart

In 3 Schritten zur ersten Abfrage:

1. API-Schlüssel erstellen

Im Dashboard unter Integrationen → API-Schlüssel. Wählen Sie die benötigten Scopes.

2. Erste Anfrage (REST)

curl -H "Authorization: Bearer rntb_IHR_API_KEY" \
  https://YOUR_PROJECT.supabase.co/functions/v1/rest-api/v1/properties

3. Oder via MCP (Claude Desktop)

// claude_desktop_config.json
{
  "mcpServers": {
    "rentably": {
      "url": "https://YOUR_PROJECT.supabase.co/functions/v1/mcp-server",
      "headers": {
        "Authorization": "Bearer rntb_IHR_API_KEY"
      }
    }
  }
}

Verbindungseinrichtung

MCP-Verbindung (Streamable HTTP)

Der rentab.ly MCP Server unterstützt das Streamable HTTP Transport (Protocol Version 2024-11-05).

Endpoint URL

https://YOUR_PROJECT.supabase.co/functions/v1/mcp-server

Protocol

JSON-RPC 2.0 über HTTP POST

REST API

Klassische HTTP-Endpunkte für programmatischen Zugriff ohne MCP-Client.

Base URL

https://YOUR_PROJECT.supabase.co/functions/v1/rest-api

Hinweis: Beide Schnittstellen verwenden denselben API-Schlüssel und dieselben Berechtigungen. Was Sie über MCP abfragen, können Sie auch über REST abrufen — und umgekehrt.

Authentifizierung

Alle Anfragen erfordern einen API-Schlüssel im Authorization Header.

Authorization: Bearer rntb_IHR_API_KEY

Format: API-Keys beginnen immer mit rntb_.

Erzeugung: Dashboard → Integrationen → Neuer API-Schlüssel.

Speicherung: Der Schlüssel wird nur bei Erstellung angezeigt. Er wird serverseitig als SHA-256-Hash gespeichert.

Widerruf: Schlüssel können jederzeit im Dashboard widerrufen werden. Widerrufene Schlüssel geben TOKEN_EXPIRED zurück.

Scopes

Bei der Erstellung eines API-Schlüssels wählen Sie die benötigten Scopes. Jedes Tool und jeder Endpunkt erfordert mindestens einen passenden Scope.

Scope	Berechtigung
`properties`	Immobilien und Einheiten lesen
`tenants`	Mieter-Stammdaten lesen
`leases`	Mietverträge lesen
`payments`	Zahlungen, Betriebskosten, Indexmiete lesen und Notizen schreiben
`tasks`	Aufgaben lesen und erstellen
`documents`	Dokumente auflisten und durchsuchen
`messages`	Nachrichten-Entwürfe erstellen
`*`	Alle Scopes (Wildcard)

Fehlende Scopes geben SCOPE_REQUIRED mit dem fehlenden Scope in details.required_scope.

MCP Tool-Verzeichnis

23 Tools verfügbar (16 lesend, 6 schreibend, 1 Suche).

REST Endpunkte

23 Endpunkte. Alle Pfade relativ zur Base URL.

GET/v1/propertiesAlle Immobilien auflistenproperties

GET/v1/properties/:idImmobilie im Detailproperties

GET/v1/unitsEinheiten auflistenunits

GET/v1/units/:idEinheit im Detailunits

GET/v1/tenantsMieter auflistentenants

GET/v1/tenants/:idMieter im Detailtenants

GET/v1/leasesMietverträge auflistenleases

GET/v1/leases/:idMietvertrag im Detailleases

GET/v1/paymentsZahlungen auflistenpayments

GET/v1/payments/openOffene Positionenpayments

GET/v1/payments/:id/summaryMietkonto-Zusammenfassungpayments

POST/v1/payments/:id/notesInterne Notiz hinzufügenpayments

GET/v1/tasksAufgaben auflistentasks

GET/v1/tasks/:idAufgabe im Detailtasks

POST/v1/tasksAufgabe erstellentasks

PATCH/v1/tasks/:id/statusAufgabenstatus änderntasks

GET/v1/documentsDokumente auflistendocuments

GET/v1/documents/searchDokumente durchsuchendocuments

GET/v1/operating-costsBetriebskostenabrechnungenpayments

GET/v1/index-rentIndexmiet-Statuspayments

POST/v1/drafts/messageNachrichtenentwurf erstellenmessages

POST/v1/drafts/payment-reminderZahlungserinnerung vorbereitenmessages

POST/v1/drafts/index-rent-letterIndexmietschreiben vorbereitenmessages

Beispielantwort

// GET /v1/properties
{
  "data": {
    "properties": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Musterstraße 10",
        "address": "Musterstraße 10, 12345 Berlin",
        "type": "apartment_building",
        "unit_count": 4
      }
    ],
    "total": 12,
    "limit": 50,
    "offset": 0
  }
}

Paginierung

Listen-Endpunkte unterstützen limit (max 100, Standard 50) und offset (Standard 0).

// Anfrage
GET /v1/properties?limit=20&offset=40

// Antwort
{
  "data": {
    "properties": [...],
    "total": 85,
    "limit": 20,
    "offset": 40
  }
}

MCP Tools verwenden dieselben Parameter. Die Antwort enthält immer total für die Gesamtanzahl.

Fehlercodes

Konsistentes Fehlerformat über MCP und REST. Das Feld retryable zeigt an, ob ein erneuter Versuch sinnvoll ist.

// Fehlerantwort
{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "Missing required scope: payments",
    "retryable": false,
    "details": {
      "required_scope": "payments",
      "your_scopes": ["properties", "tenants"]
    }
  }
}

HTTP	Code	Beschreibung	Retry
401	`AUTHENTICATION_REQUIRED`	Kein oder ungültiger Authorization Header	Nein
401	`TOKEN_EXPIRED`	API-Key abgelaufen oder widerrufen	Nein
403	`SCOPE_REQUIRED`	Fehlender Scope für diese Aktion	Nein
403	`PERMISSION_DENIED`	Kein Zugriff auf diese Ressource / Feature deaktiviert	Nein
404	`RESOURCE_NOT_FOUND`	Ressource nicht gefunden oder kein Zugriff	Nein
422	`VALIDATION_ERROR`	Ungültige Parameter oder fehlende Pflichtfelder	Nein
409	`CONFLICT`	Duplikat-Idempotency-Key oder Ressource bereits vorhanden	Nein
429	`RATE_LIMIT_EXCEEDED`	Rate Limit erreicht, Retry-After Header beachten	Ja
500	`INTERNAL_ERROR`	Unerwarteter Serverfehler	Ja

Rate Limits

Limits pro API-Key und Bucket-Typ. Zähler werden minütlich zurückgesetzt.

Lesezugriffe / Minute

Schreibzugriffe / Minute

Suchanfragen / Minute

Response Headers (REST)

X-RateLimit-Limit — Maximale Anfragen im Zeitfenster

X-RateLimit-Remaining — Verbleibende Anfragen

X-RateLimit-Reset — Zeitpunkt des Resets (ISO 8601)

Retry-After — Sekunden bis zum Retry (nur bei 429)

Bei RATE_LIMIT_EXCEEDED warten Sie die im Header angegebene Zeit ab. Automatische Retries mit Exponential Backoff empfohlen.

Draft Pattern (Entwürfe)

Schreibende Aktionen mit externem Einfluss (Nachrichten, Zahlungserinnerungen) erzeugen Entwürfe statt sofortiger Ausführung. Dies verhindert versehentliche Kommunikation.

KI erstellt Draft

Tool-Aufruf mit den gewünschten Inhalten + optionalem Idempotency-Key.

Benutzer prüft in rentab.ly

Der Entwurf erscheint im Dashboard zur Prüfung und Bestätigung.

Bestätigung & Versand

Erst nach manueller Bestätigung wird die Nachricht versendet.

Idempotenz

Senden Sie bei Schreiboperationen einen idempotency_key mit. Bei doppeltem Key wird kein neuer Draft erstellt, sondern der bestehende zurückgegeben (CONFLICT).

Sicherheitshinweise

Mandantentrennung: Alle Daten sind strikt nach Account isoliert. Ein API-Key kann ausschließlich auf Daten des eigenen Accounts zugreifen.

Minimal Privilege: Erstellen Sie separate API-Keys mit nur den benötigten Scopes für jeden Anwendungsfall.

Key-Rotation: Widerrufen Sie nicht mehr benötigte Schlüssel sofort. Erstellen Sie bei Verdacht auf Kompromittierung einen neuen Key.

Keine Klartext-Speicherung: API-Keys werden ausschließlich als SHA-256-Hash gespeichert. Der Klartext existiert nur bei Erstellung.

Audit-Logging: Jede API-Aktion wird mit Timestamp, IP-Adresse, genutztem Key und Ergebnis protokolliert.

Draft Pattern: Nachrichten können nicht direkt über die API versendet werden. Das schützt vor versehentlicher Massenkommunikation.

Rate Limiting: Schützt vor Missbrauch und übermäßiger Nutzung. Pro Key, nicht pro User.

HTTPS-Only: Alle Verbindungen sind TLS-verschlüsselt. Unverschlüsselte Verbindungen werden abgelehnt.

Changelog

2026-07-16v1.0.0

Initiale Beta-Version

23 MCP Tools (17 lesend, 5 schreibend, 1 Suche)
23 REST-Endpunkte mit identischer Funktionalität
Scope-basierte Berechtigungen (7 Scopes + Wildcard)
Rate Limiting (60/10/5 per Minute)
Draft Pattern für ausgehende Kommunikation
Vollständiges Audit Logging
Feature Flag Steuerung
Idempotency-Keys für Schreiboperationen

MCP Protocol

2024-11-05

REST API Version

v1.0.0

Server

rentably 1.0.0

Bereit loszulegen?

Erstellen Sie einen API-Schlüssel und integrieren Sie rentab.ly in Ihre Workflows.

Bei rentab.ly anmelden OpenAPI Spec

MCP-Integration Übersicht openapi.json