Dokumentacja

Podłączenie zewnętrznego MCP przez OAuth 2.1

Co dokładnie jest podłączane

Sapphire External MCP znajduje się w developer alpha. W obecnym potwierdzonym środowisku zweryfikowano połączenie ChatGPT z https://sapphire-project.com/mcp. Przenośność na inne hosty i klientów, a także nieukończone funkcje polityki i wzmacniania (hardening) nie są deklarowane jako gotowy uniwersalny produkt.

Sapphire External MCP to zewnętrzny interfejs do narzędzi, które moduły jawnie opublikowały dla takiego dostępu. Nie jest to zdalne logowanie do wbudowanego agenta AI ani automatyczne publikowanie wewnętrznych narzędzi AI. Ten sam użytkownik może pracować z wbudowanym SapphireAI i z zewnętrznym MCP, ale uwierzytelnianie, katalog i polityka tych środowisk pozostają oddzielne.

Dla ChatGPT używany jest OAuth 2.1 przez HTTPS. Kanoniczny adres zasobu produktu:

https://sapphire-project.com/mcp

Podaj dokładnie ten adres przy tworzeniu niestandardowego łącznika MCP. Nie zastępuj go adresem panelu administracyjnego, procesu CGI/FastCGI ani strony usługowej. Obsługiwany transport użytkownika to MCP Streamable HTTP przez HTTPS.

Wymagania wstępne

Użytkownik musi posiadać aktywne konto Helix na tej samej stronie.
Administrator zezwolił użytkownikowi i jego grupie na wymagane funkcje modułów.
W przestrzeni roboczej ChatGPT dozwolone jest dodawanie niestandardowych łączników MCP.
Przeglądarka musi umożliwiać przejście na stronę Sapphire i powrót do ChatGPT.
Połączenie odbywa się tylko przez HTTPS i na oczekiwanym domenie.

Nie jest wymagane przygotowywanie sekretu klienta, osobistego bearer'a ani klucza API dla tego scenariusza. ChatGPT działa jako publiczny klient OAuth, a logowanie i zgoda odbywają się w Helix. Nigdy nie wprowadzaj hasła Sapphire do formularza ChatGPT ani nie przekazuj go administratorowi łącznika.

Krok po kroku podłączanie w ChatGPT

Otwórz w ChatGPT zarządzanie łącznikami i wybierz utworzenie niestandardowego połączenia MCP. Nazwy elementów mogą się różnić między przestrzeniami roboczymi, ale wymagany jest dokładnie serwer MCP lub łącznik niestandardowy (custom connector).
Nadaj zrozumiałą nazwę, np. Sapphire MCP, i wklej kanoniczny URL zasobu. Nie dodawaj parametrów zapytania, tokenów ani fragmentów.
Uruchom połączenie. ChatGPT wykryje parametry zasobu zabezpieczonego i przekieruje przeglądarkę do uwierzytelnienia Sapphire.
Sprawdź domenę strony, zaloguj się do Helix swoim zwykłym kontem i przeczytaj ekran zgody.
Potwierdź minimalnie żądany dostęp. Po pomyślnym powrocie łącznik powinien przejść w stan connected.
Otwórz katalog narzędzi i najpierw wykonaj bezpieczne wywołanie tylko do odczytu (read-only). Dopiero po tym przejdź do operacji zapisu.

Kod uwierzytelniający jest zabezpieczony PKCE S256 i powiązany z dokładnym zasobem MCP. Użytkownik nie musi ręcznie przetwarzać kodu ani tokenów. Nie kopiuj wartości z paska adresu, logów dewelopera ani panelu sieciowego: to nie jest część standardowego połączenia.

Minimalny dostęp i scope step-up

Nowe uwierzytelnienie OAuth rozpoczyna się od minimalnego zakresu (scope) mcp.basic. Jest przeznaczony dla podstawowych asystentów bieżącego użytkownika, systemowej daty i czasu. To świadoma zasada najmniejszych przywilejów: fakt połączenia nie nadaje automatycznie praw do edycji treści, konfiguracji ani innych modułów.

Katalog może pokazywać zewnętrznie opublikowane narzędzie i wymagany dla niego zakres (scope), ale wykonanie narzędzia poza bieżącym grantem nie jest możliwe. Gdy klient wywołuje taką operację, Sapphire zwraca dokładny zapytanie o dodatkowe uprawnienie. ChatGPT może zasugerować ponowne uwierzytelnienie. Sprawdź nazwę wymaganej domeny, przeznaczenie narzędzia i potwierdź rozszerzenie tylko wtedy, gdy jest to konieczne dla bieżącej pracy.

