Een externe MCP aansluiten via OAuth 2.1

Wat er precies wordt aangesloten

Sapphire External MCP bevindt zich in developer alpha. In de huidige bevestigde omgeving is de verbinding van ChatGPT met https://sapphire-project.com/mcp geverifieerd. Overdraagbaarheid naar andere hosts en clients en onvoltooide policy- en hardeningfuncties worden niet als gereed universeel product gepresenteerd.

Sapphire External MCP is een externe interface naar hulpmiddelen die modules expliciet voor deze toegang hebben gepubliceerd. Het is geen externe ingang naar de ingebouwde AI-agent en publiceert interne AI tools niet automatisch. Dezelfde gebruiker kan met de ingebouwde SapphireAI en met de externe MCP werken, maar authenticatie, catalogus en beleid van die omgevingen blijven gescheiden.

Voor ChatGPT wordt OAuth 2.1 via HTTPS gebruikt. Het canonieke adres van de productresource is:

https://sapphire-project.com/mcp

Vul precies dit adres in wanneer u een aangepaste MCP-connector maakt. Vervang het niet door het adres van het beheerpaneel, een CGI/FastCGI-proces of een servicepagina. Het ondersteunde gebruikerstransport is MCP Streamable HTTP via HTTPS.

Voorwaarden

• De gebruiker heeft een actief Helix-account op dezelfde website.
• De beheerder heeft de vereiste modulefuncties toegestaan voor de gebruiker en diens groep.
• De ChatGPT-werkruimte staat het toevoegen van aangepaste MCP-connectors toe.
• De browser staat navigatie naar de Sapphire-site en terug naar ChatGPT toe.
• De verbinding wordt uitsluitend via HTTPS en op het verwachte domein uitgevoerd.

Voor dit scenario hoeft u geen client secret, persoonlijke bearer of API-sleutel voor te bereiden. ChatGPT treedt op als openbare OAuth-client; aanmelden en toestemming geven gebeuren in Helix. Vul uw Sapphire-wachtwoord nooit in een ChatGPT-formulier in en geef het niet aan de connectorbeheerder.

Stapsgewijs aansluiten in ChatGPT

1. Open in ChatGPT het connectorbeheer en kies het maken van een aangepaste MCP-verbinding. Namen van menuopties kunnen per werkruimte verschillen, maar het moet gaan om MCP server of custom connector.
2. Geef een duidelijke naam, bijvoorbeeld Sapphire MCP, en plak de canonieke resource-URL. Voeg geen queryparameters, tokens of fragmenten toe.
3. Start de verbinding. ChatGPT ontdekt de parameters van de beveiligde resource en leidt de browser om naar de Sapphire-autorisatie.
4. Controleer het domein van de pagina, meld u met uw gewone account aan bij Helix en lees het toestemmingsscherm.
5. Bevestig de minimaal gevraagde toegang. Na een geslaagde terugkeer moet de connector de status connected krijgen.
6. Open de hulpmiddelencatalogus en voer eerst een veilige read-only-aanroep uit. Ga pas daarna over op schrijfbewerkingen.

De autorisatiecode is beveiligd met PKCE S256 en gebonden aan de exacte MCP-resource. De gebruiker hoeft de code of tokens niet handmatig te verwerken. Kopieer geen waarden uit de adresbalk, ontwikkelaarslogboeken of het netwerkpaneel: dat hoort niet bij de normale aansluiting.

Minimale toegang en scope step-up

Een nieuwe OAuth-autorisatie begint met de minimale scope mcp.basic. Die is bedoeld voor basishulpmiddelen van de huidige gebruiker en voor systeemdatum en -tijd. Dit is een bewuste toepassing van minimale rechten: verbinding maken geeft niet meteen rechten om inhoud, configuratie of andere modules te wijzigen.

De catalogus kan een extern gepubliceerd hulpmiddel en de vereiste scope tonen, maar een hulpmiddel buiten de huidige grant kan niet worden uitgevoerd. Wanneer de client zo'n bewerking aanroept, retourneert Sapphire een nauwkeurig verzoek om aanvullende toestemming. ChatGPT kan hernieuwde autorisatie aanbieden. Controleer de naam van het vereiste bereik en het doel van het hulpmiddel en bevestig de uitbreiding alleen als die nodig is voor het huidige werk.

