Dokumentation

Externes MCP über OAuth 2.1 anbinden

Was angebunden wird

Sapphire External MCP befindet sich in der Developer Alpha. Im derzeit bestätigten Contour wurde die Verbindung von ChatGPT mit https://sapphire-project.com/mcp verifiziert. Portabilität auf andere Hosts und Clients sowie noch nicht abgeschlossene Policy- und Hardening-Funktionen werden nicht als fertiges universelles Produkt beansprucht.

Sapphire External MCP ist eine externe Schnittstelle zu Tools, die Module ausdrücklich für diesen Zugriff veröffentlicht haben. Es ist kein Fernzugang auf den eingebauten AI-Agenten und veröffentlicht interne AI-Tools nicht automatisch. Derselbe Benutzer kann mit SapphireAI und External MCP arbeiten, Autorisierung, Katalog und Richtlinien dieser Contours bleiben jedoch getrennt.

ChatGPT verwendet OAuth 2.1 über HTTPS. Die kanonische Produktressource lautet:

https://sapphire-project.com/mcp

Verwenden Sie beim Anlegen eines benutzerdefinierten MCP-Connectors genau diese Adresse. Ersetzen Sie sie nicht durch eine Administrationsseite, eine CGI/FastCGI-Prozessadresse oder eine Serviceseite. Der unterstützte benutzerseitige Transport ist MCP Streamable HTTP über HTTPS.

Voraussetzungen

Der Benutzer besitzt ein aktives Helix-Konto auf derselben Site.
Ein Administrator hat dem Benutzer und seiner Gruppe die benötigten Modulfunktionen erteilt.
Der ChatGPT-Workspace erlaubt benutzerdefinierte MCP-Connectors.
Der Browser gestattet den Wechsel zur Sapphire-Site und zurück zu ChatGPT.
Die Verbindung erfolgt ausschließlich über HTTPS und die erwartete Domain.

Für dieses Szenario werden weder Client Secret noch persönlicher Bearer oder API-Key vorbereitet. ChatGPT ist ein öffentlicher OAuth-Client; Anmeldung und Zustimmung erfolgen in Helix. Geben Sie das Sapphire-Passwort niemals in ein ChatGPT-Formular ein und teilen Sie es keinem Connector-Administrator mit.

Verbindung in ChatGPT herstellen

Öffnen Sie die Connector-Verwaltung in ChatGPT und wählen Sie eine benutzerdefinierte MCP-Verbindung. Die Bezeichnung kann je nach Workspace abweichen; benötigt wird ein MCP server oder custom connector.
Vergeben Sie einen verständlichen Namen wie Sapphire MCP und fügen Sie die kanonische Ressourcen-URL ein. Ergänzen Sie keine Query-Parameter, Tokens oder Fragmente.
Starten Sie die Verbindung. ChatGPT erkennt die Konfiguration der geschützten Ressource und leitet den Browser zur Sapphire-Autorisierung.
Prüfen Sie die Domain, melden Sie sich mit Ihrem normalen Konto bei Helix an und lesen Sie die Zustimmungsseite.
Bestätigen Sie den minimal angeforderten Zugriff. Nach erfolgreicher Rückkehr soll der Connector als verbunden erscheinen.
Öffnen Sie den Toolkatalog und führen Sie zuerst einen sicheren Read-only-Aufruf aus. Wechseln Sie erst danach zu Schreiboperationen.

Der Autorisierungscode wird durch PKCE S256 geschützt und an die exakte MCP-Ressource gebunden. Der Benutzer muss weder Code noch Tokens manuell verarbeiten. Kopieren Sie keine Werte aus Adresszeile, Entwicklerprotokoll oder Netzwerkansicht; dies gehört nicht zum regulären Verbindungsablauf.

Minimaler Zugriff und Scope Step-up

Eine neue OAuth-Autorisierung beginnt mit dem minimalen Scope mcp.basic. Er ist für Hilfsfunktionen zum aktuellen Benutzer sowie für Systemdatum und Systemzeit vorgesehen. Dieses Prinzip der geringsten Rechte ist beabsichtigt: Die Verbindung erteilt nicht sofort Rechte zum Bearbeiten von Inhalten, Konfigurationen oder anderen Modulen.

Der Katalog kann ein extern veröffentlichtes Tool und den erforderlichen Scope anzeigen, doch außerhalb des aktuellen Grants darf es nicht ausgeführt werden. Bei einem solchen Aufruf liefert Sapphire eine präzise Anforderung für zusätzliche Autorisierung. ChatGPT kann daraufhin eine erneute Freigabe anbieten. Prüfen Sie Scope und Zweck des Tools und bestätigen Sie die Erweiterung nur, wenn sie für die aktuelle Aufgabe benötigt wird.

