Connessione dell'MCP esterno tramite OAuth 2.1

Cosa viene connesso esattamente

Sapphire External MCP è in developer alpha. Nel perimetro attualmente verificato è stata confermata la connessione di ChatGPT a https://sapphire-project.com/mcp. La portabilità verso altri host e client, così come le funzioni di policy e hardening non ancora completate, non vengono presentate come un prodotto universale pronto.

Sapphire External MCP è un'interfaccia esterna per gli strumenti che i moduli hanno pubblicato esplicitamente per questo tipo di accesso. Non è un ingresso remoto all'agente IA integrato e non pubblica automaticamente gli AI tools interni. Uno stesso utente può lavorare con SapphireAI integrato e con l'MCP esterno, ma autorizzazione, catalogo e politica dei due perimetri restano separati.

Per ChatGPT viene usato OAuth 2.1 su HTTPS. L'indirizzo canonico della risorsa del prodotto è:

https://sapphire-project.com/mcp

Indicate esattamente questo indirizzo quando create il connettore MCP personalizzato. Non sostituitelo con l'indirizzo del pannello amministrativo, di un processo CGI/FastCGI o di una pagina di servizio. Il transport utente supportato è MCP Streamable HTTP su HTTPS.

Prerequisiti

• L'utente dispone di un account Helix attivo sullo stesso sito.
• L'amministratore ha autorizzato per l'utente e il relativo gruppo le funzioni dei moduli necessarie.
• Lo spazio di lavoro ChatGPT consente l'aggiunta di connettori MCP personalizzati.
• Il browser permette di passare al sito Sapphire e tornare a ChatGPT.
• La connessione viene eseguita esclusivamente tramite HTTPS e sul dominio previsto.

Per questo scenario non occorre preparare un client secret, un bearer personale o una chiave API. ChatGPT agisce come client OAuth pubblico, mentre accesso e consenso avvengono in Helix. Non inserite mai la password Sapphire in un modulo ChatGPT e non comunicatela all'amministratore del connettore.

Connessione passo passo in ChatGPT

1. Aprite in ChatGPT la gestione dei connettori e scegliete di creare una connessione MCP personalizzata. I nomi delle voci possono variare tra gli spazi di lavoro, ma deve trattarsi specificamente di un MCP server o custom connector.
2. Assegnate un nome chiaro, ad esempio Sapphire MCP, e inserite l'URL canonico della risorsa. Non aggiungete parametri query, token o frammenti.
3. Avviate la connessione. ChatGPT rileverà i parametri della risorsa protetta e reindirizzerà il browser all'autorizzazione Sapphire.
4. Controllate il dominio della pagina, accedete a Helix con il vostro account abituale e leggete la schermata di consenso.
5. Confermate l'accesso minimo richiesto. Dopo il ritorno riuscito, il connettore deve passare allo stato connected.
6. Aprite il catalogo degli strumenti ed eseguite inizialmente una chiamata read-only sicura. Passate alle operazioni di scrittura solo in seguito.

Il codice di autorizzazione è protetto da PKCE S256 e vincolato alla risorsa MCP esatta. L'utente non deve gestire manualmente il codice o i token. Non copiate valori dalla barra degli indirizzi, dai log di sviluppo o dal pannello di rete: non fanno parte della normale procedura di connessione.

Accesso minimo e scope step-up

Una nuova autorizzazione OAuth inizia con lo scope minimo mcp.basic. È destinato agli assistenti di base dell'utente corrente e alla data e ora di sistema. Si tratta di un'applicazione deliberata del principio del privilegio minimo: il semplice collegamento non concede subito diritti di modifica di contenuti, configurazione o altri moduli.