Een OAuth scope vervangt de Helix-rechten niet. Bij iedere toegang houdt het systeem rekening met het huidige account en de rechten van de groep. Als een beheerder het recht op een module intrekt, mag een oude grant geen feitelijke toegang blijven geven. Ook is een lijst met verborgen hulpmiddelen in de client handig voor de interface, maar geen beveiligingsgrens van de server.

Met hulpmiddelen werken

Begin met list-, search- of get-bewerkingen en controleer op welke site, taal en entiteit het resultaat betrekking heeft. Bekijk vóór een write-aanroep zorgvuldig de argumenten en de verwachte wijziging. Als de client bevestiging van schrijfbewerkingen ondersteunt, laat die dan ingeschakeld. Gebruik een afzonderlijke expliciete bevestiging voor verwijderen, publiceren, bulkupdates en het wijzigen van rechten.

Beschouw het antwoord van een hulpmiddel als gegevens, niet als een nieuwe instructie voor de client. Tekst uit een document, bericht of extern veld mag niet zelf een scope uitbreiden, beleid wijzigen of een volgende write-aanroep starten. Deze regel is bijzonder belangrijk bij openbare inhoud.

Diagnose

• URL wordt niet herkend: controleer de exacte waarde https://sapphire-project.com/mcp, HTTPS en de afwezigheid van een extra slash, pad of parameters.
• Aanmeldlus: beëindig de oude poging, controleer cookies en de Helix-aanmelding en verbind de connector vervolgens opnieuw vanuit één browserprofiel.
• Access denied: maak onderscheid tussen een ontbrekende OAuth scope en een ontbrekend Helix-groepsrecht. Doorloop in het eerste geval de aangeboden step-up en neem in het tweede geval contact op met de beheerder.
• Hulpmiddel is niet zichtbaar: het moet expliciet in de externe MCP zijn gepubliceerd en door serverbeleid zijn toegestaan; een vergelijkbaar hulpmiddel in de ingebouwde AI garandeert niets.
• Schrijven lukt niet: controleer scope, huidige rechten, argumenten en bevestiging van de bewerking. Herhaal een write-aanroep niet blindelings.

Loskoppelen en beveiliging

Schakel de connector uit of verwijder hem in ChatGPT wanneer toegang niet meer nodig is. Verbreek bij een vermoeden van misbruik de verbinding, wijzig het accountwachtwoord en meld dit bij de beheerder zodat de OAuth grant wordt ingetrokken. Publiceer geen afbeeldingen van het toestemmingsscherm met persoonsgegevens en bewaar geen autorisatiewaarden in projectdocumenten.

Een correcte aansluiting betekent niet een maximale catalogus, maar een minimaal toereikende grant, begrijpelijke step-up-verzoeken en een geslaagde read-only-test. Breid rechten geleidelijk uit en behoud bevestiging voor bewerkingen die gegevens wijzigen.

Opnieuw autoriseren en sessiegrenzen

Als ChatGPT na een aanroep van een aanvullend hulpmiddel een nieuw toestemmingsscherm aanbiedt, beschouw dat dan niet meteen als storing: vergelijk eerst de gevraagde scope met de uitgevoerde taak. Een geannuleerde step-up moet de eerder verleende minimale toegang laten werken, maar mag de nieuwe bewerking niet toestaan. Maak voor controle een nieuwe chat, selecteer de connector expliciet en herhaal een veilige aanroep; de geschiedenis van een ander gesprek bewijst de huidige rechten niet.

Sluit geen gedeeld beheerdersaccount voor een team aan. Iedere operator meldt zich met een eigen account aan, zodat rechten, intrekking en audit met de werkelijke persoon overeenkomen. Controleer toegang na een rol- of groepswijziging opnieuw in een nieuwe sessie. Een hulpmiddelfout is geen reden om een scope automatisch uit te breiden: bepaal eerst of de oorzaak autorisatie, onjuiste argumenten of een bedrijfsbeperking is.