Zakres OAuth nie zastępuje praw Helix. Przy każdym dostępie system uwzględnia aktualne konto oraz uprawnienia jego grupy. Jeśli administrator usunął prawo do modułu, stary grant nie powinien nadal zapewniać faktycznego dostępu. Podobnie lista klientów ukrytych narzędzi jest wygodna dla interfejsu, ale nie stanowi granicy bezpieczeństwa po stronie serwera.

Praca z narzędziami

Zacznij od operacji list, search lub get i sprawdź, do jakiej strony, języka i encji odnosi się wynik. Przed wywołaniem zapisu (write) uważnie przejrzyj argumenty i oczekowaną zmianę. Jeśli klient obsługuje potwierdzenie zapisów, pozostaw tę opcję włączoną. Do usunięcia, publikacji, masowej aktualizacji i zmiany praw używaj osobnego jawnego potwierdzenia.

Odpowiedź narzędzia należy traktować jako dane, a nie jako nową instrukcję dla klienta. Tekst z dokumentu, e-maila lub zewnętrznego pola nie powinien sam rozszerzać zakresu (scope), zmieniać polityki ani uruchamiać kolejnego wywołania zapisu. Zasada ta jest szczególnie ważna dla treści publicznych.

Diagnostyka

URL nie rozpoznany: sprawdź dokładną wartość https://sapphire-project.com/mcp, HTTPS i brak zbędnego ukośnika, ścieżki lub parametrów.
Cykl wprowadzania: Zakończ poprzednią próbę, sprawdź pliki cookie i logowanie do Helix, a następnie ponownie podłącz łącznik z jednego profilu przeglądarki.
Dostęp zabroniony: Rozróżniaj brak zakresu OAuth od braku uprawnienia grupowego w Helix. W pierwszym przypadku przejdź przez zaproponowany step-up, w drugim skontaktuj się z administratorem.
Narzędzie nie widoczne: Musi być jawnie opublikowane w zewnętrznym MCP i dozwolone polityką serwera; obecność podobnego narzędzia we wbudowanym AI nic nie gwarantuje.
Zapis nie wykonany: Sprawdź zakres (scope), bieżące uprawnienia, argumenty i potwierdzenie operacji. Nie powtarzaj wywołania zapisu ślepo.

Odłączanie i bezpieczeństwo

Jeśli dostęp nie jest już potrzebny, odłącz lub usuń łącznik w ChatGPT. W przypadku podejrzenia kompromitacji zakończ połączenie, zmień hasło konta i powiadom administratora o wycofaniu grantu OAuth. Nie publikuj zrzutów ekranu ze zgodą na dane osobowe ani nie przechowuj wartości uwierzytelniające w dokumentach projektu.

Poprawne podłączenie oznacza nie maksymalny katalog, ale minimalnie wystarczający grant, zrozumiałe zapytania step-up i pomyślny test tylko do odczytu. Rozszerzaj uprawnienia stopniowo, zachowując potwierdzenie dla operacji zmieniających dane.

Ponowne uwierzytelnienie i granice sesji

Jeśli ChatGPT proponuje nowy ekran zgody po wywołaniu dodatkowego narzędzia, nie traktuj tego jako błąd: najpierw porównaj żądany zakres (scope) z wykonywanym zadaniem. Anulowany step-up powinien pozostawić wcześniej nadany minimalny dostęp aktywny, ale nie zezwalać na nową operację. Aby sprawdzić, utwórz nowy czat, jawnie wybierz łącznik i powtórz bezpieczne wywołanie; historia innej rozmowy nie jest dowodem bieżących uprawnień.

Nie podłącz wspólnego konta administracyjnego dla zespołu. Każdy operator loguje się własnym kontem, aby prawa, wycofanie dostępu i audyt odpowiadały realnej osobie. Po zmianie roli lub grupy sprawdź dostęp ponownie nową sesją. Błąd narzędzia nie daje podstaw do automatycznego rozszerzania zakresu: najpierw wyjaśnia się, czy przyczyna leży w uwierzytelnianiu, błędnych argumentach, czy ograniczeniu biznesowym.