Technik für Fortgeschrittene: Server, Anmeldung, Automationen

Diese Seite ist für alle, die genauer wissen wollen, wie der Sprachassistent technisch angebunden ist. Für den Alltag brauchst du sie nicht.

Die zwei Server im Vergleich

Protokollfassungen des gehosteten Servers: 2025-06-18, 2025-03-26, 2024-11-05.

Anmeldung am gehosteten Server (OAuth 2.1)

• Ein Aufruf ohne Token bekommt 401 mit WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp". Damit startet der Client die Anmeldung selbst.
• Metadaten: /.well-known/oauth-protected-resource und /.well-known/oauth-authorization-server.
• Client-Registrierung: dynamisch (Dynamic Client Registration) über POST /mcp/oauth/register. Weiterleitungsadressen müssen https:// sein, oder http://localhost. Alternativ ein „Client ID Metadata Document“ (CIMD): Die client_id ist dann eine https-Adresse, unter der der Client Name und Weiterleitungsadressen veröffentlicht (so arbeitet „Claudes veröffentlichte Identität verwenden“). PetWorkers ruft sie nur auf der Zustimmungsseite ab: nur https, nur öffentliche Ziele, ohne Weiterleitung, höchstens 5 KB, 24 Stunden zwischengespeichert. Nur öffentliche Clients (token_endpoint_auth_method: none).
• Zustimmung: /mcp/oauth/authorize, nur mit response_type=code und PKCE S256. Der Mitarbeiter meldet sich mit seinem PetWorkers-Konto an und klickt auf Erlauben.
• Token: POST /mcp/oauth/token mit authorization_code oder refresh_token. Zugangsmarke 1 Stunde, Erneuerungsmarke 30 Tage, bei jeder Nutzung neu (einmal verwendbar).
• Bereiche (Scopes): mcp:read und mcp:write. Welche ausgegeben werden, entscheidet allein der Zugang unter System → MCP, nicht die Anfrage des Clients.
• Gespeichert werden Marken nur als SHA-256-Prüfsumme. Zugang entfernen oder trennen entwertet alle Marken des Mitarbeiters sofort.

Was ein Werkzeug intern tut

Jedes Werkzeug ist ein Aufruf der Schnittstelle /api/v1 mit dem Lese- oder Schreibschlüssel des Mitarbeiters. Es gelten dieselben Rechte, Sperren und Tempo-Grenzen wie für jeden anderen Aufruf. Es gibt keine zweite Rechteprüfung.

• Lesewerkzeuge nutzen Pfade wie /_ueberblick, /_termine, /_freie_zeiten, /_belegung, /_anfragen.
• Schreibwerkzeuge nutzen Aktionen wie POST /coachingappointments/anlegen oder POST /groupappointments/anlegen.
• Jedes Schreibwerkzeug ist ohne ausfuehren: true ein Probelauf. trotzdem: true speichert trotz gemeldeter Überschneidung oder Dublette.
• Lesewerkzeuge tragen den Hinweis readOnlyHint. Clients können sie dadurch ohne Rückfrage ausführen.
• Antworten sind meist kurze Textzeilen mit der Zeile „Heute: …“ am Anfang. So kann der Assistent „nächsten Dienstag“ richtig auflösen.

Die Pfade im Einzelnen: Assistent: Tagesüberblick, Termine anlegen, Kundenakte.

Claude Code mit dem gehosteten Server

Statt des Pakets kannst du Claude Code auch direkt mit /mcp verbinden. Dann liegt kein Schlüssel auf dem Rechner:

claude mcp add --transport http -s user petworkers https://deine-instanz.petworkers.app/mcp

Starte danach Claude Code, gib /mcp ein und wähle PetWorkers. Die Anmeldung läuft im Browser wie bei ChatGPT. Unter System → MCP erscheint die Verbindung in der Spalte Browser-Verbindungen.

Das Node-Paket im Detail

• Umgebungsvariablen: PETWORKERS_URL (Pflicht, mit https://), PETWORKERS_API_KEY (Pflicht, Leseschlüssel), PETWORKERS_API_KEY_WRITE (optional; ohne ihn meldet das Paket keine Schreibwerkzeuge an).
• Prüfen: node server.js --pruefen oder npm run check.
• Das Paket speichert nichts auf der Platte und hat keine eigene Logik.
• Herunterladen nur über System → MCP deiner Instanz. So passt das Paket immer zu deinem PetWorkers.

Zum Ausprobieren der Werkzeuge ohne Claude eignet sich der „MCP Inspector“ des MCP-Projekts. Starte ihn im Paketordner:

npx @modelcontextprotocol/inspector \
  -e PETWORKERS_URL=https://deine-instanz.petworkers.app \
  -e PETWORKERS_API_KEY=DEIN-LESESCHLUESSEL \
  node server.js

Automationen ohne Chat

Für feste Abläufe, zum Beispiel mit n8n, Make oder eigenen Skripten, brauchst du kein MCP. Rufe die Schnittstelle direkt mit einem eigenen API-Schlüssel auf:

• Schnittstelle (API): Einstieg
• Werkzeuge wie n8n und Make anbinden
• Berechtigungen und Firewall

Lege für Automationen einen eigenen Schlüssel an, nicht die MCP-Schlüssel. Sonst trifft „Zugang entfernen“ unter System → MCP auch deine Automation.

Wenn etwas nicht klappt

• 401 mit invalid_token — Token abgelaufen oder entwertet. Der Client muss die Erneuerung bzw. Anmeldung neu durchlaufen.
• invalid_client „Unbekannter Client. …“ — Die Registrierung fehlt. Client neu registrieren lassen (Verbindung im Assistenten neu anlegen).
• invalid_client „Die Client-Beschreibung …“ — Das CIMD-Dokument war nicht abrufbar oder ungültig (Grund steht in der Meldung). Dynamische Registrierung nutzen.
• invalid_target — Der resource-Parameter zeigt nicht auf …/mcp dieser Instanz.
• 429 — Tempo-Grenze oder Absender-Sperre. Den Kopf Retry-After beachten.
• 405 bei GET /mcp — Richtig so: Der Server hat keinen Ereignisstrom. Nur POST.