REST API и MCP

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

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

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

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

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

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

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

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

Что доступно вызывающему

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

REST: GET /api/auth/me/access с сеансом, API-токеном или токеном OAuth.
MCP и AI Workspace: инструмент get_my_access, при необходимости с разделом area, например docker_containers или routes.
Ресурс MCP: gateway://access.

Сводка группирует доступ по разделам продукта. Для каждого раздела она указывает, общий доступ (broad) или ограниченный (limited), перечисляет выданные папки (идентификатор, имя и путь), ноды, аккаунты и ресурсы с разрешёнными для каждого действиями и показывает, где вызывающий может создавать ресурсы: create.atRoot, create.folders и create.nodes, с подсказкой howTo. Объект principal называет тип учётных данных (session, api-token, oauth-token, mcp или assistant). Только сеанс браузера и AI Workspace дополнительно получают идентификатор, имя, адрес электронной почты и группу прав пользователя; API-токены, токены OAuth и клиенты MCP получают только principal: { credential, boundedByOwner: true }, потому что их доступ никогда не превышает текущий доступ владельца. Если подключение MCP ограничено, Opfield при подключении также добавляет краткую версию сводки в инструкции сервера MCP.

Работайте в пределах перечисленных прав:

Запросы и инструменты списков возвращают только то, что доступно вызывающему; пустой список — не отказ в доступе.
list_resource_folders показывает все папки, на которые у вызывающего есть хоть какое-то право, включая пустые, с access.actions и access.canCreate.
Создание без folderId выполняется на верхнем уровне. Если право создания ограничено, передавайте folderId, а там, где операция его принимает, и nodeId.
Отказ вызывающему с ограниченным доступом — при создании в корне или чтении ресурса вне его разрешений — называет папки, ноды и ресурсы, которые ему доступны, и предлагает передать folderId; так отвечают и REST, и ошибки инструментов MCP и AI Workspace. Считайте право отсутствующим, только если сводка не показывает разрешения на это действие нигде.

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

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

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

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

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

Подготовка Opfield

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

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

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

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

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

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

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

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

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

Добавьте Opfield как удалённый 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. Каждый разработчик при этом всё равно входит под своей учётной записью Opfield.

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

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

клиент обращается к /api/mcp и получает адреса служебных документов OAuth Opfield;
клиент регистрируется и запускает поток Authorization Code с PKCE;
Opfield открывает в браузере страницу входа и согласия;
пользователь подтверждает доступ в пределах своих текущих областей Opfield и может ограничить его папками или ресурсами, например с помощью Limit selected scopes to folder…; см. «Ограничение токенов и разрешений OAuth»;
Opfield выдаёт токен OAuth, предназначенный для ресурса MCP;
клиент сохраняет учётные данные и отправляет их на /api/mcp при следующих запросах.

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

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

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

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

Убедитесь, что клиент показывает 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.
Вход выполнен, но Opfield отвечает 403: учётной записи нужны mcp:use и хотя бы одна действующая область доступа к ресурсам. Разрешение, ограниченное папкой, видит только ресурсы этой папки; создание в другом месте запрещено. Попросите агента вызвать get_my_access и создавать ресурсы в одной из перечисленных папок; см. «Что доступно вызывающему».
Клиент передаёт имя области, которого больше нет: Opfield 2.11 ещё два выпуска принимает устаревшие имена скоупов и выдаёт их замены.
Каталог инструментов переполняет контекст клиента: отключите Extended MCP compatibility, чтобы использовать небольшой начальный каталог и обнаружение по категориям.
Opfield отклоняет адрес возврата OAuth: сначала обновите клиент и повторите вход. Обычные локальные адреса возврата Codex и Claude Code не требуют OAuth extended callback compatibility.
Сохранённое подключение перестало работать: проверьте разрешение OAuth, mcp:use, области ресурсов и канонический адрес Opfield. Выполните вход заново, а не подставляйте обычный API-токен.

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

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

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

Не превращайте тайм-аут транспорта сразу во второй запрос создания или удаления. Первый запрос мог достичь ответственного демона и ожидать согласования состояния. Исключение — создание через адрес, который принимает Idempotency-Key, отправленное с этим заголовком: повторите его с тем же ключом.

Безопасные повторы с Idempotency-Key

Необязательный заголовок Idempotency-Key длиной от 1 до 255 печатаемых символов ASCII, например UUID, принимают только отдельные запросы создания. Документ OpenAPI указывает заголовок ровно у этих операций:

Docker: создание и дублирование контейнеров, а также создание развёртываний, проектов Compose, ресурсов из источника Git, томов, сетей и реестров;
Ingress и сертификаты: маршруты (POST /api/proxy-hosts), папки маршрутов, домены, сертификаты ACME, корневые и промежуточные центры сертификации;
Базы данных и хранилища: подключения к базам данных, управляемые базы данных, подключения хранилищ и управляемые хранилища;
Другое: проекты Pages, правила оповещений и получатели SIEM.

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

curl -X POST https://gateway.example.com/api/domains \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6c1e-8a55-4c43-9d4e-2f1f8c3d9b10" \
  -d '{"domain":"app.example.com"}'

