Перейти к содержанию

HOSTKEY MCP Server

В этой статье

HOSTKEY MCP Server (RU) — мост между AI-клиентами (Cursor, VS Code, Claude Code, Codex и другими MCP-совместимыми средами) и вашим аккаунтом HOSTKEY на российском портале . Технически это MCP-сервер, который запускается локально через stdio (или подключается удалённо) и предоставляет модели более 130 типизированных инструмента плюс универсальный call_api_raw для доступа к любому методу InvAPI. Сервер работает с порталом .ru и endpoint invapi.hostkey.ru, зашитым в код.

Три сценария, где MCP-сервер экономит время радикально:

  • Диагностика в моменте: сервер упал, вы не уверены, проблема в питании или сети. Вместо панели — спрашиваете ассистента, он вызывает get_power_status, get_server_sensors, get_network_status и выдаёт сводку.
  • Рутинные операции: перезагрузка, переустановка ОС, обновление DNS — всё через чат.
  • Заказ ресурсов: подбор пресета, проверка доступности, dry-run с расчётом стоимости — и только потом реальный заказ.

Примечание

Для международного портала .com существует отдельный MCP hostkey-mcp-server.

Архитектура

MCP (Model Context Protocol) — это стандарт, который описывает, как AI-модель может вызывать внешние инструменты. В случае HOSTKEY MCP Server:

  1. Вы настраиваете MCP-клиент (Cursor, VS Code и т.п.), указывая команду запуска сервера и ваш API-ключ.
  2. Клиент запускает сервер локально (или подключается к удалённому endpoint).
  3. Когда вы просите ассистента что-то сделать с серверами, модель выбирает подходящий инструмент из 132 доступных.
  4. Сервер вызывает соответствующий метод InvAPI, получает ответ и возвращает его модели.
  5. Модель формулирует ответ вам.

Внимание

все операции записи требуют явного подтверждения**. По умолчанию confirm=true не передаётся, и сервер ничего не меняет.

Сервер предоставляет три встроенных промпта — предустановленных сценария, которые направляют модель по правильному пути. Но даже без них можно просто писать команды на естественном языке: «покажи мои серверы», «закажи VPS в NL».

Как подключить MCP сервер к средам

Cursor

В .cursor/mcp.json:

{
  "mcpServers": {
    "hostkey-mcp-server-ru": {
      "command": "npx",
      "args": ["-y", "hostkey-mcp-server-ru"],
      "env": {
        "HOSTKEY_API_KEY": "ваш-ключ"
      }
    }
  }
}

Или нажмите кнопку Install in Cursor в README пакета, подставьте ключ и подтвердите .

VS Code

В .vscode/mcp.json:

{
  "servers": {
    "hostkey-mcp-server-ru": {
      "command": "npx",
      "args": ["-y", "hostkey-mcp-server-ru"],
      "env": {
        "HOSTKEY_API_KEY": "ваш-ключ"
      }
    }
  }
}

Удалённый режим (для облачных агентов)

Если локальный Node/npx недоступен:

{
  "mcpServers": {
    "hostkey": {
      "url": "https://mcp.hostkey.ru/mcp",
      "headers": {
        "Authorization": "Bearer ваш-ключ"
      }
    }
  }
}

Инструменты

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

Серверы и состояние

  • get_servers — список ваших серверов с фильтрацией по IP, hostname, локации, тегам . Это отправная точка для большинства сценариев.

  • get_server — детальная карточка сервера: конфигурация, ОС, IP-адреса, интерфейсы, IPMI . Возвращает всё, что нужно для понимания состояния.

  • get_power_status — состояние питания. Если сервер выключен, следующий шаг — power_on (с подтверждением).

  • get_server_sensors — для bare-metal серверов: температуры, напряжения, состояние вентиляторов. Критично для диагностики перегрева или сбоя PSU.

  • search_servers_by_tag — поиск по пользовательским тегам. Если вы помечаете серверы как «production», «staging», «gpu» — это быстрый способ отфильтровать нужные .

Каталог и подбор ресурсов

  • list_presets — список доступных instant-серверов (VM/BM/GPU/vGPU) с ценами в указанной локации. Не требует токена — можно смотреть каталог до заказа .

  • search_presets — поиск подходящих свободных серверов под конкретный пресет по имени (например, vm.pico). Требует авторизации .

  • get_preset_pricing — цены на пресеты в разных валютах. Нужен для честного dry-run заказа .

  • list_os — список ОС, доступных для установки. Без instance_id возвращает все ОС для всех пресетов .

  • list_software — marketplace-приложения, доступные для автоустановки (панели, БД, инструменты) .

  • list_traffic_plans — тарифные планы трафика для пресета в локации .

