Diese Anleitung richtet sich an Entwicklerinnen und Entwickler, die einen eigenen KI-Agenten auf einem Server an den immoJUMP-MCP-Server anbinden — ohne Desktop, ohne Browser, ohne Anmeldefenster. Die beiden bestehenden Anleitungen (ohne Terminal und für technisch Versierte) setzen beide einen Rechner mit Oberfläche voraus. Hier geht es um den Dauerbetrieb: eigene Identität für den Agenten, harte Rechtegrenzen, Token-Lebensdauer, Limits.
Kurzfassung
| Frage | Antwort |
|---|---|
| Eigene Identität für den Agenten? | Ja — Bot-Token aus Organisation → Bots |
| Rechte einschränken? | Ja — Rolle mit deny-Regeln, serverseitig durchgesetzt |
| Statischer Bearer-Header? | Offiziell unterstützt, bleibt bestehen |
| Token-Ablauf? | Kein praktischer Ablauf, Rotation entzieht sofort |
| Rate Limits? | 5.000 Anfragen/Stunde, einzelne Endpunkte enger |
1. Der Agent bekommt eine eigene Identität
Der Token aus Einstellungen → Schnittstellen-Zugang gehört einem Menschen. Ein Agent, der damit arbeitet, handelt unter dessen Namen — im Protokoll ist danach nicht mehr zu unterscheiden, wer was getan hat. Für einen dauerhaft laufenden Agenten ist das die falsche Grundlage.
Bot-Token funktionieren gegen den MCP-Server. Lege unter Organisation → Bots einen Bot an (Deployment: Kein Deployment (extern / Polling)), kopiere den Token und schicke ihn wie gewohnt:
Authorization: Bearer <bot-token>
X-Organisation-Id: <organisations-id>Der Bot ist ein vollwertiges Mitglied deiner Organisation mit eigenem Namen und eigenem Kürzel. Aktivitäten, Kommentare und Änderungen erscheinen unter seiner Identität — nicht unter der eines Mitarbeiters. Genau dafür ist die Funktion gebaut. Einen zusätzlichen Benutzer anzulegen ist nicht nötig und wäre der schlechtere Weg: ein Bot ist im Team sofort als solcher erkennbar.
Ein Bot-Token ist bewusst enger als ein Benutzer-Token: Die Bot-Verwaltung selbst ist für Bots gesperrt. Ein abhandengekommener Bot-Token kann also keine weiteren Bots anlegen, keine Token rotieren und keine anderen Bots löschen.
2. Nur lesen: Rechte hart begrenzen
Ein Bot-Token ist von sich aus nicht schreibgeschützt — es hat die Rechte eines normalen Mitglieds. Selbstbeschränkung des Agenten über den Prompt ist keine Sicherheitsgrenze. Die echte Grenze zieht immoJUMPs Rollen- und Rechtesystem, und die gilt serverseitig: Was die Rolle verbietet, wird abgewiesen, egal welches Werkzeug der Agent aufruft.
Das Rezept für einen reinen Lese-Agenten sind drei deny-Regeln auf einer Rolle, die du dem Bot zuweist:
- Unter Organisation → Rollen eine Rolle anlegen, z. B. „Agent (nur lesen)“.
- Drei Regeln hinterlegen — jeweils Effekt
deny, Ressource*, Verbcreate,updateunddelete. - Die Rolle dem Bot zuweisen.
Danach beantwortet der Server jede schreibende Anfrage des Agenten mit 403 — auch immobilien_delete, immobilien_transfer und email_account_send. Lesen, Suchen und Auswerten bleiben unverändert möglich.
Wichtig zur Reihenfolge: deny wirkt abziehend. Eine Rolle, die nur Verbote enthält, behält vollen Zugriff auf alles, was sie nicht ausdrücklich verbietet — deshalb ist * als Ressource die richtige Wahl und nicht eine Aufzählung einzelner Objektarten. Und: Ein Mitglied mit der Rolle Administrator steht über den Regeln. Der Bot muss ein einfaches Mitglied bleiben, sonst laufen die Verbote ins Leere.
Ergänzend, aber zusätzlich und nicht ersatzweise: Der MCP-Server kennzeichnet jedes Werkzeug als lesend, schreibend oder löschend (readOnlyHint). Viele Clients können darüber Werkzeuge ausblenden. Das reduziert Versehen und spart Kontext — die Sicherheitsgrenze bleibt die Rolle.
3. Der statische Bearer-Header ist der vorgesehene Weg
Ja, das ist offiziell unterstützt — und kein Nebeneffekt. Der Server kennt drei Wege, Zugangsdaten entgegenzunehmen, und der Header ist der erste davon. Er ist ausdrücklich für Clients ohne Browser gedacht.
Der OAuth-Weg mit PKCE existiert für Clients, die zwingend OAuth verlangen (etwa ChatGPT) — er verpackt intern denselben Token. Wer den Header nutzt, umgeht nichts, sondern spart nur den Umweg. Baut euren Agenten ruhig darauf. Sollte sich daran je etwas ändern, kündigen wir das mit Vorlauf an und brechen keine laufenden Integrationen.
Ein Detail für die Umsetzung: Manche Endpunkte erwarten die Organisation zusätzlich als Parameter organisation_id, nicht nur im Header. Der MCP-Server erledigt das für euch — wer direkt gegen die API geht, sollte es wissen.
4. Paketstufen und Lizenz
Die drei Hosts sind Werkzeug-Zuschnitte, keine Lizenzstufen. Sie unterscheiden sich darin, wie viele Werkzeuge ein Client geladen bekommt — nicht darin, was ihr vertraglich dürft. Dass euer Token von allen dreien angenommen wird, ist so beabsichtigt und kein Versehen.
Was ihr nutzen dürft, prüft der Server an der Stelle, an der es zählt: bei den Daten selbst. Eure TEAM-Lizenz liegt in der Profi-Klasse — 100 KI-Dokumentanalysen pro Kalendermonat, 200 aktive Objekte je Organisation. Wird ein Kontingent überschritten, antwortet die API mit 402 und einem strukturierten Hinweis, welches Limit greift. Ihr könnt also nichts „versehentlich“ nutzen, was nicht Teil eures Vertrags ist.
Praktischer Rat: Nehmt die kleinste Stufe, die eure Aufgabe abdeckt. Für eine Ankaufsanalyse reicht in aller Regel die Standardstufe. Weniger Werkzeuge heißt weniger Kontext, schnellere Antworten und eine kleinere Angriffsfläche.
Zu den Zahlen: Eure Messung ist richtig, unsere Anleitung war veraltet. Der Werkzeugbestand wächst mit jeder Version — verlasst euch im Zweifel auf tools/list zur Laufzeit, nicht auf eine Zahl in der Dokumentation. Von den Werkzeugen der Vollstufe sind übrigens nur rund 40 % lesend; der Rest schreibt oder löscht. Eure Einschätzung war also eher zu vorsichtig — ein Grund mehr für die Rolle aus Abschnitt 2.
5. Lebensdauer und Rotation des Tokens
Der Token hat keinen praktisch relevanten Ablauf — ihr müsst für einen Dauerbetrieb keine Erneuerung einplanen.
Entzogen wird er durch Rotation: Sobald ein neuer Token erzeugt wird, ist der alte sofort ungültig. Es gilt immer genau ein gültiger Token pro Zugang; ein alter Token bleibt nicht parallel gültig. Für Bots geschieht das über Organisation → Bots → Token rotieren. Rechnet also mit einem kurzen Ausfall beim Wechsel und legt den Token so ab, dass ihr ihn ohne Neuausrollen tauschen könnt.
6. Rate Limits
Es gibt eine Obergrenze von 5.000 Anfragen pro Stunde. Für eine Ankaufsanalyse ist das reichlich; ihr müsst dafür nichts Besonderes bauen.
Enger sind einzelne teure Endpunkte:
- KI-Dokumentanalyse: 20 pro Stunde (zusätzlich zum Monatskontingent)
- E-Mail-Versand: 60 pro Stunde
- Marktwert-Abfragen: 50 pro Tag
Bei Überschreitung kommt 429. Ein einfacher Backoff mit Wiederholung genügt. Sinnvoller als hartes Drosseln: Ergebnisse auf eurer Seite zwischenspeichern — Stammdaten eines Objekts ändern sich während einer Analyse nicht.
7. Was hinter valuation_request steckt
Hinter den Bewertungs-Werkzeugen stehen zwei externe Anbieter:
- GeoMap (Voreinstellung) — Marktdaten aus Angebots- und Transaktionsdaten, Umkreisanalyse um die Adresse.
- FPRE (Fahrländer Partner Raumentwicklung) — hedonisches Bewertungsmodell.
valuation_providers zeigt euch, welche in eurer Instanz aktiv sind. Für die Gegenprobe, die ihr vorhabt, ist das genau der richtige Ansatz: dieselbe Adresse gegen beide Anbieter laufen lassen und die Spanne betrachten, statt einer Zahl zu vertrauen.
Zu Kosten und Kontingent: Abgerechnet wird nicht pro Abruf. Es gilt das Limit von 50 Abfragen pro Tag. Ergebnisse werden 24 Stunden zwischengespeichert — dieselbe Adresse mehrfach abzufragen kostet also kein zusätzliches Kontingent. valuation_history liest die bereits erhobenen Bewertungen eines Objekts und geht gar nicht erst nach außen; für Wiederholungsläufe ist das der günstigste Weg.
Empfehlung für euren Aufbau
- Eigenen Bot anlegen, Token dort ziehen — nicht den Benutzer-Token verwenden.
- Rolle „Agent (nur lesen)“ mit den drei
deny-Regeln anlegen und zuweisen. - Standardstufe verwenden, solange keine Aufgabe mehr verlangt.
- Statischen Bearer-Header nutzen, Token austauschbar ablegen.
- Marktwerte gegen beide Anbieter prüfen und die Spanne bewerten.
Fragen zum Aufbau beantworten wir gern direkt — schreib uns an info@immojump.de.