Fehlersuche im Fernzugriff
Probleme, die nur mit --http auftreten: Clients verbinden, Proxys, Uploads, Zustimmung und das
Zustandsverzeichnis. Für Token-Fehler, fehlende Werkzeuge, Bestätigungen und andere Probleme, die
auch über stdio auftreten, siehe Fehlersuche.
Verbinden
claude.ai meldet, den Server nicht erreichen oder sich nicht verbinden zu können. claude.ai verbindet sich aus dem Internet; prüfe also von außerhalb deines Netzes:
curl https://<host>/healthzantwortet{"status":"ok"};curl https://<host>/.well-known/oauth-protected-resource/mcpliefert JSON mit deiner öffentlichen URL;- die URL des Connectors ist genau
SEVDESK_HTTP_PUBLIC_URLplus/mcp; - der Server läuft im OAuth-Modus (im Bearer-Modus antworten die Metadaten-Dokumente mit 404, und claude.ai kann sich nicht verbinden);
- das Zertifikat gilt für den Host, und nichts vor dem Server verlangt eine Anmeldung.
Eine 401-Schleife: Die Zustimmung klappt, dann bittet claude.ai erneut um Verbindung. Das
Access-Token gilt nur für <public URL>/mcp, ist mit dem aktuellen Geheimnis versiegelt und wird
gegen den Zugangsspeicher geprüft.
- Die URL des Connectors weicht von der öffentlichen URL ab (anderer Host,
httpstatthttps, ein abschließender Schrägstrich oder ein anderer Pfad): Korrigiere die URL oderSEVDESK_HTTP_PUBLIC_URL. - Das Geheimnis hat sich seit der Zustimmung geändert, oder zwei Instanzen mit verschiedenen Geheimnissen bedienen dieselbe URL.
- Das Zustandsverzeichnis ist nicht dauerhaft, ein Neustart hat die Zugänge also vergessen. Binde dort ein Volume ein.
- Mehr als eine Instanz: Ein Zugang existiert nur im Speicher der Instanz, die ihn angelegt hat.
Das Modell sagt, der Client könne nicht um Bestätigung gebeten werden. Der Client hat über HTTP
keine Formular-Elicitation (claude.ai zum Zeitpunkt des Schreibens). Setze
SEVDESK_CONFIRM=browser und verwende das Freigabe-Postfach.
Hinter einem Proxy
Anfragen werden wegen Host oder Origin abgelehnt. Der Server nimmt nur den Host seiner
öffentlichen URL an. Die meisten Proxys (Caddy, Fly, Render, Railway, cloudflared) reichen den
ursprünglichen Host weiter; sendet deiner einen eigenen (einen internen Namen wie
localhost:8080), stelle ihn so ein, dass er den ursprünglichen Host weiterreicht, oder nimm
diesen Namen in SEVDESK_HTTP_ALLOWED_HOSTS auf. Ein Client, der einen anderen Origin-Header als
den öffentlichen Origin sendet, braucht ihn in SEVDESK_HTTP_ALLOWED_ORIGINS; ein MCP-Client, der
in einer Webseite auf einem anderen Origin läuft, kann gar nicht funktionieren, weil /mcp kein
CORS unterstützt. /healthz wird nie wegen seines Hosts abgelehnt. Beide Ablehnungen antworten mit 403.
Viele Antworten mit 429, oder jede Anfrage mit der IP des Proxys protokolliert. Setze hinter
einem Proxy SEVDESK_HTTP_TRUST_PROXY auf die Anzahl der Proxys, die etwas an X-Forwarded-For
anhängen; sonst teilen sich alle Clients die Ratenbegrenzung der Adresse des Proxys. Setze den
Wert nie höher als die tatsächliche Anzahl: Clients könnten sonst ihre eigene IP-Adresse wählen.
Eine 429, deren Meldung das sevDesk-Konto nennt, ist eine andere Grenze: Für dieses Konto laufen
bereits 8 Anfragen an /mcp, gleich von welchen Adressen (Grenzen).
Sie vergeht, sobald eine davon endet.
Antworten hängen oder kommen alle auf einmal. Ein Proxy puffert die gestreamten Antworten.
Schalte die Pufferung für den Server ab: Caddy flush_interval -1 (die Compose-Vorlage tut das),
nginx proxy_buffering off.
Uploads scheitern hinter einem Proxy. Die Upload-Seite antwortet mit den eigenen Worten des Servers; alles andere kommt vom Proxy.
- „Size missing“ (411): Der Proxy hat den Upload ohne
Content-Lengthweitergeleitet (in Chunks). Lass ihn dasContent-Lengthdes Browsers weiterreichen oder Request-Bodys puffern: nginx tut das standardmäßig (proxy_request_buffering on); Caddy reicht es unverändert weiter. - Eine 413-Seite des Proxys, nicht das „File too large“ des Servers: Die Body-Grenze des Proxys
liegt unter der des Servers (etwas über 20 MiB für eine Datei, bis zum verbleibenden Byte-Anteil
des Kontos für mehrere Dateien auf einer Seite; siehe Reverse Proxys).
nginx:
client_max_body_size 65m;beim Standard mit Zustandsverzeichnis, oder201mfür die absolute Obergrenze (Standard 1 MB). Caddy hat keine Grenze, sofern du keine setzt. - Eine Zeitüberschreitung (408) bei großen Dateien über eine langsame Verbindung: Der Body muss innerhalb von 90 Sekunden eintreffen, mit durchschnittlich mindestens 16 KB/s, und darf nie 10 Sekunden lang pausieren. Ein Proxy, der Request-Bodys puffert (nginx standardmäßig), reicht sie mit voller Geschwindigkeit weiter.
Uploads und Download-Links
Ein Link aus dem Chat zeigt das Anmeldeformular. Der Browser hat keine Sitzung dieses Kontos: Es ist nicht der Browser, in dem du zugestimmt hast (die Claude-Apps öffnen Links unter Umständen in ihrem eigenen Browser), die 12 Stunden sind vorbei, du hast dich abgemeldet, oder er ist an einem anderen Konto angemeldet. Melde dich in diesem Formular mit dem sevDesk-API-Token des Kontos an; es bringt dich zur Seite zurück.
„Upload page not found“ oder „File not found“. Der Link ist unbekannt, gehört zu einem anderen sevDesk-Konto, wurde bereits erfolgreich angehängt, oder der Server wurde inzwischen neu gestartet (ein Neustart macht jeden Upload und jeden Link ungültig). „Expired“ und „used up“ bedeuten, was sie sagen. Bitte das Modell um einen neuen Upload-Link oder darum, die Datei erneut zu erzeugen.
„No space for the file“ (507), oder das Modell meldet, dass die Grenze erreicht ist. Die
Uploads und Links des Kontos füllen sein Viertel von SEVDESK_HTTP_FILES_MAX_MB, die Konten
zusammen füllen den Platz, oder das Konto hat SEVDESK_HTTP_FILES_MAX_PER_ACCOUNT erreicht
(Standard 10). Erfolgreiches Anhängen gibt Uploads sofort frei. Bei einer erreichten Anzahlgrenze
wartest du bis zum Ablaufzeitpunkt des Kontos, den die Ablehnung nennt, oder erhöhst diese
Einstellung; bei Platzmangel wartest du auf den Ablauf von Dateien oder erhöhst
SEVDESK_HTTP_FILES_MAX_MB. „Server busy“ (503) heißt, dass gerade zwei andere Uploads eintreffen,
„Upload in progress“ (503), dass ein anderer Upload desselben Kontos eintrifft; versuche es gleich
noch einmal (Grenzen und Laufzeiten).
Zustimmung
Die Zustimmungsseite lehnt das Konto oder den Client ab. Sie nennt die Konto-ID oder den
Client-Host; nimm ihn in SEVDESK_OAUTH_ACCOUNTS oder SEVDESK_OAUTH_CLIENTS auf und starte neu,
wenn du ihn zulassen willst. Einen Eintrag zu entfernen und neu zu starten widerruft auch die
bestehenden Zugänge dieses Kontos oder Clients bei ihrer nächsten Nutzung und beendet die
Browser-Sitzungen des Kontos.
Die Zustimmungsseite meldet zu viele Verbindungen. Der Zugangsspeicher ist voll. grants list
zeigt die Zugänge; widerrufe die, die niemand nutzt (Befehle).
Zustandsverzeichnis und Instanzen
Das Zustandsverzeichnis ist nicht beschreibbar. Das Image läuft als uid 65532. Ein benanntes
Docker-Volume übernimmt seinen Eigentümer aus dem Image und funktioniert einfach; ein Bind-Mount
oder eine Plattform-Disk mit root als Eigentümer braucht die Lösung unter
Volumes und der Container-Benutzer. Ohne
beschreibbares Volume setzt du SEVDESK_HTTP_STATE_DIR auf einen leeren Wert: Der Zustand wird
dann im Speicher gehalten, und jeder Neustart meldet alle Clients ab.
Der Start meldet, dass eine andere Instanz das Zustandsverzeichnis nutzt. Nur ein laufender Server darf es nutzen. Nach einem Absturz gilt die alte Sperre nach 30 Sekunden als veraltet, und der nächste Start übernimmt sie. Laufen wirklich zwei (eine zweite Replica oder Machine), reduziere auf eine. Ein laufender Server, der seine Sperre von einem anderen übernommen findet, vertraut seinem Zugangsspeicher nicht mehr: OAuth-Anfragen scheitern mit einem Serverfehler (Clients behalten ihre Tokens), und der Prozess beendet sich, sodass die Plattform ihn neu startet.
Der Start bricht ab oder warnt. Der Start meldet alle Probleme auf einmal; was jedes bedeutet, steht unter Abbrüche und Warnungen beim Start.