# Основа коннекторов: код, проверка качества и OAuth

Мастерская помогает подготовить и проверить подключение к внешнему сервису. Их наличие на конкретной установке зависит от завершённого обновления и явной настройки оператором. Доступность конкретного внешнего сервиса зависит от установленного адаптера.

## Виды коннекторов

| Вид | Откуда берутся инструменты |
|---|---|
| Декларативный | Автор описывает HTTP-запросы в версии коннектора. Импорт OpenAPI создаёт черновики для дальнейшей проверки. |
| MCP | Автор получает список инструментов внешнего сервера по протоколу контекста модели (MCP), выбирает нужные и сохраняет снимок версии. |
| Код | Автор выбирает подготовленный сервис и его выпуск. Сервис объявляет инструменты по MCP. Автор выбирает их для версии. |
| BRIDGE | Сервис объявляет неизменяемые инструменты и сохраняет долгие операции; мастерская использует утверждённый снимок. |

Код коннектора выполняется отдельным сервисом, а не в процессе платформы. Автор мастерской не загружает исполняемый код, не задаёт заголовок доступа к сервису и не меняет его ключи. Адрес сервиса, идентификатор сервиса и идентификатор выпуска должны в точности совпадать с настройкой оператора.

Создание коннектора с кодом доступно только после настройки оператора. Сохранённый адрес сам по себе не включает этот механизм. Полученные инструменты проходят общие проверки схем, доступов, лимитов и правил записи. Перед публикацией по-прежнему нужны обязательные проверки через подходящую песочницу.

## Как сервис получает данные входа

Шлюз передаёт сервису только данные, необходимые выбранному способу входа: объявленные поля ключа, имя пользователя и пароль либо действующий токен доступа OAuth. Секрет клиента OAuth, токен обновления и конверт хранилища не передаются.

Передача идёт по HTTPS на закреплённый адрес выпуска. Запросы списка инструментов не содержат данных подключения. Сервис отдельно проверяет ключ шлюза и выпуск, сохраняет данные входа только в контексте текущего вызова и не пишет их в журнал. Ответ и отладочные данные очищаются от переданных секретов.

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

## Дополнительная проверка качества

В мастерской можно задать от пяти до десяти искусственных просьб. Модель выбирает инструмент и аргументы, платформа проверяет их по схеме, затем модель оценивает соответствие описанию. Настоящие инструменты внешнего сервиса при этом не вызываются.

Дополнительную проверку запускают в редакторе версии после отдельного сохранения текущего описания инструментов. На вкладке обязательных проверок доступен только просмотр сохранённого отчёта.

Результат — подсказка автору: «успешно», «есть несоответствия» или «недоступно». Он не заменяет обязательные проверки, не переводит версию в готовое состояние и не разрешает публикацию. Он показывает поведение модели на заданных искусственных примерах, а не качество реальных данных внешнего сервиса.

Отчёт относится к конкретной версии и содержимому её инструментов. Изменение черновика очищает отчёт. Запоздавший ответ не прикрепляется к изменённой версии. При повторном открытии показывается только подходящий проверенный отчёт. Модели не передаются секреты подключения, данные песочницы, журналы сотрудников или настоящие ответы инструментов.

Предложенное моделью описание сначала показывается для просмотра. Кнопка применения переносит его в локальный несохранённый черновик. Сохранение остаётся отдельным действием автора. Запоздавшее предложение после правки черновика не применяется.

Дополнительные проверки и предложение описания требуют уровня «делаю». Уровень «вижу» позволяет прочитать сохранённый отчёт. По умолчанию модель не настроена, поэтому эти действия недоступны. Нет фонового запуска, платного запасного варианта или автоматического выбора другой модели.

## Автоматическая настройка OAuth для MCP

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

Если клиент ещё не настроен, платформа читает сведения о ресурсе и сервере авторизации. При заявленной поддержке публичного документа клиента выбирается CIMD: идентификатором клиента становится HTTPS-адрес неизменяемого документа платформы. Этот способ требует явной поддержки публичного клиента без общего секрета и проверки ключа при обмене кода (PKCE) с методом S256. Он работает и без адреса динамической регистрации.

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

