Holkas
Написать в поддержку Поддержка

Установка

Подключение ИИ-агента

Подключите своего ИИ-помощника к Holkas: проверьте доступ, попросите построить план и откройте настоящий diff в браузере. От настройки MCP до первой понятной задачи — без применения изменений в базу.

На этой странице

Проверьте, что доступно вашему агенту

В Holkas откройте «Полномочия → Мой агент» и найдите «Мои права на узлы». Агент работает от вашего имени. Для сравнения нужны чтение источника и приёмника; право записи понадобится, когда вы решите применять изменения.

Если нужной базы нет, сначала попросите администратора выдать доступ. Как устроены права.

Права учебного пользователя на подключения — чтение разработки и чтение с записью приёмки
Права учебной учётной записи site-guide. Например, разработку она может читать, а приёмку — читать и изменять. Токен не добавляет новых разрешений.

Вы знаете источник, приёмник и объект первой проверки. Агенту не придётся угадывать, с какой базой работать.

Создайте токен «для агента»

В карточке «Токены доступа» укажите имя, выберите «для агента» и нажмите «Создать». Полный токен показывается один раз. Сохраните его в своём хранилище секретов: он понадобится при настройке клиента.

Выпускайте отдельный агентский токен на каждый клиент или компьютер (например, codex-laptop и claude-code-work): тогда отзыв одного не отключит остальные. Все они действуют от вашего имени и с вашими правами. Служебные учётные записи используют CLI и REST, агентский токен им не выдаётся.

Создание токена в Holkas с выбранным назначением для агента
Выбран тип «для агента». В таблице два отдельных активных учебных токена — для ноутбука и сервера. После проверки оба отозваны. Полный секрет в кадр не попадает.

Получен токен с назначением «для агента». Токен «для скрипта» для 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. Если план ещё строится, попросите дождаться результата этой операции.

План из MCP в Holkas — готовая операция с одной командой изменения функции
В нашем прогоне операция 7ba30170be84 получила статус PlanReady: одна команда Update, без аномалий. Приёмка не изменена.

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

Откройте результат и прочитайте diff

Перейдите по ссылке агента или откройте <адрес Holkas>/migrate/<номер операции>. Выберите строку функции, нажмите «Diff исходного кода» и включите «Все строки». Это тот же план, который вернул MCP.

Сверьте направление, объект и код с объяснением агента. Этот учебный план оставляем без применения. Если нужно разобраться в ошибке, попросите агента прочитать журнал именно этой операции.

Diff учебной функции — правило суммы не меньше 100 заменяется версией больше нуля из Git
Красным — текущее правило приёмника amount >= 100, зелёным — amount > 0 из выбранного старого коммита. План показывает направление возможного изменения; сам он его не выполняет.

Подключение проверено по всей цепочке: вход → инструменты → план → подробный diff в браузере. Теперь можно перейти к совместной работе над переносом.

Определите, когда агент должен спрашивать

Вернитесь в «Полномочия → Мой агент» и посмотрите «Договор автономии». «Авто» разрешает действие без дополнительного подтверждения, если у вас достаточно прав. Политику отдельных действий можно ужесточить.

Когда вы поручите применение в базу, первый вызов MCP создаст заявку и вернёт её номер. После просмотра плана подтвердите её в Holkas или сообщите решение агенту; тогда он повторит тот же вызов с подтверждением. Заявка действует 30 минут. В первом примере до этого шага выполнения мы не доходим.

Договор автономии Holkas — построение плана автоматически, применение в базу всегда с подтверждением
Правило применения в базу закреплено: «Всегда подтверждение». Автоматическая выгрузка в Git, S3 или файл регулируется отдельно.

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

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 сохранили имена обоих токенов; после проверки второй также отозван.