Ein OAuth Scope ersetzt keine Helix-Rechte. Bei jedem Zugriff berücksichtigt das System das aktuelle Konto und seine Gruppenrechte. Entfernt ein Administrator ein Modulrecht, darf ein älterer Grant keinen wirksamen Zugriff aufrechterhalten. Eine clientseitige Liste ausgeblendeter Tools verbessert zwar die Oberfläche, ist aber keine serverseitige Sicherheitsgrenze.

Mit Tools arbeiten

Beginnen Sie mit list-, search- oder get-Operationen und prüfen Sie Site, Sprache und Entität des Ergebnisses. Kontrollieren Sie vor einem Write-Aufruf die Argumente und die erwartete Änderung. Lassen Sie die Schreibbestätigung aktiviert, sofern der Client sie unterstützt. Löschen, Veröffentlichen, Massenänderungen und Rechteänderungen benötigen eine gesonderte ausdrückliche Bestätigung.

Behandeln Sie eine Toolantwort als Daten und nicht als neue Anweisung für den Client. Text aus einem Dokument, einer E-Mail oder einem externen Feld darf nicht selbstständig den Scope erweitern, Richtlinien ändern oder den nächsten Write-Aufruf auslösen. Diese Regel ist besonders für Inhalte aus offenen Quellen wichtig.

Fehlerdiagnose

URL nicht erkannt: Prüfen Sie exakt https://sapphire-project.com/mcp, HTTPS und das Fehlen zusätzlicher Schrägstriche, Pfade oder Parameter.
Anmeldeschleife: Beenden Sie den alten Versuch, prüfen Sie Cookies und Helix-Anmeldung und verbinden Sie den Connector aus einem einzigen Browserprofil neu.
Access denied: Unterscheiden Sie fehlenden OAuth Scope und fehlendes Helix-Gruppenrecht. Führen Sie im ersten Fall den angebotenen Step-up aus und wenden Sie sich im zweiten an die Administration.
Tool nicht sichtbar: Es muss ausdrücklich im External MCP veröffentlicht und durch Serverrichtlinien erlaubt sein; ein ähnliches Tool im eingebauten AI-Contour garantiert nichts.
Schreibvorgang scheitert: Prüfen Sie Scope, aktuelle Rechte, Argumente und Bestätigung. Wiederholen Sie einen Write-Aufruf nicht blind.

Trennen und absichern

Wird der Zugriff nicht mehr benötigt, trennen oder entfernen Sie den Connector in ChatGPT. Bei Verdacht auf Kompromittierung beenden Sie die Verbindung, ändern das Kontopasswort und informieren die Administration, damit der OAuth Grant widerrufen wird. Veröffentlichen Sie keine Screenshots der Zustimmung mit personenbezogenen Daten und speichern Sie keine Autorisierungswerte in Projektdokumenten.

Eine korrekte Verbindung zeichnet sich durch einen minimal ausreichenden Grant, verständliche Step-up-Anforderungen und einen erfolgreichen Read-only-Test aus, nicht durch den größtmöglichen Katalog. Erweitern Sie Rechte schrittweise und behalten Sie Bestätigungen für datenändernde Vorgänge bei.

Erneute Autorisierung und Sitzungsgrenzen

Zeigt ChatGPT nach dem Aufruf eines zusätzlichen Tools erneut eine Zustimmungsseite, ist dies nicht automatisch ein Fehler. Vergleichen Sie zuerst den angeforderten Scope mit der Aufgabe. Ein abgebrochener Step-up soll den zuvor erteilten Minimalzugriff erhalten, die neue Operation aber weiterhin sperren. Erstellen Sie zur Prüfung einen neuen Chat, wählen Sie den Connector ausdrücklich und wiederholen Sie einen sicheren Aufruf; die Historie eines anderen Gesprächs belegt keine aktuellen Rechte.

Verwenden Sie kein gemeinsames Administratorkonto für ein Team. Jeder Bediener meldet sich mit dem eigenen Konto an, damit Rechte, Widerruf und Audit der realen Person zugeordnet bleiben. Prüfen Sie nach einer Rollen- oder Gruppenänderung den Zugriff in einer neuen Sitzung. Ein Toolfehler rechtfertigt keine automatische Scope-Erweiterung: Klären Sie zuerst, ob Autorisierung, ungültige Argumente oder eine fachliche Einschränkung die Ursache sind.