Konfigurationsreferenz
Jede Variable des Fernzugriffs, wie sich die Variablen des stdio-Modus unter
--http ändern und wobei der Start abbricht oder warnt. Die Variablen, die mit stdio geteilt sind,
stehen unter Konfiguration.
Alle Variablen werden beim Start gelesen. Der Start meldet alle Probleme auf einmal und verweigert
sich, bis alle behoben sind. Variablen, die auf _FILE enden, lesen den Wert stattdessen aus einer
Datei (Docker- und Kubernetes-Secrets); setze die eine oder die andere.
HTTP-Variablen
| Variable | Standard | Bedeutung |
|---|---|---|
SEVDESK_HTTP_AUTH | (Pflicht) | bearer oder oauth (Bearer oder OAuth). |
SEVDESK_HTTP_HOST | 127.0.0.1 (Image: 0.0.0.0) | Adresse, auf der der Server lauscht. Alles außer einer Loopback-Adresse braucht SEVDESK_HTTP_PUBLIC_URL. |
SEVDESK_HTTP_PORT | $PORT, sonst 8080 (Image: 8080) | Port, 0–65535 (0 wählt einen freien Port, für Tests). |
SEVDESK_HTTP_PUBLIC_URL | Der Origin, den Clients verwenden, zum Beispiel https://mcp.example.com: nur Schema, Host und Port, ohne Pfad, Query, Fragment oder Zugangsdaten. https, außer der Host ist localhost, 127.0.0.1 oder [::1]. Pflicht für OAuth und wenn der Server nicht nur auf Loopback lauscht. Der MCP-Endpunkt (und die OAuth-Ressource) ist <origin>/mcp, der OAuth-Issuer ist der Origin. Jede URL, die der Server ausgibt oder auf die er weiterleitet, wird daraus gebaut, nie aus Headern der Anfrage. | |
SEVDESK_HTTP_ALLOWED_HOSTS | Weitere Hostnamen, die im Host-Header angenommen werden, durch Kommas getrennt. Der Host der öffentlichen URL wird immer angenommen (bei Loopback ohne öffentliche URL die Loopback-Namen). | |
SEVDESK_HTTP_ALLOWED_ORIGINS | Weitere Werte, die im Origin-Header von /mcp-Anfragen angenommen werden, durch Kommas getrennt; die Prüfung vergleicht nur Hostnamen (beliebiges Schema, beliebiger Port). Der öffentliche Origin wird immer angenommen, und Anfragen ohne Origin passieren. /mcp sendet keine CORS-Header und beantwortet kein Preflight (OPTIONS); MCP-Clients, die in einer Webseite auf einem anderen Origin laufen, werden also nicht unterstützt: Das lässt nur Clients zu, die selbst einen solchen Origin-Header senden. | |
SEVDESK_HTTP_TRUST_PROXY | 0 | Reverse Proxys vor dem Server, 0–5. Die Client-IP (Ratenbegrenzung, Logs) ist der Eintrag, der so viele Stellen von rechts in X-Forwarded-For steht. |
SEVDESK_HTTP_BEARER_TOKEN (_FILE) | Bearer-Modus, Pflicht: das Client-Geheimnis, oder zwei durch Komma getrennte Geheimnisse während eines Wechsels. Jedes mindestens 32 Zeichen mit mindestens 16 verschiedenen, ohne Leerraum und nicht das sevDesk-Token. | |
SEVDESK_HTTP_SECRET (_FILE) | OAuth, Pflicht: das Server-Geheimnis, mit dem alle Tokens und Cookies versiegelt werden; mindestens 32 zufällige Bytes, hex oder base64/base64url (generate-secret). Optional im Bearer-Modus, wo es Browser-Anmeldungen über einen Neustart hinweg gültig hält. | |
SEVDESK_HTTP_SECRET_PREVIOUS (_FILE) | Das vorige Server-Geheimnis, während du es wechselst: Damit versiegelte Tokens werden weiter angenommen und bei der Erneuerung neu versiegelt. | |
SEVDESK_HTTP_STATE_DIR | Speicher (Image: /data) | Absolutes Verzeichnis für den Zugangsspeicher und die verschlüsselten Dateien der Dateiübertragung (files/); angelegt mit Modus 0700 (ein bestehendes wird auf 0700 verschärft) und beim Start auf Schreibrechte geprüft. Ohne die Variable enden Zugänge und Browser-Sitzungen mit dem Prozess (der OAuth-Start warnt), und Dateien werden im Speicher gehalten. |
SEVDESK_HTTP_FILES | on | Dateiübertragung: Upload-Seiten für Belege und E-Rechnungen und Download-Links für die Dateien, die Werkzeuge erzeugen. on/off, 1/0, true/false oder yes/no. Aus: keine Seiten, kein sevdesk_upload_request und kein sevdesk_uploads_list; im OAuth-Modus außerdem kein Werkzeug, das eine Datei zum Lesen oder einen Ort zum Speichern braucht. Die PDF- und XML-Werkzeuge und die sevdesk://-Ressourcen bleiben: Ein Client liest Dokumentdateien weiterhin über MCP. |
SEVDESK_HTTP_FILES_MAX_MB | 256 mit Zustandsverzeichnis, sonst 64 | Mebibyte (MiB), die die hochgeladenen Dateien und Download-Links aller Konten zusammen belegen dürfen, 32 bis 4096. Ein Konto darf ein Viertel davon nutzen (mindestens 20 MiB, höchstens die Hälfte); Platz für einen Upload bleibt für Konten frei, die noch keine Dateien halten. Mit Zustandsverzeichnis liegen die Dateien auf der Festplatte, sonst im Speicher. |
SEVDESK_HTTP_FILES_MAX_PER_ACCOUNT | 10 | Reservierte Dateiplätze für Uploads, hochgeladene Dateien und Download-Links zusammen je sevDesk-Konto, eine ganze Zahl von 1 bis 1000. Die separaten Grenzen von 5 wartenden Seiten und insgesamt 1.000 Einträgen gelten weiterhin; die Byte-Kontingente bleiben unverändert. |
SEVDESK_HTTP_FILES_TTL | 30m | Maximale Gültigkeit einer hochgeladenen Datei und eines Download-Links, 5 Minuten bis 24 Stunden. Erfolgreich angehängte Uploads werden früher freigegeben. |
SEVDESK_OAUTH_ACCOUNTS | OAuth, Pflicht: die sevDesk-Konto-IDs, die sich verbinden dürfen, durch Kommas getrennt, oder any (der Start warnt). | |
SEVDESK_OAUTH_CLIENTS | claude.ai | Hosts, die das Metadaten-Dokument eines Clients (seine client_id-URL) liefern dürfen, durch Kommas getrennt, oder any (der Start warnt). |
SEVDESK_OAUTH_ACCESS_TTL | 1h | Laufzeit des Access-Tokens, 5 Minuten bis 24 Stunden. Unter 10 Minuten warnt der Start: Claude erneuert 5 Minuten vor Ablauf und würde dann bei fast jeder Anfrage erneuern. |
SEVDESK_OAUTH_REFRESH_IDLE_TTL | 14d | Ein Refresh-Token, das so lange ungenutzt bleibt, läuft ab; 1 bis 90 Tage. |
SEVDESK_OAUTH_GRANT_TTL | 90d | Laufzeit eines Zugangs ab der Zustimmung; 1 bis 365 Tage. |
Dauern schreibst du als ganze Zahl mit der Einheit s, m, h oder d (90s, 30m, 1h,
14d) oder als bloße Anzahl Sekunden.
Andere Variablen im HTTP-Modus
Die Variablen des stdio-Modus behalten ihre Bedeutung, mit diesen Unterschieden:
SEVDESK_API_TOKEN(_FILE): Pflicht im Bearer-Modus; dort ist es das Konto, das der Server bedient, und das Token, mit dem sich ein Browser an den Seiten des Servers anmeldet (Freigabe-Postfach, Uploads und Downloads). Im OAuth-Modus nicht verwendet (der Start warnt, wenn es gesetzt ist): Jeder Benutzer fügt sein eigenes Token auf der Zustimmungsseite ein.SEVDESK_API_TOKEN_KEYCHAIN,SEVDESK_PROFILE,SEVDESK_PROFILES_PATH: abgelehnt. Der Schlüsselbund des Betriebssystems und lokale Profile sind für lokale Installationen über stdio; ein Container hat keinen Schlüsselbund.SEVDESK_ALLOW,SEVDESK_READ_ONLY: das Höchste, was eine Verbindung bekommen darf. Im OAuth-Modus bekommt jeder Zugang die Schnittmenge mit den Stufen, die auf der Zustimmungsseite angehakt wurden (Stufen je Zugang).SEVDESK_CONFIRM:elicit(der Standard) funktioniert mit Clients, die das Protokoll 2026-07-28 sprechen und Formular-Elicitation unterstützen. Clients aus der Zeit von 2025 können über zustandsloses HTTP nicht gefragt werden; dazu gehört zum Zeitpunkt des Schreibens auch claude.ai. Der Start warnt daher, wennelicitmit der Stufecommitoderexternalkombiniert ist.browsernutzt das Freigabe-Postfach des Servers.SEVDESK_CONFIRM_OPEN: im HTTP-Modus aus, sofern nicht ausdrücklich gesetzt, und dort ohne Wirkung: Freigaben warten im Postfach, das du selbst öffnest.1zusammen mit einem Lauschen außerhalb von Loopback wird abgelehnt.SEVDESK_FILE_DIRS,SEVDESK_OUTPUT_DIR: im OAuth-Modus abgelehnt, weil sich alle Verbindungen die Festplatte des Servers teilen würden. Dateien erreichen die Werkzeuge stattdessen über Upload-Seiten und Download-Links (SEVDESK_HTTP_FILES, standardmäßig an). Der Bearer-Modus behält sie; die Ordner liegen auf dem Server, nicht auf dem Rechner des Clients. Dort kann ein Dateiargument ein Pfad inSEVDESK_FILE_DIRSoder ein Upload sein, undSEVDESK_OUTPUT_DIRhat, wenn gesetzt, Vorrang vor Download-Links: Dateien werden dann auf dem Server gespeichert.SEVDESK_AUDIT_LOG: ein Log für alle Konten; jede Zeile nennt das Konto und den Zugang. Es hält außerdem jeden empfangenen Upload, jeden angelegten Download-Link und jeden Download fest. Im Image ist das Root-Dateisystem schreibgeschützt; lege es also unter/dataab.SEVDESK_RATE_LIMIT: gilt je sevDesk-Konto, geteilt von allen seinen Verbindungen.
Abbrüche und Warnungen beim Start
Der Start verweigert sich unter anderem bei:
--httpohneSEVDESK_HTTP_AUTH;- Bearer-Modus ohne gültiges Bearer-Geheimnis oder ohne sevDesk-Token;
- OAuth ohne
SEVDESK_HTTP_SECRET,SEVDESK_HTTP_PUBLIC_URLoderSEVDESK_OAUTH_ACCOUNTSoder mit einem Geheimnis, das zu kurz oder nicht zufällig genug ist; - einem Lauschen außerhalb von Loopback ohne öffentliche URL oder einer öffentlichen
http://-URL, deren Host nicht Loopback ist; - OAuth zusammen mit
SEVDESK_FILE_DIRSoderSEVDESK_OUTPUT_DIR(die Meldung verweist auf die Upload-Seiten und Download-Links); SEVDESK_API_TOKEN_KEYCHAIN,SEVDESK_PROFILEoderSEVDESK_PROFILES_PATH(nur stdio);SEVDESK_HTTP_FILESmit einem Wert, der kein Schalterwert ist (siehe Tabelle),SEVDESK_HTTP_FILES_MAX_MBaußerhalb von 32–4096,SEVDESK_HTTP_FILES_MAX_PER_ACCOUNT, das keine ganze Zahl von 1 bis 1000 ist, oderSEVDESK_HTTP_FILES_TTLaußerhalb von 5 Minuten bis 24 Stunden;SEVDESK_CONFIRM_OPEN=1bei einem Lauschen außerhalb von Loopback;- einem Zustandsverzeichnis, das nicht beschreibbar ist, einer beschädigten
grants.jsonl, einem Zustandsverzeichnis, das eine andere laufende Instanz nutzt, oder einem Ordnerfiles/darin, der sich nicht leeren lässt; - jedem anderen Wert außerhalb dessen, was die Tabellen oben erlauben, etwa einer Variablen, die
zusammen mit ihrer
_FILE-Variante gesetzt ist,SEVDESK_HTTP_SECRET_PREVIOUSohneSEVDESK_HTTP_SECRET, mehr als zwei Bearer-Geheimnissen, einem relativen Zustandsverzeichnis, einer OAuth-Laufzeit außerhalb ihres Bereichs, einem ungültigen Host- oder Origin-Eintrag oderanygemischt mit IDs oder Hosts.
Der Start warnt (und startet) bei:
SEVDESK_CONFIRM=elicitmit der Stufecommitoderexternal;SEVDESK_OAUTH_ACCOUNTS=any(mit aktiver Dateiübertragung auch, weil der Server dann kurzzeitig die Belege und Exporte jedes verbundenen Kontos hält und einige Konten zusammen seinen Platz für Dateien füllen können) undSEVDESK_OAUTH_CLIENTS=any;- OAuth ohne Zustandsverzeichnis sowie
SEVDESK_API_TOKENoder einem Bearer-Geheimnis im OAuth-Modus; - einem Server- oder Bearer-Geheimnis, das eher wie eine Passphrase als wie zufällige Bytes
aussieht (verwende
generate-secret); - einem Lauschen außerhalb von Loopback mit einer öffentlichen Loopback-URL: Jeder, der den Port erreicht, kann den Server nutzen (siehe den Docker-Schnellstart);
- Dateiübertragung über einfaches http (das Cookie der Browser-Sitzung erreicht jeden Server unter
diesem Hostnamen) und Dateiübertragung ohne Zustandsverzeichnis (Dateien werden im Speicher
gehalten, bis zu
SEVDESK_HTTP_FILES_MAX_MB); SEVDESK_HTTP_FILES_MAX_MB,SEVDESK_HTTP_FILES_MAX_PER_ACCOUNToderSEVDESK_HTTP_FILES_TTLzusammen mitSEVDESK_HTTP_FILES=off(sie haben dann keine Wirkung);SEVDESK_OAUTH_ACCESS_TTLunter 10 Minuten.