Scout MCP einrichten
Claude mit OAuth verbinden#
Nach separat freigegebener CHM-STAGE-Bereitstellung wird in claude.ai ein URL-only-Custom-Connector mit genau dieser MCP-Adresse angelegt:
https://hugoscout.chm.stg.sternwald.cloud/mcp
Keine Client-ID, kein Secret und kein eigener Header sind manuell einzutragen. Claude entdeckt die OAuth-Endpunkte, registriert sich als öffentlicher Client und öffnet die normale Scout-Anmeldung. Falls ein Superadmin zur Admin-Anmeldung aufgefordert wird, dort anmelden und den Connector erneut öffnen. Anschließend die angezeigte kontogebundene Dienstfreigabe bewusst bestätigen oder ablehnen. Ein Scout-Sitzungscookie allein gewährt keinen MCP-Zugriff.
Die Implementierung ist lokal isoliert geprüft; die echte CHM-/Claude-Verbindung ist noch nicht abgenommen. Betreiberaktion und Prüfprotokoll stehen unter CHM-OAuth-Abnahme.
Schnellstart mit Scout-API-Key#
Mit Scout kann ein MCP-Client freigegebene Gemeindemitteilungen recherchieren, Fragen beantworten und gespeicherte Originaltexte lesen.
-
Schlüssel beschaffen: Einen Admin oder Superadmin um einen Dienstzugang bitten. Beide Rollen erstellen ihn unter Verwaltung → API & MCP. Schlüssel und Anschlussbeispiele erscheinen dort nur einmal; sicher übernehmen.
-
MCP-URL eintragen: Im Client Streamable HTTP wählen und die vom Betreiber bestätigte HTTPS-Adresse mit dem Pfad
/mcpeintragen.https://DEINE-BESTAETIGTE-SCOUT-DOMAIN/mcpist nur ein Domain-Platzhalter, keine bestätigte Installation. Domain vor Verwendung ersetzen. -
Zusätzlichen Header setzen: URL und Header in getrennte Felder eintragen:
Feld Eintrag Header-Name AuthorizationHeader-Wert Bearer DEIN_DIENSTSCHLUESSELZwischen
Bearerund Schlüssel steht genau ein Leerzeichen. Keine zusätzlichen Anführungszeichen in die Header-Felder eintragen. -
Verbindung prüfen: Verbindung herstellen, Werkzeuge laden und
list_municipalitiesaufrufen: Das Verzeichnis zeigt die freigegebenen Gemeinden. -
Erste Recherchefrage stellen: Zum Beispiel „Welche Mitteilungen gibt es zum Thema Schulhaus? Suche in meinen freigegebenen Gemeinden und nenne die Quellen.“ Vor wörtlichen Zitaten das Original lesen lassen.
Client-Voraussetzung: Streamable HTTP mit OAuth Authorization Code / PKCE S256 oder mit eigenem Authorization-Bearer-Header. Der API-Key-Weg bleibt unverändert. Die echte Claude-Abnahme einer bereitgestellten Version steht aus.
Was kann ich mit Scout tun?#
| Werkzeug | Anwenderaufgabe |
|---|---|
list_municipalities |
Freigegebene Gemeinden finden, bevor gezielt recherchiert wird. |
find_documents |
Passende Mitteilungen und Quellen zu einem Thema finden. Keine vollständige Bestandsliste. |
ask_scout |
Eine KI-Antwort aus freigegebenen Quellen mit nummerierten Belegen erhalten. |
get_document |
Gespeicherten Originalwortlaut oder eine gespeicherte PDF-Seite lesen und Zitate prüfen. |
Scout-Links öffnen den Artikel in Scout und benötigen weiterhin die eigene
Browseranmeldung (aktiver Scout-Anbieter: Cognito oder Clerk). Ein Dienstschlüssel meldet niemanden im
Browser an; ein erfolgreicher MCP-Aufruf beweist keine Browsersitzung.
KI-Antworten sind keine Originalbelege. PDF-Seiten nur zitieren, wenn der Abruf
einen tatsächlichen Seitenbeleg (pdf_extracted) liefert.
Häufige Probleme#
| Problem | Hilfe |
|---|---|
| Schlüssel fehlt oder ist ungültig (401) | Header-Name, Leerzeichen und vollständigen Schlüssel prüfen. Kein Schlüssel in die URL. Browsercookies helfen hier nicht. |
| Zugang widerrufen (403) | Admin oder Superadmin kontaktieren; widerrufene Schlüssel durch einen neuen Zugang ersetzen. |
| Freigabe eingeschränkt oder geändert | Gemeindeverzeichnis prüfen. Gemeinde- und Veröffentlichungsdatumsgrenzen gelten für jeden Aufruf; Filter erweitern die Freigabe nicht. Bei 403 Admin oder Superadmin kontaktieren. |
| Keine passenden Treffer | Nur freigegebene Gemeinden recherchieren, Suchbegriff/Zeitraum anpassen. Die Suche garantiert keine Vollständigkeit. |
| Dienstlimit erreicht (429) | Mindestens 60 Sekunden warten und weniger Anfragen parallel senden. Kein sofortiges Wiederholen in Schleife. |
| Dienst technisch nicht verfügbar (503) | Später erneut versuchen; bei anhaltendem Fehler Betreiber informieren. |
| Client verlangt OAuth oder hat keine Header-Felder | Den OAuth-Connector mit der MCP-URL einrichten; Discovery-Konfiguration und Bereitstellungsstand prüfen. |
Technische Referenz und Betreiberinformationen#
Der gemeinsame Datenvertrag steht in Recherche-API, die Betriebs- und Prüfnachweise in Betreiberprüfung. Die Webansicht bietet außerdem OpenAPI JSON und YAML in ihrer Navigation. Die folgenden Abschnitte richten sich an Integration und Betrieb, nicht an den normalen Einstieg.
list_municipalities liefert höchstens 1000 Gemeinden pro Seite (limit, offset,
has_more, next_offset); name_filter grenzt das Verzeichnis ein. Auch bei
unbeschränkter Freigabe bleiben Artikel-/Dokumentergebnisse begrenzt.
Dienstzugänge und Remote-Protokoll#
Dienstschlüssel können Admins und Superadmins unter Verwaltung → API & MCP
anlegen und nach Bestätigung widerrufen. Browser und Betreiber-CLI verwalten
dieselben persistenten Freigaben. Ein neuer Schlüssel wird nur einmal angezeigt;
verlorene Schlüssel werden widerrufen und ersetzt, nicht wieder abgerufen.
Standard ist „Alle Gemeinden“, einschließlich künftig registrierter Gemeinden.
Eine Einschränkung auf bestimmte Gemeinden muss ausdrücklich aktiviert werden
und mindestens eine Gemeinde enthalten; bestehende Schlüssel bleiben unverändert
eingeschränkt. Optionale Datumsgrenzen beschränken
die Veröffentlichungsdaten, nicht die Lebensdauer des Zugangs. Derselbe Schlüssel
gilt für REST und MCP. Der Abschnitt „Dienstzugänge in der Verwaltung“ in
Recherche-API beschreibt Einmalanzeige, Kopieren und den sicheren Umgang
mit verlorenen Anlageantworten. Die MCP-Anleitung ist unter /v1/mcp-docs
auch ohne Browsersitzung erreichbar.
In der Betreiber-CLI ist die Reichweite immer bewusst anzugeben:
--municipalities 100023,100024 bleibt eine explizite Einschränkung.
Alternativ gibt --all-municipalities alle heutigen und künftig registrierten
Gemeinden frei. Die Optionen schließen einander aus; Weglassen ist ein Fehler.
Die private Ausgabedatei und alle übrigen Sicherheitsanforderungen bleiben gleich.
Streamable HTTP an /mcp auf der vom Betreiber bestätigten HTTPS-Installation.
Clients verwenden entweder einen Scout-API-Key oder ein Scout-OAuth-Access-Token
im Authorization-Bearer-Header. Öffentliche Clientregistrierung ist auf den
exakten Claude-Callback begrenzt; es werden keine Scout-Konten angelegt.
Browsercookies ersetzen keines der beiden Dienst-Credentials.
Der gepflegte offizielle Python-MCP-SDK verarbeitet Protokoll, Initialisierung
und Toolaufrufe. Stateless JSON-Antworten; kein SSE-Reconnect-/Sitzungstoken
als Ersatz für Authentifizierung. Jeder Request und jeder Toolaufruf prüft
die aktuelle Dienstfreigabe. Widerruf gilt auch nach früherem initialize.
MCP läuft über eine lazy pro Worker gestartete ASGI→WSGI-Brücke in der bestehenden Flask-/Gunicorn-Anwendung; keine neue öffentliche Portfreigabe, kein zusätzlicher Deploymentdienst. Der bestehende ausgehende Archiv-MCP-Client bleibt unverändert.
OAuth-Konfiguration und Sicherheitsregeln#
Alle Discovery-URLs, der Issuer, die Ressourcenbindung und die MCP-Hostfreigabe
verwenden dieselbe validierte SCOUT_PUBLIC_ORIGIN, für CHM:
SCOUT_PUBLIC_ORIGIN=https://hugoscout.chm.stg.sternwald.cloud
Kein Pfad, abschließender Slash, Query, Fragment oder Benutzerinfo; HTTPS ist
Pflicht. Ohne gültige Origin bleiben OAuth-Endpunkte mit 503 geschlossen.
Öffentliche URLs stammen nie aus Host oder X-Forwarded-*. Der MCP-SDK behält
DNS-Rebinding-Schutz und exakte öffentliche Hosts; fremde Hosts/Ports bleiben
gesperrt. Loopback-Ports dienen nur dem bestehenden lokalen Transport.
Origin prüfen, ohne Scout zu starten
Im Projektverzeichnis, mit dem vorhandenen Python des betroffenen Deployment-Kontexts:
python -m src.mcp_config --expected-origin https://hugoscout.chm.stg.sternwald.cloud
Die Prüfung benötigt nur die Python-Standardbibliothek. Sie startet weder
Scout, MCP-Transport, Tunnel noch Datenbankmigrationen und ruft kein Netzwerk
auf. JSON meldet valid, missing, invalid oder mismatch; nur valid
endet mit Exitcode 0. Der eingelesene Wert wird nie ausgegeben, auch nicht bei
versehentlich enthaltener Benutzerinfo. scope: current_process_only bedeutet:
Dies prüft ausschließlich den aufrufenden Prozess, nicht bereits laufende Worker.
Ein erfolgreicher Workspace-Test belegt keine Deployment-Konfiguration.
Der reguläre Launcher meldet künftig vor Diensten und Datenbankarbeit eine
Warnung bei fehlender/ungültiger Origin, ohne Browser und REST zu blockieren.
Bei CHM ist die oben angegebene exakte Origin im tatsächlich ausgelieferten STAGE-Kontext zu hinterlegen, nicht nur in Development. Erst nach gesonderter Betreiberfreigabe ändern und alle betroffenen Worker kontrolliert neu laden: Die SDK-Hostliste wird pro Worker beim ersten MCP-Aufruf übernommen; eine nachträgliche Umgebungsänderung repariert bereits gestartete Transporte nicht. Keine Host-Wildcard, zweite Hostliste oder Ableitung aus Forwarded-Headern ergänzen. Ein vorgeschalteter Proxy muss den bestätigten Host unverändert weiterreichen; das ist am tatsächlichen Gateway/Backend zu prüfen, nicht durch clientseitig gesetzte Forwarded-Header zu ersetzen.
Vor der Korrektur den ausgelieferten Stand, die Konfigurationsklassifikation
je Worker und die Proxy-Hostweitergabe getrennt erfassen. Nach der freigegebenen
Korrektur alle drei Discovery-Adressen erneut prüfen (200), danach /mcp
ohne Credential (401 mit resource_metadata) und mit separat autorisiertem
Zugang (initialize, tools/list, begrenzte Recherche). Fehlt eine dieser
Freigaben oder der interaktive Claude-Zugang, bleibt die externe Abnahme offen.
Der OAuth-Callback erlaubt nicht automatisch Origin: https://claude.ai
für den HTTP-Transport.
SCOUT_AUTH_PROVIDER und die vorhandene Anbieter-Konfiguration bleiben
unverändert. Bei Cognito muss SCOUT_AUTH_ALLOWED_ORIGINS diese exakte
CHM-Origin enthalten; die vorhandenen Cognito-Callback-/Logout-URLs müssen für
CHM freigegeben sein. SESSION_SECRET bleibt die vorhandene stabile
Sitzungssignatur über alle Worker. OAuth benötigt kein eigenes Client-Secret,
keine zusätzliche Datenbank und keinen externen OAuth-Anbieter. Keine dieser
Umgebungsvariablen wurde durch diese Implementierung gesetzt.
| Endpunkt | Vertrag |
|---|---|
GET /.well-known/oauth-protected-resource |
Identisch zur Variante /mcp; Ressource <origin>/mcp, Authorization-Server <origin>, Bearer nur im Header, Scope scout. |
GET /.well-known/oauth-protected-resource/mcp |
Geschützte Ressource, auch Ziel der 401-Challenge. |
GET /.well-known/oauth-authorization-server |
Issuer und authorize/token/register aus derselben Origin; Code, Refresh, S256, öffentliche Clients ohne Secret. |
POST /mcp/oauth/register |
JSON mit redirect_uris: ["https://claude.ai/api/mcp/auth_callback"]; optional token_endpoint_auth_method: "none", grant_types: ["authorization_code","refresh_token"], response_types: ["code"], scope: "scout", client_name. Kein Secret. Andere Metadaten/Redirects werden abgewiesen. |
GET /mcp/oauth/authorize |
client_id, exakt registrierte redirect_uri, response_type=code, S256-Challenge samt Methode; optional scope=scout, resource=<origin>/mcp, unverändert zurückgelieferter state. Andere Scopes/Ressourcen werden abgewiesen. |
GET/POST /mcp/oauth/consent |
Kurzlebige browsergebundene Freigabe nach echter Scout-Sitzungsprüfung; CSRF, Origin und Konto werden bei Zustimmung erneut geprüft. Kein generischer Login-Rücksprung zu anderen MCP-Endpunkten. |
POST /mcp/oauth/token |
Form-URL-encoded: Code mit client_id, redirect_uri, code_verifier; Refresh mit client_id, refresh_token. resource darf nur <origin>/mcp sein; falls weggelassen bleibt diese einzige Ressource fest gebunden. |
Anmeldevorgänge laufen nach 10 Minuten, Codes nach 2 Minuten, Access-Tokens nach 15 Minuten ab. Refresh-Tokens rotieren bei jedem Tausch; die Familie endet absolut nach 30 Tagen, ohne Verlängerung durch Rotation. Öffentliche Clients gelten 90 Tage. Codes sind einmalig; erneute Verwendung eines gültig gebundenen verbrauchten Codes oder Refresh-Tokens widerruft die gesamte Dienstfreigabe. Ein verlorener Austauschabschluss darf daher nicht blind wiederholt werden: bei Replay den Connector neu autorisieren.
Clients und Vorgänge sind instanzweit auf 1000 bzw. 2000 begrenzt, Bodygrößen auf 8 KiB. Höchstens 20 Clientregistrierungen pro voller UTC-Stunde werden datenbankweit zugelassen. Überschreitungen ergeben 429 mit Retry-After; bei ausgeschöpftem Stundenbudget bis zur nächsten Stunde warten. Abgelaufene Vorgänge, Clients, Codes (nach einem zusätzlichen Tag) und Tokenfamilien werden bei Registrierung/Autorisierungsbeginn in begrenzten 100er-Blöcken entfernt. Verbleibende Tokenfamilien behalten Replay-Nachweise bis zu ihrem absoluten Ablauf. Ohne neue Vorgänge erfolgt keine automatische Aufräumarbeit. Abgelaufene OAuth-Freigaben bleiben weitere 30 Tage als Verwaltungsnachweise erhalten und werden dann ebenfalls in begrenzten Blöcken zusammen mit ihrem Dienstfreigabeeintrag entfernt. Bestehende API-Keys sind von dieser Bereinigung ausgeschlossen.
Freigaben stehen als OAuth · Claude · Konto … unter Verwaltung → API & MCP
und in python -m src.service_keys list. Dort beziehungsweise per CLI widerrufen;
damit enden Access und Refresh gemeinsam. Neue Freigaben erlauben dynamisch alle
Gemeinden. Die aktuelle Kontorichtlinie kennt lokale Rollen, aber keine eigenen
Gemeinde-/Datumsfelder; bestehende Dienstbeschränkungen werden niemals verändert.
Bei jedem Zugriff und nach langer Werkzeugverarbeitung werden Ablauf,
lokale Kontozulassung (einschließlich lokaler Clerk-Sperren beziehungsweise
Cognito-Admin-Zuordnung für Superadmins) und gespeicherte Dienstgrenzen erneut geprüft.
REST und stdio akzeptieren weiterhin ausschließlich Scout-API-Keys.
Persistenz erfolgt ausschließlich in der bestehenden Scout-Datenbank:
additive, vom vorhandenen Schema-Fingerprint erfasste Tabellen
mcp_oauth_* plus getrennte Freigaben in public_service_keys.
Keine Laufzeit-DDL im OAuth-Request. Die Schemaanwendung erfolgt erst im
separat freigegebenen regulären Startvorlauf. Token-/Codewerte liegen nur
gehasht vor; Provider-Tokens werden nicht weitergereicht.
OAuth-Antworten tragen no-store und eine restriktive CSP. Die Zustimmungsseite
verwendet Referrer-Policy: same-origin, damit Chromium den Origin-Nachweis im
gleichursprünglichen Formular-POST erhält, aber keinen Referrer an Claude
weitergibt. Andere OAuth-Antworten tragen no-referrer. form-action erlaubt
neben 'self' ausschließlich den festgelegten Claude-Callback, damit der
Browser auch die Weiterleitung nach Zustimmung oder Ablehnung zulässt.
Die anwendungseigenen Werkzeug-/Gunicorn-Zugriffslogs entfernen OAuth-Queries;
der Betreiber muss auch vorgelagerte Proxy-Logs ohne Query-/Header-/Body-Geheimnisse
konfigurieren. Kein Token in Chat, Logs oder Abnahmeprotokoll.
Für nicht authentifizierte /mcp-Aufrufe gilt 401 mit
WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp"
und „Gültiges OAuth-Token oder Scout-API-Key erforderlich.“
403, 429 und 503 bleiben für Rechtefehler, Limits und technische Störungen erhalten.
Eine MAD-/V6.0.a-Implementierung war weder als Datei noch im verfügbaren Git-Verlauf zugänglich. Dies ist keine Übernahme dieser Implementierung, sondern eine Ergänzung auf dem bestehenden offiziellen MCP-SDK und Scouts vorhandenen Login-, Datenbank- und Dienstfreigabekomponenten.
Lokales stdio (nur Betreiber)#
Nur explizit konfigurierte, vertrauenswürdige lokale Prozesse:
SCOUT_STDIO_KEY_FILE=/privates-verzeichnis/scout-client.key python -m src.mcp_server
Die Schlüsseldatei gehört dem Prozessbenutzer, hat keine Gruppen-/Weltrechte
und darf kein Symlink sein. Der Betreiber erstellt sie über
python -m src.service_keys create (Details im gemeinsamen Vertrag).
Kein Schlüssel in argv, URL oder Client-Log. Die Datei liegt außerhalb von Git.
Arbeitsverzeichnis ist das Scout-Projekt. Der Prozess braucht die bestehende
DB-/KI-Konfiguration und Zugriff auf gespeicherte Medien; es gibt keinen
impliziten unbegrenzten Lokalzugang. Die DB-Schemaeinrichtung erfolgt wie
beim normalen App-Start, nicht bei jeder stdio-Verbindung.
Bei der Aurora-Konfiguration muss der vorhandene Scout-Datenbank-Tunnel
bereits laufen; stdio startet weder einen weiteren Tunnel noch Medien-Restore.
Fehlende/gesperrte Freigabe sperrt auch stdio. stdout enthält ausschließlich
MCP-Protokoll, Startfehler stehen generisch auf stderr.
Remote und stdio verwenden denselben Dienst und dieselben Schemas, Texte, Status, Projektionen, Belegnummern und Fortsetzungen. Lokale Missbrauchsgrenzen gelten pro Prozess, nicht global.
Client-Aktualisierung und Datenvertrag#
Tool-Metadaten nach separat freigegebener Veröffentlichung ggf. erneuern.
In neuem Chat rohen Toolinhalt kontrollieren:
content[].text ist bei Recherche/Antwort/Originalabruf menschenlesbar,
NICHT mehr JSON. Maschinen verwenden structuredContent; nur das
Gemeindeverzeichnis behält zusätzlich JSON-Text. isError unterscheidet
Toolfehler von normalen Inhaltsstatus.
Client muss beide Artikel-IDs aus derselben Quelle übernehmen und bei PDF
zusätzlich deren document_id. Standardfelder der Suche enthalten scout_url,
aber nicht municipality_id: für Folgeabfragen diese ausdrücklich anfordern.
fields:["article_id"] ändert nur strukturierte Treffer, nicht die lesbare
Quellenzeile. Suchgrenzen sind keine Vollständigkeitsgarantie. Für Fortsetzung
next UND next_documents_offset auswerten, nicht allein truncated.
Scout-Links verlangen eigenständige Anmeldung im Browser. Die bestehende Anmeldung (in Stage Clerk) bleibt unverändert; Dienstzugänge bleiben getrennt.