Il catalogo può mostrare uno strumento pubblicato esternamente e lo scope da esso richiesto, ma non è possibile eseguirlo al di fuori del grant corrente. Quando il client richiama tale operazione, Sapphire restituisce una richiesta precisa dell'autorizzazione aggiuntiva. ChatGPT può proporre una nuova autorizzazione. Controllate il nome dell'ambito richiesto e lo scopo dello strumento, quindi confermate l'estensione solo se necessaria al lavoro corrente.

Lo OAuth scope non sostituisce i diritti Helix. A ogni accesso il sistema considera l'account corrente e le autorizzazioni del relativo gruppo. Se l'amministratore rimuove il diritto a un modulo, un vecchio grant non deve continuare a fornire accesso effettivo. Analogamente, l'elenco degli strumenti nascosti lato client è utile per l'interfaccia, ma non costituisce un confine di sicurezza lato server.

Uso degli strumenti

Iniziate con operazioni list, search o get e verificate a quale sito, lingua ed entità appartiene il risultato. Prima di una chiamata write, esaminate attentamente gli argomenti e la modifica prevista. Se il client supporta la conferma delle scritture, lasciatela attiva. Per eliminazione, pubblicazione, aggiornamento massivo o modifica dei diritti, usate una conferma esplicita separata.

La risposta di uno strumento deve essere considerata un dato, non una nuova istruzione per il client. Il testo proveniente da un documento, un messaggio o un campo esterno non deve ampliare autonomamente lo scope, cambiare la politica o avviare la chiamata write successiva. Questa regola è particolarmente importante per i contenuti aperti.

Diagnostica

• URL non riconosciuto: verificate il valore esatto https://sapphire-project.com/mcp, HTTPS e l'assenza di barre, percorsi o parametri aggiuntivi.
• Accesso ciclico: terminate il vecchio tentativo, controllate i cookie e l'accesso a Helix, quindi riconnettete il connettore da un solo profilo del browser.
• Access denied: distinguete l'assenza di OAuth scope dall'assenza di diritti di gruppo Helix. Nel primo caso completate lo step-up proposto, nel secondo contattate l'amministratore.
• Strumento non visibile: deve essere pubblicato esplicitamente nell'MCP esterno e consentito dalla politica del server; la presenza di uno strumento simile nell'IA integrata non garantisce nulla.
• La scrittura non viene eseguita: controllate scope, diritti correnti, argomenti e conferma dell'operazione. Non ripetete alla cieca una chiamata write.

Disconnessione e sicurezza

Se l'accesso non serve più, disconnettete o rimuovete il connettore in ChatGPT. Se sospettate una compromissione, terminate la connessione, cambiate la password dell'account e informate l'amministratore affinché lo OAuth grant venga revocato. Non pubblicate screenshot della schermata di consenso contenenti dati personali e non conservate valori di autorizzazione nei documenti del progetto.

Una connessione corretta non significa avere il catalogo massimo, ma disporre di un grant minimo sufficiente, richieste di step-up comprensibili e un test read-only riuscito. Estendete i diritti gradualmente, mantenendo la conferma per le operazioni che modificano i dati.

Nuova autorizzazione e limiti della sessione

Se ChatGPT propone una nuova schermata di consenso dopo la chiamata a uno strumento aggiuntivo, non consideratelo un guasto: confrontate innanzitutto lo scope richiesto con l'attività in corso. Uno step-up annullato deve lasciare funzionante l'accesso minimo già concesso, ma non autorizzare la nuova operazione. Per verificarlo, create una nuova chat, selezionate esplicitamente il connettore e ripetete una chiamata sicura; la cronologia di un'altra conversazione non dimostra i diritti correnti.

Non collegate un account amministrativo condiviso per l'intero team. Ogni operatore accede con il proprio account, affinché diritti, revoca dell'accesso e audit corrispondano alla persona reale. Dopo un cambio di ruolo o gruppo, verificate nuovamente l'accesso da una nuova sessione. Un errore dello strumento non giustifica l'estensione automatica dello scope: occorre prima stabilire se la causa sia l'autorizzazione, argomenti errati o un vincolo di business.