Scout Dokumentation Zur Anwendung
Schnittstellen / MCP-Schnellstart

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.

  1. 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.

  2. MCP-URL eintragen: Im Client Streamable HTTP wählen und die vom Betreiber bestätigte HTTPS-Adresse mit dem Pfad /mcp eintragen. https://DEINE-BESTAETIGTE-SCOUT-DOMAIN/mcp ist nur ein Domain-Platzhalter, keine bestätigte Installation. Domain vor Verwendung ersetzen.

  3. Zusätzlichen Header setzen: URL und Header in getrennte Felder eintragen:

    Feld Eintrag
    Header-Name Authorization
    Header-Wert Bearer DEIN_DIENSTSCHLUESSEL

    Zwischen Bearer und Schlüssel steht genau ein Leerzeichen. Keine zusätzlichen Anführungszeichen in die Header-Felder eintragen.

  4. Verbindung prüfen: Verbindung herstellen, Werkzeuge laden und list_municipalities aufrufen: Das Verzeichnis zeigt die freigegebenen Gemeinden.

  5. 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.