Если CIMD не заявлен, доступная динамическая регистрация DCR остаётся другим способом настройки. Ручная настройка и отдельная команда DCR сохраняются. Ошибка после выбора CIMD не запускает скрытую регистрацию DCR. Для коннектора с кодом эти команды автоматической регистрации не предусмотрены.

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

Смена приложения или публичного адреса требует явной настройки и, при замене действующего входа, подтверждения повторного подключения. Старые публичные документы не переписываются и не исчезают после выключения, вывода из работы или удаления коннектора. Доступность документа не даёт права выполнять инструменты.

Проверка сведений OAuth ограничена одним запуском: не более семи сетевых запросов за 30 секунд, не более 10 секунд и 64 КиБ ответа на запрос. Перенаправления и закрытые адреса запрещены. Документы должны иметь тип JSON и корректный UTF-8. Реализация ориентируется на `MCP Authorization 2025-11-25` и `CIMD draft-00`. Поддержка всех вариантов OAuth не обещается.

## Мастерская BRIDGE и песочница

Создание BRIDGE доступно, только когда оператор настроил разрешённый сервис, а у автора есть право выполнять действия в мастерской. При ошибке загрузки возможностей создание остаётся недоступным. Укажите точные идентификаторы сервиса и выпуска, HTTPS-адрес и разрешённые хосты, затем настройте авторизацию, параметры подключения и лимиты. Ключи шлюза принадлежат оператору и здесь не вводятся.

Обнаружение получает утверждённые объявления инструментов адаптера. Имена, описания, схемы и признаки READ/WRITE доступны только для чтения; ручные инструменты, переопределения и понижение WRITE запрещены, в том числе через JSON-редактор. Проверка качества использует сохранённый утверждённый снимок. Подсказки описаний рекомендательные: изменение объявления требует нового выпуска адаптера и повторного обнаружения. Публикация использует существующие проверки и READ-пробы через подходящую песочницу.

Вызов песочницы может вернуть pending и показать кнопку результата. Автоматический опрос соблюдает задержку сервера; закрытие мастерской прекращает опрос, но не работу. BRIDGE показывает нормализованные результаты без отладочных данных транспорта и учётных данных. Вызовы песочницы бесплатны и используют сессию запустившего оператора отдельно от ключей приложения или Коворка.

| Поверхность мастерской | Право и владение |
|---|---|
| `POST /api/platform/connectors/{id}/versions/{vid}/run` | Сессия платформы, право коннекторов `do`; подходящая готовая песочница; явное подтверждение WRITE |
| `GET /api/platform/connectors/{id}/sandbox/operations/{operationId}` | Сессия платформы, право коннекторов `do`; тот же запустивший оператор и текущая авторизация песочницы |

GET результата возвращает тот же ответ песочницы: счётчики времени/размера и `result`, с `kind: "pending"` и метаданными операции либо окончательным `ok`/`error`. Переподключение, удаление песочницы или утрата прав скрывают старый результат нейтральным `CONNECTOR_OPERATION_NOT_FOUND`. Это не V1 API для ключа приложения.

## Подготовка оператором и возврат версии

До включения создания BRIDGE оператор готовит проверенный HTTPS-сервис, точный разрешённый выпуск, ротацию ключей шлюза и надёжное хранение заданий. Ключи сервиса и настройки установки не входят в публичные объявления инструментов. Комплектный адаптер — **FAKE test fixture**, а не готовый промышленный мост ERP или 1С.

При возврате версии сохраняют задания, результаты и историю защиты от повторов и используют сборку, понимающую существующие виды коннекторов. Отключение создания не отменяет принятую работу и не делает старую сборку совместимой. Восстановление проверяет неопределённые внешние эффекты до повтора записи; очистка удаляет истёкшее содержимое, сохраняя защиту на весь срок повторов.

## Смотрите также

- [Шлюз коннекторов (MCP)](/docs/connectors-mcp)
- [Инструменты хоста коннекторов](/docs/connectors-host)