Установка
Подключение ИИ-агента
Подключите своего ИИ-помощника к Holkas: проверьте доступ, попросите построить план и откройте настоящий diff в браузере. От настройки MCP до первой понятной задачи — без применения изменений в базу.
На этой странице
Проверьте, что доступно вашему агенту
В Holkas откройте «Полномочия → Мой агент» и найдите «Мои права на узлы». Агент работает от вашего имени. Для сравнения нужны чтение источника и приёмника; право записи понадобится, когда вы решите применять изменения.
Если нужной базы нет, сначала попросите администратора выдать доступ. Как устроены права.
Вы знаете источник, приёмник и объект первой проверки. Агенту не придётся угадывать, с какой базой работать.
Создайте токен «для агента»
В карточке «Токены доступа» укажите имя, выберите «для агента» и нажмите «Создать». Полный токен показывается один раз. Сохраните его в своём хранилище секретов: он понадобится при настройке клиента.
Выпускайте отдельный агентский токен на каждый клиент или компьютер (например, codex-laptop и claude-code-work): тогда отзыв одного не отключит остальные. Все они действуют от вашего имени и с вашими правами. Служебные учётные записи используют CLI и REST, агентский токен им не выдаётся.
Получен токен с назначением «для агента». Токен «для скрипта» для MCP не подходит. Имя использованного токена видно в аудите рядом с подписью агента; оно сохраняется после отзыва.
Укажите клиенту адрес Holkas
MCP — способ дать помощнику инструменты Holkas: прочитать подключения, построить план, объяснить различия и посмотреть журнал. Адрес подключения — адрес вашего сервера с /mcp в конце, например http://localhost:8080/mcp для локального Docker.
Выберите Codex CLI или Claude Code, выполните настройку ниже и вернитесь к следующему шагу. Для другого приложения используйте параметры подключения. Сам Holkas запускается отдельно.
В списке MCP-серверов клиента появился holkas. Это ещё не доказательство связи: дальше проверим настоящий вызов инструмента.
Начните с проверки связи и прав
Откройте новый разговор в настроенном клиенте. Этот запрос проверяет вход и список доступных подключений; перенос он не запускает. Формулировки здесь — примеры поручений, а ответы инструментов ниже получены на настоящем стенде.
Прочитай гид Holkas. Проверь связь через holkas_ping и покажи доступные мне подключения с правами. Пока ничего не изменяй. Настоящий ответ holkas_ping в учебном прогоне
Holkas up. actor=agent, on_behalf_of=site-guide, door=mcp.on_behalf_of показывает пользователя, от имени которого действует агент; у вас будет свой логин. Гид holkas_guide нужно прочитать один раз за MCP-сессию. Без него сервер не разрешит построение плана и напомнит об этом кодом guide_not_read.
Ответ пришёл от вашего Holkas, пользователь указан верно, а нужные подключения есть в списке. Если видите ошибку — разберите её до построения плана.
Попросите сравнить один объект
Дайте точное направление, объект и границу задачи. В учебном примере сравним старую версию функции из Git с текущей приёмкой. Так можно увидеть отличие от сохранённого коммита, не возвращая его в базу.
Построй только план из «Учебная · GitHub», коммит b5d8a36b6c422f201585f85d26740d4c6cc15c97, в «Учебная · приёмка» для функции JFP:parus.f_hksite_contract_check. Основание: «Подключение ИИ: сравнить сохранённую версию без применения». Покажи число команд, предупреждения, объясни изменение функции и дай ссылку на план в Holkas. Ничего не применяй. Имена подключений и объекта замените своими. Для сравнения двух баз укажите базу-источник и уберите коммит. Агент вызывает holkas_build_plan, а затем разбирает функцию через holkas_explain_object. Если план ещё строится, попросите дождаться результата этой операции.
Получены номер операции, её состояние и сводка. Пустой успешный план тоже возможен: выбранные объекты уже совпадают. Ошибка с нулём команд совпадением не считается.
Откройте результат и прочитайте diff
Перейдите по ссылке агента или откройте <адрес Holkas>/migrate/<номер операции>. Выберите строку функции, нажмите «Diff исходного кода» и включите «Все строки». Это тот же план, который вернул MCP.
Сверьте направление, объект и код с объяснением агента. Этот учебный план оставляем без применения. Если нужно разобраться в ошибке, попросите агента прочитать журнал именно этой операции.
Подключение проверено по всей цепочке: вход → инструменты → план → подробный diff в браузере. Теперь можно перейти к совместной работе над переносом.
Определите, когда агент должен спрашивать
Вернитесь в «Полномочия → Мой агент» и посмотрите «Договор автономии». «Авто» разрешает действие без дополнительного подтверждения, если у вас достаточно прав. Политику отдельных действий можно ужесточить.
Когда вы поручите применение в базу, первый вызов MCP создаст заявку и вернёт её номер. После просмотра плана подтвердите её в Holkas или сообщите решение агенту; тогда он повторит тот же вызов с подтверждением. Заявка действует 30 минут. В первом примере до этого шага выполнения мы не доходим.
Вы понимаете, что агент может выполнить сам, а где требуется ваше решение. Пример заявки, применения и повторной проверки показывает весь следующий сценарий.
Codex CLI
В настройке используется переменная HOLKAS_TOKEN: в конфигурации сохраняется её имя, а не секрет. В терминале добавьте сервер, заменив адрес своим:
codex mcp add holkas --url http://localhost:8080/mcp --bearer-token-env-var HOLKAS_TOKEN
codex mcp get holkas
Если holkas уже настроен, проверьте его параметры перед изменением. Вместо команды можно добавить блок в ~/.codex/config.toml; это альтернативный способ, выполнять оба не нужно:
[mcp_servers.holkas]
url = "http://localhost:8080/mcp"
bearer_token_env_var = "HOLKAS_TOKEN"
tool_timeout_sec = 120
tool_timeout_sec даёт инструменту время на ожидание плана. Затем задайте токен в окружении, запустите codex из того же терминала и откройте /mcp. Там видны активные серверы. Вернитесь к первому запросу: наличие записи в mcp get проверяет конфигурацию, а вызов holkas_ping — связь и вход.
Параметры HTTP, токен из окружения и команды управления описаны в официальной документации Codex.
Claude Code
В папке проекта добавьте или дополните .mcp.json. Сохраните существующие серверы; в объект mcpServers добавьте holkas:
{
"mcpServers": {
"holkas": {
"type": "http",
"url": "http://localhost:8080/mcp",
"headers": {
"Authorization": "Bearer ${HOLKAS_TOKEN}"
}
}
}
}
Здесь ${HOLKAS_TOKEN} — буквальная ссылка на переменную окружения, не место для вставки секрета. Подставьте свой адрес, задайте переменную и запустите claude из этого терминала в папке проекта. Если клиент запросит доверие к серверу проекта, проверьте адрес и разрешите подключение. Внутри Claude Code откройте /mcp, проверьте сервер и выполните первый запрос.
Holkas после выпуска токена также показывает готовую команду claude mcp add. Она содержит полный секрет; не публикуйте её. Вариант .mcp.json выше позволяет держать секрет отдельно от файла проекта. Формат и подстановка окружения — в документации Claude Code.
Передайте токен запущенному клиенту
В Bash выполните команды и вставьте токен в скрытый запрос:
read -rsp 'Токен Holkas для агента: ' HOLKAS_TOKEN
printf '\n'
export HOLKAS_TOKEN
В PowerShell:
$secret = Read-Host 'Токен Holkas для агента' -AsSecureString
$env:HOLKAS_TOKEN = [System.Net.NetworkCredential]::new('', $secret).Password
Remove-Variable secret
Затем из этого же терминала запустите выбранный клиент: codex или claude. Уже открытое приложение не получает новую переменную автоматически. При следующем запуске в другом терминале задайте её снова либо используйте принятое у вас управление секретами.
HOLKAS_TOKEN в этих примерах содержит токен «для агента». Переменная HOLKAS_API_KEY из инструкции CLI используется отдельно с токеном «для скрипта». Не вставляйте токен в разговор с моделью или в файлы репозитория.
Другие клиенты
Нужны следующие параметры; названия полей и способ хранения секрета зависят от приложения:
| Параметр | Значение |
|---|---|
| Транспорт | Streamable HTTP |
| URL | Полный адрес вашего Holkas с /mcp в конце |
| Вход по личному токену | Заголовок Authorization: Bearer <токен для агента> |
| Корпоративный вход | OAuth через настроенный Holkas в режиме Team |
Отдельного режима stdio у Holkas нет. JSON для Claude Code выше относится именно к его .mcp.json; в другом клиенте используйте его собственный формат настройки.
Адрес должен быть доступен из места, где работает MCP-клиент. localhost — машина клиента. Облачное приложение не получает доступ к серверу в вашей локальной сети только потому, что он открыт в вашем браузере. Для примеров этой страницы удобен клиент на вашем компьютере с доступом к сети Holkas.
В ответах инструментов могут быть исходники объектов, имена подключений и сообщения журналов. Выбирайте помощника и настройки обработки данных, подходящие для вашего проекта.
Team: вход через браузер
Если администратор настроил Team с Keycloak и HTTPS, используйте корпоративный URL Holkas и OAuth. Создавать личный токен для этого способа не нужно. Настройку сервера выполняет администратор по параметрам Team.
Для Codex добавьте сервер без --bearer-token-env-var и начните вход:
codex mcp add holkas --url https://holkas.example.org/mcp
codex mcp login holkas
Для Claude Code:
claude mcp add --transport http holkas https://holkas.example.org/mcp
Замените домен своим. В Claude Code откройте /mcp и выберите вход для holkas. В браузере пройдите корпоративную авторизацию, затем вернитесь к проверке связи. Команды OAuth и просмотр серверов описаны в документации Codex и Claude Code.
Если раньше использовали личный токен, сначала измените существующую запись клиента: уберите для неё bearer_token_env_var или заголовок Authorization. Не оставляйте два противоречащих способа входа под одним именем. Права определяются учётной записью, с которой вы вошли.
Если не подключается
| Что видите | Что проверить и сделать |
|---|---|
holkas отсутствует в списке MCP | Проверьте конфигурацию выбранного клиента и папку проекта. Перезапустите клиент после настройки. |
| Ошибка соединения или тайм-аут подключения | Сервер Holkas работает, адрес и порт верны, путь заканчивается на /mcp, сеть доступна машине клиента. Для локального Docker из нашей инструкции порт 8080, для Windows по умолчанию 5000. |
401 Unauthorized | Токен передан в окружение именно этого процесса, не отозван, не истёк и выпущен в указанном экземпляре Holkas. В OAuth-варианте проверьте вход через клиент. |
403, код rest_token_door | Передан токен «для скрипта». Выпустите токен «для агента»; смена имени переменной назначение токена не меняет. |
service_account_has_no_agent | Вход выполнен под служебной учётной записью. Для ИИ-агента нужна личная; для служебной есть CLI и REST. |
guide_not_read | Попросите вызвать holkas_guide, затем повторить задачу в той же MCP-сессии. Это правило сервера. |
| Связь есть, но нужная база не видна | Сверьте пользователя в holkas_ping и его права в Holkas. Как выдать доступ. |
Сообщение с confirm=<номер> | Подключение работает, действие ожидает решения человека. Прочитайте план и заявку; подтверждайте только нужную операцию. |
| Клиент прекратил ждать построения плана | Проверьте историю и уже созданную операцию, прежде чем повторять запрос. Для Codex можно увеличить tool_timeout_sec. |
| Корпоративный вход не завершается | Сверьте публичный HTTPS-адрес с TeamAuth__Issuer, доступность Keycloak и настройки клиента. Это отдельная настройка Team, а не замена личного токена. |
Отзыв доступа и следующий шаг
После разового знакомства отзовите личный токен в «Полномочия → Мой агент → Токены доступа». Закрытие клиента само по себе токен не отзывает. Из текущего окружения уберите его командой unset HOLKAS_TOKEN в Bash или Remove-Item Env:HOLKAS_TOKEN в PowerShell. Для корпоративного OAuth используйте управление доступом, принятое у администратора Team.
Дальше — перенос вместе с агентом: проверка diff, заявка, подтверждение и повторное сравнение. Все инструменты и их параметры собраны в справочнике MCP.
Если нужна помощь, можно поручить агенту подготовить обращение: «Подготовь сообщение в поддержку об ошибке операции и покажи мне перед отправкой». Почту сначала привязывает человек в разделе «Поддержка». Проверьте текст и приложения, затем дайте согласие на отправку. Подробнее — как обратиться в поддержку.
Проверка этой страницы: настоящий MCP-сеанс на учебном сервере — гид, вход, список подключений, проверка базы, план, разбор функции и журнал. План оставлен без применения, токен отозван. Конфигурация Codex проверена установленным CLI 0.163.0; ответы показаны непосредственно от инструментов, без имитации разговора с моделью. Пример Claude Code сверен с официальной документацией; его запуск, PowerShell и корпоративный OAuth в этом прогоне не проверялись.
26 октября 2026 дополнительно проверены два агентских токена одного пользователя: оба подключились к MCP и построили учебный план. После отзыва первого второй продолжил отвечать. Аудит и CSV сохранили имена обоих токенов; после проверки второй также отозван.