API und MCP-Server

Diese Website hat neben den Seiten für Besucher zwei Zugänge für Programme und KI-Assistenten: eine öffentliche API (REST) und einen MCP-Server (Model Context Protocol). Beide sind ohne Anmeldung nutzbar und zeigen dieselben Inhalte wie die Website.

Was Sie damit tun können

  • die aktuellen Kauf- und Mietangebote abrufen, wahlweise nach Art und Rubrik gefiltert,
  • ein einzelnes Angebot mit den Angaben des Exposés abrufen: Objektdaten, Texte, Werte des Energieausweises und Fotos,
  • die Kontaktdaten des Büros abrufen,
  • im Auftrag einer Person eine Nachricht an Henry Koch senden, entweder allgemein wie über das Kontaktformular oder als Anfrage zu einem Angebot wie über das Anfrageformular im Exposé.

Die Inhalte sind deutsch, die Feldnamen der API englisch.

Adressen

MCP-Server einrichten

Claude

  1. Öffnen Sie in Claude die Einstellungen und wählen Sie „Konnektoren“.
  2. Wählen Sie „Benutzerdefinierten Konnektor hinzufügen“.
  3. Tragen Sie als Adresse https://kochs-immobilien.de/mcp ein und geben Sie dem Konnektor einen Namen, zum Beispiel „Henry Koch Immobilien“.
  4. Eine Anmeldung ist nicht nötig. Bestätigen Sie das Hinzufügen und aktivieren Sie den Konnektor in der Unterhaltung, in der Sie ihn nutzen möchten.

Andere Programme

Jeder Client, der entfernte MCP-Server über Streamable HTTP unterstützt, kann sich mit https://kochs-immobilien.de/mcp verbinden. Der Server speichert keine Sitzungen und verlangt keine Zugangsdaten. Die Werkzeuge sind:

  • list_offers: aktuelle Angebote auflisten, optional nach type (verkauf oder vermietung) und category filtern,
  • get_offer: ein Angebot über seine Nummer abrufen,
  • get_contact: Kontaktdaten des Büros abrufen,
  • send_contact_message: eine allgemeine Nachricht an Henry Koch senden,
  • send_enquiry: eine Anfrage zu einem Angebot senden.

Die REST-API nutzen

Die Angebote lesen Sie mit einem einfachen Abruf, zum Beispiel:

curl https://kochs-immobilien.de/api/v1/offers?type=verkauf

Die Operationen im Überblick:

  • GET /api/v1/offers: Angebote auflisten,
  • GET /api/v1/offers/{id}: ein Angebot abrufen,
  • GET /api/v1/contact: Kontaktdaten abrufen,
  • POST /api/v1/contact-messages: eine Nachricht senden,
  • POST /api/v1/offers/{id}/enquiries: eine Anfrage zu einem Angebot senden.

Alle Felder, Pflichtangaben und Antworten beschreibt die OpenAPI-Beschreibung. Anfragen zum Senden erwarten einen JSON-Körper (Content-Type: application/json) von höchstens 16 KiB.

Regeln für das Senden von Nachrichten

Nachrichten über die API und den MCP-Server erreichen Henry Koch wirklich. Deshalb gilt:

  • Senden Sie eine Nachricht nur im Auftrag einer Person, die das ausdrücklich wünscht, und mit ihren eigenen, echten Angaben. Ein Assistent zeigt der Person die Nachricht vorher und sendet nichts ohne ihr Einverständnis.
  • Werbung, Massennachrichten und Tests mit erfundenen Angaben sind nicht erlaubt.
  • Jede Nachricht wird vor der Zustellung geprüft. Nachrichten, die diese Prüfung nicht bestehen, werden nicht zugestellt.
  • Je Absender (Netzwerk und E-Mail-Adresse) gelten dieselben Grenzen wie für die Formulare der Website. Zu einem Angebot kann ein Absender pro Tag nur wenige Male anfragen.
  • Zusätzlich nimmt die Website über die API und den MCP-Server zusammen nur eine begrenzte Anzahl von Nachrichten pro Tag an (Tageslimit). Ist es erreicht, antwortet sie mit dem Status 429 und nimmt erst am nächsten Tag wieder Nachrichten an.
  • Die Antwort „received“ (Status 202) bedeutet: Die Nachricht ist empfangen, nicht zugestellt. Über das Ergebnis der Prüfung gibt die Antwort keine Auskunft.

Die Verarbeitung der Nachrichten beschreibt unsere Datenschutzerklärung. Wenn etwas dringend ist, erreichen Sie das Büro telefonisch unter 0 50 24 - 88 330.

Fehlermeldungen

Die API meldet Fehler als application/problem+json nach RFC 9457. Das Feld type verweist auf einen der folgenden Abschnitte.

  • Ungültige Angaben (422): Pflichtangaben fehlen oder sind ungültig. Das Feld errors nennt jedes betroffene Feld mit einer deutschen Meldung.
  • Angebot nicht gefunden (404): Zu dieser Nummer gibt es kein aktuelles Angebot. Es kann inzwischen vergeben oder zurückgezogen sein.
  • Zu viele Nachrichten (429): Die Grenzen je Absender sind erreicht. Der Header Retry-After nennt die Wartezeit in Sekunden.
  • Tageslimit erreicht (429): Heute werden über die API und den MCP-Server keine weiteren Nachrichten mehr angenommen. Der Header Retry-After nennt die Sekunden bis zum nächsten Tag.
  • Ungültige Anfrage (400): Der Körper oder ein Parameter ist nicht lesbar, zum Beispiel kein gültiges JSON, ein unbekanntes Feld oder ein unbekannter Filterwert.
  • Format nicht unterstützt (415): Nachrichten erwarten Content-Type: application/json.
  • Anfrage zu groß (413): Der Körper ist größer als 16 KiB.
  • Interner Fehler (500): Die Anfrage konnte nicht verarbeitet werden. Versuchen Sie es später erneut.
  • Nicht gefunden (404): Diese Adresse gibt es in der API nicht.
  • Methode nicht erlaubt (405): Die Adresse kennt diese HTTP-Methode nicht. Der Header Allow nennt die erlaubten.

Bereitgestellt durch wambo