REST API и MCP

Используйте REST API и MCP, если операции Gateway должны быть повторяемыми, иметь явного исполнителя и не зависеть от браузера одного оператора. Владелец автоматизации поддерживает клиент, владельцы ресурсов согласуют его границы, а операторы платформы отвечают за восстановление среды выполнения. Успех — подтверждённый результат продукта с долговременными доказательствами, а не только принятый HTTP-запрос или завершённый вызов инструмента.

REST API предоставляет документированные операции с ресурсами и использует сеанс, API-токен или OAuth в зависимости от сценария. Удалённый MCP предоставляет ориентированные на задачи инструменты с теми же областями, валидацией, правами по тарифу и журналом аудита.

Автоматизация должна:

использовать отдельную идентичность с минимальными правами;
считать 202 или создание Task принятием работы и затем опрашивать долговременное состояние;
повторять только идемпотентные операции или следовать контракту повтора конкретной операции;
раздельно обрабатывать 401, 403, 409, 422 и сбои отключённой ноды;
не разбирать текст UI, если существует структурированное поле API;
фиксировать идентификаторы ресурсов и запросов без записи секретов.

Для точных схем запросов и ответов используйте документ OpenAPI, который отдаёт работающий экземпляр Gateway. Версия схемы должна совпадать с автоматизируемым экземпляром; не копируйте тела запросов из другого релиза. Руководства продукта описывают порядок ресурсов и эксплуатационные последствия, которые невозможно выразить только схемой.

Аутентификация и обнаружение

Выберите сеанс, API-токен или OAuth client в соответствии с вызывающей стороной. Клиенты удалённого MCP авторизуются через OAuth и обнаруживают ориентированные на задачи инструменты, отфильтрованные по тем же областям и состоянию продукта. Наличие инструмента не доказывает, что конкретное изменение ресурса будет разрешено.

Начинайте автоматизацию с чтения целевого ресурса и состояния его возможностей. Используйте стабильные идентификаторы вместо извлечения имён из UI. Храните базовый URL, токен и среду раздельно, чтобы скрипт разработки не мог случайно обратиться к рабочей среде.

Подключение Codex или Claude Code через MCP

Gateway предоставляет удалённый MCP-сервер с аутентификацией по адресу:

https://gateway.example.com/api/mcp

Замените gateway.example.com каноническим публичным именем своего экземпляра Gateway. Используйте тот же HTTPS-адрес, по которому операторы открывают Gateway. Не добавляйте второй /mcp и не указывайте корень REST API.

После подключения клиент увидит инструменты Gateway, но сможет выполнять только те операции, которые разрешены вошедшему пользователю. MCP не выдаёт административные права и не обходит области доступа к ресурсам, ограничения тарифа, подтверждения и журнал аудита.

Подготовка Gateway

Администратор один раз выполняет следующие действия:

Откройте Settings, перейдите на вкладку Features и найдите блок OAuth and MCP access.
Включите MCP server.
Для обычных клиентов оставьте Extended MCP compatibility включённым. Отключайте этот режим только в том случае, если клиент загружает весь каталог инструментов в контекст и не справляется с его размером.
Для Codex и Claude Code оставьте OAuth extended callback compatibility выключенным. Их локальные адреса возврата работают с более безопасной политикой по умолчанию.
Выдайте подключаемому пользователю область Use MCP (mcp:use) и обычные области доступа к ресурсам, которые клиенту разрешено читать или изменять.

Пользователь также должен иметь возможность войти в Gateway через браузер. Если подключение установлено, но нужный инструмент или ресурс не виден, проверьте группы и области доступа пользователя, а не расширяйте политику адресов возврата OAuth.

Подключение Codex

Добавьте Gateway, выполните вход через OAuth и проверьте соединение:

codex mcp add good-gateway --url https://gateway.example.com/api/mcp
codex mcp login good-gateway
codex mcp list

Команда входа откроет Gateway в браузере. Войдите под нужным пользователем, проверьте запрошенный доступ и подтвердите его. Codex сам сохранит полученные учётные данные OAuth — создавать и вставлять API-токен не требуется.

В настольном приложении Codex или расширении для редактора можно вместо команд добавить MCP-сервер типа Streamable HTTP с тем же адресом, а затем нажать Authenticate. Настольное приложение, командная строка и расширение используют общую конфигурацию MCP Codex.

Подключение Claude Code

Добавьте Gateway как удалённый HTTP-сервер для своего пользователя:

claude mcp add --transport http good-gateway --scope user https://gateway.example.com/api/mcp
claude mcp login good-gateway
claude mcp get good-gateway

