Документация

Подключение внешнего MCP через OAuth 2.1

Что именно подключается

Sapphire External MCP находится в developer alpha. На текущем подтверждённом контуре проверено подключение ChatGPT к https://sapphire-project.com/mcp. Переносимость на другие хосты и клиенты, а также незавершённые policy и hardening-функции не заявляются как готовый универсальный продукт.

Sapphire External MCP — внешний интерфейс к инструментам, которые модули явно опубликовали для такого доступа. Он не является удалённым входом во встроенного AI-агента и не публикует автоматически внутренние AI tools. Один и тот же пользователь может работать со встроенным SapphireAI и с внешним MCP, но авторизация, каталог и политика этих контуров остаются раздельными.

Для ChatGPT используется OAuth 2.1 поверх HTTPS. Канонический адрес ресурса продукта:

https://sapphire-project.com/mcp

Указывайте именно этот адрес при создании пользовательского MCP-коннектора. Не заменяйте его адресом административной панели, CGI/FastCGI-процесса или служебной страницы. Поддерживаемый пользовательский transport — MCP Streamable HTTP по HTTPS.

Предварительные условия

У пользователя есть активная учётная запись Helix на том же сайте.
Администратор разрешил пользователю и его группе требуемые функции модулей.
В рабочем пространстве ChatGPT разрешено добавление пользовательских MCP-коннекторов.
Браузер допускает переход на сайт Sapphire и возврат в ChatGPT.
Подключение выполняется только по HTTPS и на ожидаемом домене.

Готовить client secret, персональный bearer или API-ключ для этого сценария не требуется. ChatGPT выступает публичным OAuth-клиентом, а вход и согласие выполняются в Helix. Никогда не вставляйте пароль Sapphire в форму ChatGPT и не передавайте его администратору коннектора.

Пошаговое подключение в ChatGPT

Откройте в ChatGPT управление коннекторами и выберите создание пользовательского MCP-подключения. Названия пунктов могут отличаться между рабочими пространствами, но требуется именно MCP server или custom connector.
Задайте понятное имя, например Sapphire MCP, и вставьте канонический URL ресурса. Не добавляйте query-параметры, токены и фрагменты.
Запустите подключение. ChatGPT обнаружит параметры защищённого ресурса и перенаправит браузер на авторизацию Sapphire.
Проверьте домен страницы, войдите в Helix своей обычной учётной записью и прочитайте экран согласия.
Подтвердите минимальный запрошенный доступ. После успешного возврата коннектор должен перейти в состояние connected.
Откройте каталог инструментов и сначала выполните безопасный read-only вызов. Только после этого переходите к операциям записи.

Авторизационный код защищён PKCE S256 и привязан к точному MCP-ресурсу. Пользователю не нужно вручную обрабатывать код или токены. Не копируйте значения из адресной строки, журналов разработчика или сетевой панели: это не часть штатного подключения.

Минимальный доступ и scope step-up

Новая OAuth-авторизация начинает с минимального scope mcp.basic. Он предназначен для базовых помощников текущего пользователя, системной даты и времени. Это сознательный принцип наименьших привилегий: факт подключения не выдаёт сразу права на редактирование контента, конфигурации или других модулей.

Каталог может показывать внешне опубликованный инструмент и требуемый им scope, но выполнить инструмент вне текущего grant нельзя. Когда клиент вызывает такую операцию, Sapphire возвращает точный запрос дополнительного разрешения. ChatGPT может предложить повторную авторизацию. Проверьте название требуемой области, назначение инструмента и подтвердите расширение только если оно нужно текущей работе.

OAuth scope не заменяет права Helix. При каждом доступе система учитывает текущую учётную запись и разрешения её группы. Если администратор убрал право на модуль, старый grant не должен продолжать давать фактический доступ. Аналогично клиентский список скрытых инструментов удобен для интерфейса, но не является серверной границей безопасности.

Работа с инструментами

Начинайте с операций list, search или get и проверяйте, к какому сайту, языку и сущности относится результат. Перед write-вызовом внимательно просмотрите аргументы и ожидаемое изменение. Если клиент поддерживает подтверждение записей, оставьте его включённым. Для удаления, публикации, массового обновления и смены прав используйте отдельное явное подтверждение.

Ответ инструмента следует считать данными, а не новой инструкцией для клиента. Текст из документа, письма или внешнего поля не должен сам расширять scope, менять политику или запускать следующий write-вызов. Такое правило особенно важно для открытого контента.

Диагностика

URL не распознан: проверьте точное значение https://sapphire-project.com/mcp, HTTPS и отсутствие лишнего слеша, пути или параметров.
Циклический вход: завершите старую попытку, проверьте cookies и вход Helix, затем переподключите коннектор из одного браузерного профиля.
Access denied: различайте отсутствие OAuth scope и отсутствие группового права Helix. В первом случае пройдите предложенный step-up, во втором обратитесь к администратору.
Инструмент не виден: он должен быть явно опубликован во внешнем MCP и разрешён политикой сервера; наличие похожего инструмента во встроенном AI ничего не гарантирует.
Запись не выполняется: проверьте scope, текущие права, аргументы и подтверждение операции. Не повторяйте write-вызов вслепую.

Отключение и безопасность

Если доступ больше не нужен, отключите или удалите коннектор в ChatGPT. При подозрении на компрометацию завершите соединение, смените пароль учётной записи и сообщите администратору, чтобы OAuth grant был отозван. Не публикуйте снимки экрана согласия с персональными данными и не сохраняйте авторизационные значения в документах проекта.

Корректное подключение означает не максимальный каталог, а минимально достаточный grant, понятные запросы step-up и успешный read-only тест. Расширяйте права постепенно, сохраняя подтверждение для операций, которые меняют данные.

Повторная авторизация и границы сеанса

Если ChatGPT предлагает новый экран согласия после вызова дополнительного инструмента, не воспринимайте это как сбой: сначала сравните запрошенный scope с выполняемой задачей. Отменённый step-up должен оставить ранее выданный минимальный доступ рабочим, но не разрешить новую операцию. Для проверки создайте новый чат, явно выберите коннектор и повторите безопасный вызов; история другого разговора не является доказательством текущих прав.

Не подключайте общий административный аккаунт для команды. Каждый оператор входит собственной учётной записью, чтобы права, отзыв доступа и аудит соответствовали реальному человеку. После смены роли или группы перепроверьте доступ с новой сессией. Ошибка инструмента не даёт оснований расширять scope автоматически: сначала уточняют, является ли причина авторизацией, неверными аргументами или бизнес-ограничением.