Питание и управление

  • power_on / power_off — включение и выключение. Требуют confirm=true .

  • reboot_server — перезагрузка. Для серверов в standby может потребоваться IPMI .

  • power_cycle — жёсткий цикл питания (выключить и включить). Полезно, когда обычная перезагрузка не помогает.

Заказ серверов

  • order_server — ключевой инструмент заказа. Работает в двух режимах :

  • dry_run=true (по умолчанию): проверяет доступность пресета и ОС, возвращает сводку с ориентировочной стоимостью. Деньги не списываются.

  • dry_run=false+confirm=true: реальный заказ. Списывает средства с баланса или выставляет инвойс.

Параметры: preset, os_id, location_name (NL/US/FI/DE/IS/TR/UK/ES/IT/PL/CH), root_pass (мин. 8 символов, заглавная, цифра, спецсимвол, без @ и #), traffic_plan, deploy_period (monthly/quarterly/semi-annually/annually), опционально soft_id, ssh_key, hostname, promocode, deploy_notify .

Деплой занимает 10–30 минут. Статус проверяется через check_task с callback-ключом из ответа .

Переустановка ОС и PXE

  • reinstall_server — деструктивная операция: все данные на дисках будут удалены. Требует HOSTKEY_ALLOW_DESTRUCTIVE=1 в окружении, confirm=true и повторного ввода текущего hostname сервера . Это дополнительная защита от случайного запуска.

Последовательность PXE-переустановки (для серверов без удалённого управления) :

  1. create_reinstall_task — создаёт мастер-ключ, возвращает reinstall_key.
  2. create_pxe_config — создаёт PXE-конфиг.
  3. set_boot_device (pxe) — устанавливает загрузку по сети.
  4. Установка ОС происходит автоматически.
  5. set_boot_device (disk) — возвращает загрузку с диска.
  6. clear_pxe_config — обязательно после завершения, иначе возможна внезапная переустановка при следующей перезагрузке.

Инструмент также доступен как отдельный reinstall_server для стандартных случаев .

Сеть и DNS

  • get_network_status — состояние сетевых интерфейсов: порт, свитч, VLAN, скорость, MAC, статус подключения .

  • get_port_graphs — графики загрузки порта за день/месяц/год .

  • port_on / port_off — включение/выключение сетевого порта. Выключение означает потерю связности по этому интерфейсу .

  • block_ip / unblock_ip — блокировка IP на уровне сети HOSTKEY. Полезно для abuse-запросов .

  • get_ptr_record / update_ptr_record — управление reverse DNS. Несколько записей передаются разделителем %0A .

DNS-инструменты (требуют права pdns/edit):

  • add_dns_domain — создать DNS-зону и добавить домен. Параметры: name (например, example.com), confirm=true .
  • add_dns_record — добавить или изменить запись. Поддерживает A, AAAA, CNAME, MX, TXT, SRV . Для SRV-записей заполняются proto, priority, weight, port, target. Поля mname/rname отмечены как обязательные для SOA-проверок — при ошибке заполните их .
  • list_dns_domains — список всех DNS-зон аккаунта .
  • add_dns_subdomain — добавить сабдомен, привязанный к серверу .

Снапшоты, ISO, S3

  • create_snapshot — создать снапшот ВМ. Асинхронная операция, статус через check_task .
  • remove_snapshot — удалить снапшот .
  • ISO-инструменты: list_iso_images, get_uploaded_isos, add_iso (добавить/обновить образ), mount_iso (смонтировать, асинхронно, возвращает callback), unmount_iso .
  • S3: управление бакетами и объектами (подробная документация в tools/list).

IPMI и консоль

  • get_ipmi — IP-адрес и модель IPMI-интерфейса .
  • add_ipmi_user — создать временного IPMI-пользователя для веб-доступа .
  • reset_ipmi — перезагрузить IPMI-модуль. Применять, если IPMI не отвечает .
  • get_console / start_novnc — доступ к VNC/HTML5-консоли сервера .

Remote Hands

Инструменты для тикетов дежурной смене — когда нужно физическое вмешательство :

  • request_rh_power_on — включить сервер вручную
  • request_rh_power_off — выключить вручную
  • request_rh_reboot — перезагрузить
  • request_rh_pxe_boot — загрузить по PXE (нужно при переустановке без удалённого управления)
  • request_rh_kvm — подключить IP KVM
  • request_rh_check — проверить сервер и загрузить в ОС

Биллинг и API-ключи

  • get_account_info — информация о текущем API-токене и аккаунте: доступные вызовы, тип аккаунта, ID серверов. Первый инструмент для проверки подключения.
  • list_api_keys, create_api_key, update_api_key, delete_api_key — управление ключами. При создании значение показывается один раз — сохраните его.

Служебные

  • check_task — проверка статуса долгой операции по callback-ключу. Возвращает стадию выполнения, result="OK" при успехе .
  • call_api_raw — прямой вызов любого метода InvAPI, когда типизированного инструмента не хватает. **Всегда требует confirm=true**; для деструктивных/платных действий дополнительноHOSTKEY_ALLOW_DESTRUCTIVE=1` .

Промпты: готовые сценарии

Промпты — это предустановленные инструкции, которые направляют модель по проверенному пути. Они избавляют от необходимости помнить порядок вызовов и параметры.

order_server_prompt

Назначение: провести пользователя через заказ сервера шаг за шагом .

Как работает: промпт инструктирует модель:

  1. Уточнить локацию (если не указана).
  2. Вызвать list_presets, предложить 2–3 варианта с ценами через get_preset_pricing, дождаться выбора.
  3. Вызвать list_os для выбранного пресета, предложить варианты.
  4. Опционально list_software для marketplace-приложений.
  5. list_traffic_plans для выбора трафика.
  6. Собрать root-пароль (мин. 8 символов, заглавная, цифра, спецсимвол, без @/#) или SSH-ключ, hostname, период оплаты.
  7. Обязательно выполнить order_server с dry_run=true, показать сводку со стоимостью.
  8. Только после явного согласия пользователя — dry_run=false + confirm=true.
  9. Сохранить callback-ключ, сообщить о времени деплоя (10–30 минут), предложить check_task.

Аргументы: location (опционально), purpose (опционально) .

reinstall_server_prompt

Назначение: переустановка ОС с проверками .

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

  1. Определить ID сервера (через get_servers, если не указан).
  2. Вызвать get_server и get_power_status, показать состояние.
  3. Явно предупредить: переустановка удалит ВСЕ данные на дисках.
  4. list_os для сервера, выбор os_id. Опционально list_software.
  5. Собрать новый root-пароль или SSH-ключ, deploy_notify.
  6. reinstall_server с confirm=true и текущим hostname. Если инструмент ответил, что деструктивные операции отключены — объяснить про HOSTKEY_ALLOW_DESTRUCTIVE=1.
  7. Сохранить callback-ключ, отслеживать через check_task до result="OK". Не запускать вторую переустановку, пока идёт текущая.
  8. Напомнить: пароль root новый; email-уведомление при этом способе может не прийти.

Аргументы: server_id (опционально) .

troubleshoot_server_prompt

Назначение: диагностика проблем .

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

  1. Определить ID сервера (через get_servers, можно фильтровать по IP или тегам).
  2. Собрать картину: get_server (карточка), get_power_status, для bare-metal — get_server_sensors.
  3. Анализ:
  4. Сервер выключен → предложить power_on (с confirm=true, только с согласия).
  5. Аномалии сенсоров (перегрев, сбой PSU) → рекомендовать поддержку / Remote Hands.
  6. Сформулировать резюме: состояние, вероятная причина, рекомендуемые действия. Деструктивные действия (power_off, reboot, reinstall) — только после явного согласия.

Аргументы: server_id (опционально) .

Сквозные сценарии

Сценарий 1: «Сервер не отвечает, разберись»

Вы пишете ассистенту: «Сервер 12345 не пингуется, проверь что с ним».

Модель (используя troubleshoot_server_prompt или самостоятельно):

  1. get_server (12345) — получает карточку, hostname, IP.
  2. get_power_status (12345) — видит, что питание в порядке.
  3. get_network_status (12345) — проверяет состояние портов, видит, что порт выключен.
  4. Сообщает: «Сервер работает, но сетевой порт выключен. Включить?» — предлагает port_on.
  5. После подтверждения — port_on с confirm=true, проверка связности.

Сценарий 2: «Закажи VPS в Нидерландах под PostgreSQL»

Вы пишете: «Нужен VPS в NL, буду ставить PostgreSQL».

Модель (используя order_server_prompt):

  1. list_presets (NL) → показывает 3 варианта с ценами.
  2. Вы выбираете.
  3. list_os → показывает Ubuntu 22.04, Debian 12 и т.д.
  4. Выбираете.
  5. list_traffic_plans → выбираете трафик.
  6. Собирает root-пароль, hostname, период оплаты.
  7. order_server с dry_run=true → показывает сводку: «VPS vm.small, Ubuntu 22.04, NL, трафик 10 ТБ, $XX/мес. Подтверждаете?»
  8. Вы подтверждаете.
  9. order_server с dry_run=false, confirm=true → возвращает callback-ключ.
  10. Модель: «Заказ создан, деплой 10–30 минут. Проверю статус через check_task».

Сценарий 3: «Переустанови ОС на сервере 67890 на Ubuntu 24.04»

Вы пишете команду.

Модель (используя reinstall_server_prompt):

  1. get_server (67890) → показывает hostname.
  2. Предупреждает: «Все данные на дисках будут удалены. Подтверждаете?»
  3. Вы подтверждаете.
  4. list_os (67890) → выбираете Ubuntu 24.04.
  5. Собирает новый root-пароль.
  6. reinstall_server с confirm=true и текущим hostname (дополнительная защита).
  7. Если HOSTKEY_ALLOW_DESTRUCTIVE=1 не установлен — объясняет, как включить.
  8. Сохраняет callback, отслеживает через check_task.

Сценарий 4: «Добавь DNS-запись для www.example.com»

Вы пишете: «Настрой A-запись www.example.com → 10.56.121.5 в зоне example.com».

Модель:

  1. list_dns_domains → проверяет, существует ли зона example.com.
  2. Если нет — add_dns_domain (name: example.com, confirm=true).
  3. add_dns_record (zone: example.com, name: www, type: A, content: 10.56.121.5, confirm=true, ttl=3600).
  4. Подтверждает успех.

Для SRV-записи модель дополнительно заполнит proto, priority, weight, port, target. При ошибке SOA — mname/rname .

Безопасность: как устроены защиты

MCP-сервер HOSTKEY реализует многоуровневую защиту от случайных деструктивных действий:

  • Уровень 1: confirm=true. Все write-вызовы требуют явной передачи confirm=true. Без него сервер ничего не меняет . Модель по инструкции должна получать согласие пользователя перед передачей confirm=true.

  • Уровень 2: dry_run для заказов. order_server по умолчанию работает в режиме проверки — только показывает доступность и стоимость, не списывая деньги .

  • Уровень 3: HOSTKEY_ALLOW_DESTRUCTIVE=1. Для переустановки ОС, PXE и отмены услуг требуется явно установить эту переменную окружения . Без неё сервер откажет в выполнении.

  • Уровень 4: повторный hostname для переустановки. reinstall_server требует не только confirm=true, но и повторного ввода текущего hostname сервера . Это защита от случайного выбора не того сервера.

  • Уровень 5: маскировка секретов. Пароли и токены маскируются в ответах .

Решение проблем

  • «Сервер не подключается» — проверьте, что API-ключ действителен. Вызовите get_account_info — если возвращает данные, подключение работает.
  • «DNS-запись отклонена» — убедитесь, что у API-ключа есть право pdns/edit .
  • «Деструктивная операция заблокирована» — установите HOSTKEY_ALLOW_DESTRUCTIVE=1 в окружении MCP-сервера (в env конфигурации или в .env при сборке из исходников).
  • «Долгая операция не завершается» — используйте check_task с callback-ключом. Для деплоя типичное время — 10–30 минут . Не запускайте повторную операцию, пока идёт текущая.
  • «Инструмент не находит сервер» — проверьте ID сервера через get_servers. ID — числовой, не путайте с hostname.

Информация

Полезные ссылки:

Примечание

Эта документация покрывает основные сценарии и инструменты. Полный список из 132 инструментов с параметрами доступен через tools/list в вашем MCP-клиенте.

question_mark
Я могу вам чем-то помочь?
question_mark
ИИ Помощник ×