Zum Inhalt

REST-API und MCP-Server

Die App, das Terminal und die Warteschlange am Handy sprechen mit derselben API wie jedes andere Programm. Ein Programm, eine Tabelle oder ein KI-Assistent ruft sie mit einem persönlichen Zugang auf: einem Token, das eine Person für sich anlegt.

Zugänge

Unter Einstellungen → Zugänge zur API legt jede Person eines Betriebs einen Zugang an, mit einem Namen und wahlweise einem Ablauf nach 30, 90 oder 365 Tagen. Das Gerät des Terminals hat keine Zugänge.

  • Einmal sichtbar: Das Token (soll_…) steht nur in der Antwort auf das Anlegen. Soll speichert seinen SHA-256 und die ersten neun Zeichen, an denen man es in der Liste wiedererkennt; wer es verliert, legt einen neuen Zugang an.
  • Die Rechte der eigenen Rolle, nie mehr: Ein Token trägt keine Rechte. Bei jedem Aufruf gilt die Rolle, die seine Person in diesem Moment im Betrieb hat. Wird aus der Mitarbeiterin eine Planerin, darf ihr Token beim nächsten Aufruf, was eine Planerin darf; wer den Betrieb verlässt, dessen Zugänge enden sofort und leben auch nach einem Wiedereintritt nicht auf.
  • Ein Betrieb: Ein Token gehört zu dem Betrieb, in dem es angelegt wurde. Wer in zwei Betrieben arbeitet, legt in jedem einen eigenen Zugang an.
  • Widerrufen: Jeder Zugang lässt sich in der Liste widerrufen; danach antwortet die API mit 401.
  • Protokoll: Anlegen, Widerrufen und der Tag der letzten Nutzung stehen in der Audit-Kette, die Nutzung höchstens einmal am Tag. In der Auskunft stehen Name und Daten jedes eigenen Zugangs, nie das Token.
  • Verwalten nur angemeldet: Zugänge legt man mit der Sitzung in der App an und widerruft sie dort; ein Token kann keinen weiteren Zugang anlegen (403 nur_sitzung).

REST-API

Jede Route unter /api/v1 nimmt das Token als Kopfzeile, neben der Sitzung der App:

curl -H "Authorization: Bearer soll_…" https://soll.example/api/v1/arbeitszeit/tag
Antwort Bedeutung
401 zugang_ungueltig Token unbekannt, widerrufen oder älter als die Mitgliedschaft
401 zugang_abgelaufen der Ablauf des Zugangs ist erreicht
403 kein_mitglied die Person gehört nicht mehr zum Betrieb
403 keine_berechtigung die Rolle darf das nicht
403 modul_aus das Modul der Route ist im Betrieb abgeschaltet
429 zu_viele_anfragen mehr als 120 Aufrufe in der Minute mit diesem Token; Retry-After nennt die Sekunden

Ein falsches Token wird abgelehnt, auch wenn daneben eine Sitzung mitkommt. Was über ein Token gestempelt wird, trägt die Quelle api statt app.

OpenAPI

Die Beschreibung aller Routen steht ohne Anmeldung unter /api/v1/openapi.json (OpenAPI 3.1). Soll erzeugt sie aus denselben Zod-Schemas, mit denen die Routen ihre Eingaben prüfen; ein Test liest die Routen aus der App und schlägt fehl, wenn eine ohne Beschreibung bleibt.

MCP-Server

Unter /mcp spricht Soll das Model Context Protocol über Streamable HTTP, ohne Sitzung: Fassung 2026-07-28 mit server/discover und die Fassungen 2025-03-26 bis 2025-11-25 mit initialize. Ein KI-Assistent bekommt die Adresse und das Token als Kopfzeile Authorization: Bearer soll_…; eine Sitzung der App gilt hier nicht.

Werkzeug Was es tut Route
betrieb_lesen Betrieb, eigene Rolle, Module GET /api/v1/betrieb
tag_lesen ein Arbeitstag mit Stempelungen, Ist und Befunden GET /api/v1/arbeitszeit/tag
monat_lesen ein Monat mit Konto, Befunden und Abschluss GET /api/v1/arbeitszeit/monat
stempeln jetzt kommen, gehen oder Pause POST /api/v1/arbeitszeit/stempelungen
kunden_lesen, auftraege_lesen, taetigkeiten_lesen Kunden, Aufträge, Tätigkeiten /api/v1/projektzeit/…
standorte_lesen die Standorte GET /api/v1/standorte
dienstplan_woche eine Woche im Dienstplan GET /api/v1/dienstplan/woche

Jedes Werkzeug ruft die REST-API mit demselben Token auf. Es darf also genau, was die Rolle darf, ein abgeschaltetes Modul antwortet mit modul_aus, und es erreicht keinen anderen Betrieb. Eine Ablehnung der API kommt als Fehler des Werkzeugs (isError) zurück, damit der Assistent sie lesen kann. Jede Anfrage an /mcp zählt einmal gegen die Grenze des Tokens.

Der Server prüft, was die Spezifikation verlangt: eine fremde Origin bekommt 403; in der Fassung 2026-07-28 müssen MCP-Protocol-Version, Mcp-Method und Mcp-Name zum Inhalt passen (sonst 400 mit -32020), eine unbekannte Fassung bekommt 400 mit -32022 und der Liste der Fassungen. GET und DELETE beantwortet er mit 405: Er hat keinen eigenen Strom und keine Sitzungen.

Projektzeit buchen kommt mit der Stoppuhr (S-602) als Werkzeug dazu.