Ключ привязан к API-токену, токену OAuth или сеансу браузера, который его отправил, к текущим действующим областям этого вызывающего, методу и точному пути запроса. После изменения областей тот же ключ начинается заново, поэтому повтор никогда не переживает отозванный доступ.
Повтор с тем же ключом и тем же запросом — той же строкой запроса и тем же телом JSON, в любом порядке ключей — возвращает сохранённый ответ с заголовком Idempotency-Replayed: true и ничего не создаёт заново. Opfield хранит результат 24 часа в зашифрованном мастер-ключом виде и записывает каждый повтор в журнал аудита как api.idempotency.replay.
Тот же ключ с другим запросом возвращает 422 IDEMPOTENCY_KEY_REUSED. Тот же ключ, пока первый запрос ещё выполняется, возвращает 409 IDEMPOTENCY_KEY_IN_PROGRESS с Retry-After. Недопустимый ключ возвращает 400 IDEMPOTENCY_KEY_INVALID.
Opfield никогда не сохраняет ответ, который выглядит как содержащий секрет — токен, пароль, закрытый ключ или учётные данные, — а также ответ больше 1 МиБ. Он запоминает только факт завершения запроса, и повтор возвращает 409 IDEMPOTENCY_RESPONSE_WITHHELD с исходным статусом и Location, если он известен: найдите ресурс, а не повторяйте запрос.
Запоминаются только ответы 2xx, а также 400, 404, 409 и 422 с телом JSON или пустым телом. Ответы 401, 403, 5xx, потоковые ответы и скачивания не запоминаются, поэтому повтор после них выполняет запрос заново.
Не охватываются: все адреса вне перечисленных выше — они выполняются обычным образом и не учитывают заголовок. Сюда намеренно входят адреса, которые один раз возвращают секрет или повторяют чувствительные входные данные: токены API, Inference, приёма журналов и публикации Pages, регистрация нод, ключи доступа и учётные данные, привязки, списки доступа и вебхуки уведомлений. Тела запросов больше 1 МиБ и загрузки не в JSON также выполняются без идемпотентности, как и все запросы, пока недоступен Redis, где хранятся ключи.

Инструменты MCP для создания принимают необязательный аргумент idempotencyKey с теми же правилами. Ключ привязан к токену MCP и его областям, текущим областям владельца и инструменту. Сохраняются только успешные результаты, поэтому после ошибки инструмента вызов можно повторить с тем же ключом; повторно выданный результат содержит _meta.idempotencyReplayed: true и записывается в аудит. Результат, похожий на содержащий секрет, не сохраняется, а повтор возвращает IDEMPOTENCY_RESULT_WITHHELD. Аргумент есть у следующих инструментов:

Docker: create_docker_container, duplicate_docker_container и операция создания в manage_docker_deployment, manage_docker_compose, manage_docker_source, manage_docker_volume, manage_docker_network и manage_docker_registry;
Ingress: create_route, create_route_folder и create_domain;
Сертификаты: request_acme_cert, операция загрузки в manage_ssl_certificate, create_root_ca и create_intermediate_ca;
Базы данных и хранилища: операция создания в manage_database_connection, manage_managed_database, manage_storage_connection и manage_managed_storage;
Другое: операция project_create в manage_pages, create_alert_rule и create_siem_destination.

Инструменты, которые возвращают секрет или повторяют чувствительные входные данные, — create_node, create_access_list, create_webhook, создание привязок, создание токенов и ключей доступа и issue_certificate — этот аргумент не принимают. Операции жизненного цикла Compose в manage_docker_compose сохраняют собственный аргумент idempotencyKey с прежним значением.

Передача больших данных через одноразовые ссылки

Вызовы инструментов плохо подходят для передачи файлов. Для больших данных инструменты MCP возвращают одноразовую ссылку с готовой командой curl, которую выполняет оболочка на стороне агента; данные идут потоком через Opfield и никогда не проходят через модель:

Pages: операция link инструмента upload_pages_artifact принимает архив, упакованную папку сборки или один HTML-файл. Размер загрузки ограничен значением File upload limit (по умолчанию 100 МБ, максимум 500 МБ); см. Обзор Pages. Без оболочки операции begin, chunk и finalize принимают не больше 1 МиБ за часть.
Архивы контейнеров: операции link инструментов download_docker_archive и upload_docker_container_archive экспортируют и импортируют архивы .gwca.
Объекты хранилищ: download_storage_object возвращает действующую 15 минут ссылку для скачивания объекта любого размера, а upload_storage_object загружает объект частями, которые проверяет Opfield.

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

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

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

Ошибки инструментов MCP и AI Workspace начинаются с того же кода, что и ответ REST, например NOT_FOUND, STORAGE_NOT_FOUND или NGINX_CONFIG_FAILED, за которым следуют сообщение и подробности; ошибка схемы выглядит как VALIDATION_ERROR с перечнем неверных полей. Запрос к несуществующему пути /api возвращает 404 NOT_FOUND в формате JSON, а не страницу Console.

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

В 2.11 инструменты MCP охватывают все ресурсы и операции управления, которые разрешают области разрешения OAuth, включая конфигурацию и файлы нод, миграции Docker, бэкенд журналирования, настройки Opfield, пользователей и группы, операции Relay Pool и обновлений, администрирование Inference, хостинг, а также коннекторы GitLab, GitHub, обычного Git, Cloudflare и внешнего SSH. MCP не раскрывает внутренние объекты AI Workspace, такие как беседы, планы и песочницы, и не предоставляет инструменты, которые создают API-токены или авторизации OAuth. См. Что токены могут и не могут делать.

Для создания маршрутов и доменов права на ноды не нужны: create_route и create_domain могут не указывать ноду, если её определяет зарегистрированный домен или единственная подходящая нода Ingress (для маршрутов эта нода должна быть подключена), а list_route_ingress_nodes перечисляет ноды, на которых вызывающий может создавать маршруты. См. «Выбор ноды Ingress».

Сервер MCP сообщает в качестве своей версии выпуск Opfield. manage_gateway_diagnostics проверяет состояние самого Opfield; см. Диагностика Opfield. Когда инструмент MCP задаёт окружение Deployment, он объединяет его с сохранённым окружением — в отличие от маршрута развёртывания REST; см. Выпустите новую версию.

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

Проверка

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

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

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

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

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

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

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

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