Можно также запустить интерактивный сеанс Claude Code, ввести /mcp, выбрать good-gateway и выполнить вход в браузере. Используйте --scope project вместо --scope user только тогда, когда определение сервера нужно хранить для всей команды в .mcp.json. Каждый разработчик при этом всё равно входит под своей учётной записью Gateway.

Как работает OAuth

Для Codex и Claude Code не нужно вручную регистрировать OAuth-клиент:

клиент обращается к /api/mcp и получает адреса служебных документов OAuth Gateway;
клиент регистрируется и запускает поток Authorization Code с PKCE;
Gateway открывает в браузере страницу входа и согласия;
пользователь подтверждает доступ в пределах своих текущих областей Gateway;
Gateway выдаёт токен OAuth, предназначенный для ресурса MCP;
клиент сохраняет учётные данные и отправляет их на /api/mcp при следующих запросах.

Gateway принимает только токены OAuth, выданные для его ресурса MCP. Файлы cookie браузера, обычные API-токены gw_, токены журналирования gwl_ и токены Gateway Inference gwi_ будут отклонены. Сервер повторно проверяет текущие области пользователя и mcp:use, поэтому отзыв доступа блокирует последующие операции, даже если клиент уже видел инструменты.

Проверка подключения

Начните с запроса только на чтение:

Покажи доступные мне ноды в Gateway и кратко опиши их текущее состояние. Ничего не изменяй.

Убедитесь, что клиент показывает good-gateway как подключённый, видны только ожидаемые ресурсы, операция чтения выполняется успешно, действие за пределами областей пользователя получает отказ, а вызов записан в журнал аудита от имени ожидаемого пользователя.

Если MCP не подключается

Адрес возвращает 404: включите Settings → Features → OAuth and MCP access → MCP server и проверьте, что адрес заканчивается на /api/mcp.
Клиент требует аутентификацию: выполните codex mcp login good-gateway или claude mcp login good-gateway. В интерактивном клиенте используйте /mcp.
Вход выполнен, но Gateway отвечает 403: учётной записи нужны mcp:use и хотя бы одна действующая область доступа к ресурсам.
Каталог инструментов переполняет контекст клиента: отключите Extended MCP compatibility, чтобы использовать небольшой начальный каталог и обнаружение по категориям.
Gateway отклоняет адрес возврата OAuth: сначала обновите клиент и повторите вход. Обычные локальные адреса возврата Codex и Claude Code не требуют OAuth extended callback compatibility.
Сохранённое подключение перестало работать: проверьте разрешение OAuth, mcp:use, области ресурсов и канонический адрес Gateway. Выполните вход заново, а не подставляйте обычный API-токен.

Долговечные операции

Многие изменения инфраструктуры возвращают принятую Task или операцию, а не завершённый результат:

отправьте проверенный запрос;
сохраните возвращённые идентификаторы ресурса, Task, операции и запроса;
опрашивайте долговременное состояние операции или подпишитесь на него;
изучите структурированные сведения об ошибке;
независимо проверьте итоговое состояние ресурса;
повторяйте запрос только согласно контракту идемпотентности операции.

Не превращайте тайм-аут транспорта сразу во второй запрос создания или удаления. Первый запрос мог достичь ответственного демона и ожидать согласования состояния.

Обработка ошибок

400 или 422: исправьте форму запроса или входные данные валидации;
401: обновите или замените данные аутентификации;
403: отличите отсутствующую область от недоступной по тарифу функции;
404: проверьте видимость ресурса, а не только его существование;
409: проверьте конфликт жизненного цикла, квоту или текущее состояние;
429: примените ограниченную задержку и следуйте указаниям сервера;
5xx или отключённая нода: сохраните идентификаторы запросов и до повтора проверьте долговременное состояние Task.

Правила работы MCP

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

Проверка

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

Проектирование надёжных клиентов

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

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

Версионируйте клиент относительно документа OpenAPI и реально проверенных релизов Gateway. Неизвестные разрушительные поля и состояния должны приводить к безопасному отказу, а не молча игнорироваться. Если релиз меняет контракт жизненного цикла, сначала обновите клиент и его приёмочные тесты, затем распространяйте его на установки.

Безопасное развёртывание и откат

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

Откат обычно означает отключение вызывающего клиента, прекращение новых запросов и поддерживаемый продуктом откат уже изменённых ресурсов. Он не означает удаление Tasks или редактирование желаемого состояния в PostgreSQL. Сохраняйте идентификаторы запросов и метаданные неуспешной полезной нагрузки без секретов, чтобы владелец мог отличить дефект клиента от сбоя Gateway или демона.