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

MCP-сервер Рокет Хоум позволяет ИИ-агенту — Claude, Cursor или вашему собственному на любом MCP-клиенте — видеть дом, читать состояние приборов, управлять ими и работать с автоматизациями. Агент получает ровно те права, которые вы выдали его токену. Остальное в доме он не видит, а запрещённые действия сервер отклоняет.

Примечание

Что понадобится. Аккаунт rocket-home.ru с хотя бы одной локацией и MCP-клиент, который умеет подключаться по Streamable HTTP с заголовком Authorization. Если клиент этого не умеет, подойдёт мост mcp-remote (см. Claude Desktop и клиенты без заголовков).

Быстрый старт¶

Откройте ai.rocket-home.ru и нажмите «Войти через Rocket Home». Войдите в свой аккаунт rocket-home.ru и разрешите доступ. Откроется страница «Токены агентов».
В блоке «Создать токен» заполните «Название», например «Claude на ноутбуке». Название поможет потом найти токен в списке и в журнале.
В «Права доступа» оставьте значение по умолчанию: «Устройства» → «Для всех» с «Чтение состояния». С такими правами агент видит дом и читает состояние приборов, но ничего не включает и не трогает автоматизации. Расширить права можно позже, см. Права токена.
Нажмите «Создать», затем «Копировать».

Предупреждение

Токен показывается один раз. Если не успели сохранить, отзовите токен и создайте новый. Токен даёт доступ к вашему дому: не публикуйте его и не коммитьте в git. Держите его в переменной окружения или в менеджере секретов.
Подключите клиента по инструкции из раздела Подключение клиентов.
Попросите агента: «Какие комнаты есть у меня дома?».

Вы должны увидеть список ваших локаций и комнат. Вызов появится на вкладке «Логи» на ai.rocket-home.ru.

Что умеет агент¶

У каждого действия есть инструмент MCP. Агент видит только те инструменты, которые разрешены его токену.

Действие	Инструмент	Какое право нужно
Узнать локации, комнаты, приборы и их возможности	`list_structure`	любое право на приборы
Прочитать текущее состояние прибора	`get_device_status`	«Чтение состояния»
Включить, выключить, задать значение	`control_device`	«Управление»
Посмотреть автоматизации	`list_automations`, `get_automation`	«Запуск»
Включить или выключить автоматизацию, задать её параметры	`toggle_automation`, `set_automation_argument_values`	«Запуск»
Создать автоматизацию	`create_automation`	«Создание, правка и удаление» в режиме «Для всех»
Изменить или удалить автоматизацию	`update_automation`, `delete_automation`	«Создание, правка и удаление»

Кроме инструментов сервер предлагает два готовых prompt: rocket_home_device_control (управление прибором) и rocket_home_automations (работа с автоматизациями). Оба принимают необязательный аргумент goal — что вы хотите сделать.

Права токена¶

Права настраиваются в «Права доступа» при создании токена и потом в «Изменить». Они состоят из двух независимых блоков: право на приборы не даёт доступа к автоматизациям, и наоборот.

«Устройства»

«Для всех» — правило действует на все приборы всех ваших локаций.
«Выборочные правила» — права только на выбранные объекты. В группах «Локации», «Помещения» и «Устройства» нажмите «Добавить объект», выберите объект и отметьте действия. Если у прибора есть своё правило, действует оно. Если нет — правило его помещения, а если нет и его, то правило локации.
«Чтение состояния» — агент видит прибор и читает его состояние.
«Управление» — агент ещё и отправляет команды. Управление включает чтение.

Вместе с любым правом на прибор агент видит его в структуре дома. Приборов без прав в ответе list_structure нет.

«Автоматизации»

«Ничего не выбрано» — доступа к автоматизациям нет. Это значение по умолчанию.
«Запуск» — видеть автоматизации, включать и выключать их, задавать значения параметров.
«Создание, правка и удаление» — всё, что даёт «Запуск», плюс создание, изменение и удаление.

Важно

Автоматизация работает от имени своего создателя. Когда агент включает её через «Запуск», права его токена на приборы этой автоматизации не проверяются. Если агент не должен косвенно управлять приборами, не давайте ему «Запуск» на такие автоматизации.

Создавать новые автоматизации можно только с «Создание, правка и удаление» в режиме «Для всех». Кроме того, у токена должна быть запись в «Устройствах» на локацию автоматизации, «Управление» на приборы, которыми она командует, и «Чтение состояния» на приборы, которые она проверяет. Ограничение по локациям в «Устройствах» действует и на автоматизации: агент видит только автоматизации тех локаций, на которые у него есть запись.

Готовые наборы прав¶

Только смотреть. «Устройства» → «Для всех» → «Чтение состояния», «Автоматизации» → «Ничего не выбрано». Это значение по умолчанию: агент отвечает на вопросы вроде «какая температура в спальне», но ничего не меняет.

Управлять одной комнатой. «Устройства» → «Выборочные правила» → «Помещения» → «Добавить объект» → нужная комната → «Управление». Агент видит и переключает только приборы этой комнаты.

Помощник по автоматизациям. «Устройства» → «Для всех» → «Управление», «Автоматизации» → «Для всех» → «Создание, правка и удаление». Агент собирает и правит автоматизации по вашему описанию. Язык, на котором агент описывает триггеры и шаги, — Язык автоматизаций.

Права в формате JSON¶

Кнопка «Raw» показывает права как JSON, их можно править прямо там. Ключи — locations, rooms, devices и automations. Значение ключа бывает трёх видов:

"*" — все объекты, все действия;
{"*": [права]} — все объекты, только перечисленные действия;
[{"id": "<uuid>", "scopes": [права]}] — только перечисленные объекты.

Права приборов: smarthome.structure.read (видеть в структуре), smarthome.devices.status («Чтение состояния»), smarthome.devices.control («Управление»). Права автоматизаций: smarthome.automations.run («Запуск»), smarthome.automations.manage («Создание, правка и удаление»).

Чтение всех приборов, без автоматизаций (так сохраняется значение по умолчанию):

{"devices": {"*": ["smarthome.structure.read", "smarthome.devices.status"]}, "automations": []}

Чтение приборов одной локации и запуск любых автоматизаций в ней:

{
  "locations": [
    {"id": "a028e638-a604-4bca-b6d0-3b3a2e25e90d",
     "scopes": ["smarthome.structure.read", "smarthome.devices.status"]}
  ],
  "automations": {"*": ["smarthome.automations.run"]}
}

Если в JSON нет ни locations, ни rooms, ни devices, доступа к приборам нет. Если нет automations, нет и доступа к автоматизациям. Права, которые не дают ни одного действия, сервер не сохраняет: в этом случае появится ошибка «права токена не дают ни одного действия». Полный разбор правил — в репозитории MCP-сервера, файл docs/agent-token-permissions.md.

Срок действия и отзыв¶

«Срок действия (необязательно)»: «Месяц», «Год» или своя дата. Токен работает до конца выбранного дня по UTC. «Очистить» делает токен бессрочным, в списке он помечен «бессрочный».
«Изменить» в списке «Ваши токены» меняет название, права и срок. Сам токен при этом остаётся прежним, перенастраивать клиента не нужно.
«Отозвать» выключает токен сразу: следующий же запрос агента получит отказ.
У одного аккаунта может быть до 100 токенов. Заведите отдельный токен на каждого агента: так права настраиваются точнее, а в журнале видно, кто что делал.

Подключение клиентов¶

Адрес сервера — https://ai.rocket-home.ru/mcp, транспорт — Streamable HTTP. Токен передаётся в заголовке Authorization: Bearer <токен>. Ниже вместо YOUR_TOKEN подставьте токен, который начинается с rh_agent_.

Claude Code¶

Выполните в терминале:

claude mcp add --transport http rocket-home https://ai.rocket-home.ru/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Проверка — команда claude mcp list. Вы должны увидеть строку rocket-home: https://ai.rocket-home.ru/mcp (HTTP) - ✔ Connected.

Чтобы токен не оказался в git, а сервер был у всех в проекте, положите в корень проекта файл .mcp.json со ссылкой на переменную окружения:

{
  "mcpServers": {
    "rocket-home": {
      "type": "http",
      "url": "https://ai.rocket-home.ru/mcp",
      "headers": {"Authorization": "Bearer ${RH_AGENT_TOKEN}"}
    }
  }
}

и задайте переменную перед запуском: export RH_AGENT_TOKEN=YOUR_TOKEN.

Claude Desktop и клиенты без заголовков¶

Claude Desktop подключает удалённые серверы как «коннекторы» с входом по OAuth. MCP-сервер Рокет Хоум принимает только токен агента, поэтому подключайте его через мост mcp-remote: локальную программу, которая передаёт запросы на сервер и добавляет заголовок. Нужен установленный Node.js.

Откройте в Claude Desktop Settings → Developer → Edit Config и добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "rocket-home": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://ai.rocket-home.ru/mcp",
               "--header", "Authorization:${AUTH_HEADER}"],
      "env": {"AUTH_HEADER": "Bearer YOUR_TOKEN"}
    }
  }
}

Перезапустите Claude Desktop. Заголовок задаётся через env, а в args после двоеточия нет пробела: так мост не разрежет значение на части.

Тот же мост подходит любому клиенту, который запускает MCP-серверы как локальные программы (stdio), но не умеет добавлять заголовок к удалённому серверу.

Cursor¶

Добавьте сервер в ~/.cursor/mcp.json (для всех проектов) или в .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "rocket-home": {
      "url": "https://ai.rocket-home.ru/mcp",
      "headers": {"Authorization": "Bearer YOUR_TOKEN"}
    }
  }
}

Затем откройте настройки Cursor, раздел MCP, и проверьте, что сервер rocket-home включён и у него появились инструменты.

n8n, OpenClaw и другие клиенты¶

Подойдёт любой клиент MCP, у которого можно указать:

адрес https://ai.rocket-home.ru/mcp;
транспорт Streamable HTTP (иногда он называется просто «HTTP»). Старый транспорт «HTTP + SSE» сервер не поддерживает;
заголовок Authorization со значением Bearer YOUR_TOKEN. Если в настройках есть выбор типа авторизации, выберите «Bearer» или «Header», не OAuth.

Проверка через curl¶

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

curl -sS https://ai.rocket-home.ru/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_structure","arguments":{}}}'

Ответ приходит в формате Server-Sent Events: строка event: message и строка data: с JSON-RPC. В result.content[0].text лежит структура дома:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"[{\"id\": \"a028e638-…\", \"title\": \"Дом\", \"timezone\": \"Europe/Moscow\", \"rooms\": [{\"id\": \"a02bfb67-…\", \"title\": \"Зал\", \"devices\": [{\"id\": \"a2feccc7-…\", \"title\": \"Ночник\", \"type\": \"light.lamp\", \"capabilities\": [{\"name\": \"on\", \"kind\": \"capability\", …}]}]}]}]"}]}}

Список разрешённых токену инструментов покажет тот же запрос с {"jsonrpc":"2.0","id":2,"method":"tools/list"} в теле.

Журнал вызовов¶

На вкладке «Логи» (страница «Логи событий MCP») в реальном времени видны запросы ваших агентов: время, метод, инструмент, токен, код ответа и длительность. Фильтры «Токен:» и «Tool:» сужают список, «Заморозить» останавливает прокрутку, «Очистить» удаляет журнал.

Аргументы вызовов и ответы инструментов в журнал не попадают. Хранятся последние 500 событий; более старые удаляются автоматически.

Примечание

Ошибка инструмента (например, отказ по правам) в журнале выглядит как успешный запрос с кодом 200: по протоколу MCP она передаётся внутри ответа. Причину показывает сам агент.

Отвязать или удалить аккаунт MCP¶

В меню «Выйти ▾» на ai.rocket-home.ru есть два действия.

«Отвязать аккаунт» — отзывает у MCP-сервера доступ к Рокет Хоум и безвозвратно удаляет все токены агентов, журнал и сеансы входа. После нового входа токены придётся выпустить заново и заменить в настройках агентов. Имя и email остаются как учёт привязки.
«Удалить аккаунт MCP» — то же самое плюс удаление имени и email. Для подтверждения введите DELETE. Ваш аккаунт rocket-home.ru, дома, приборы и автоматизации не затрагиваются.

Чтобы выключить одного агента, достаточно «Отозвать» его токен.

Типичные проблемы¶

401 invalid or expired agent token: Токен введён с ошибкой, отозван, у него истёк срок или аккаунт отвязан. Проверьте токен в «Ваши токены». Если его там нет, создайте новый и замените в настройках клиента.
401 only agent tokens or no auth allowed for MCP: В заголовке передан не токен агента, а другой ключ, например токен API rocket-home.ru. Нужен токен со страницы «Токены агентов», он начинается с rh_agent_.
authentication required: send Authorization: Bearer rh_agent_…: Клиент подключился без заголовка Authorization. Список инструментов он при этом получит, но вызвать их не сможет. Добавьте заголовок (см. Подключение клиентов).
Агент не видит нужный инструмент или говорит, что прибора нет: Токену не хватает прав: инструменты и приборы без прав скрыты. Откройте «Изменить» у токена и добавьте право (см. таблицу в разделе «Что умеет агент»). Изменения действуют со следующего запроса агента.
доступ к устройству запрещён правилами токена: <id>: Прибор виден, но для действия нужно право выше, например «Управление» вместо «Чтение состояния». Расширьте права в «Изменить».
автоматизация запрещена правилами токена: <id> или локация … запрещена правилами токена: У токена нет права на эту автоматизацию или нет записи в «Устройствах» на её локацию. Добавьте локацию или автоматизацию в права.
устройство не найдено: <id>: Прибор удалён или id неверный. Попросите агента заново вызвать list_structure.
request status for device …: no status received: Прибор не ответил за 3 секунды: обычно он вне сети или его хаб офлайн. Если в ответе есть last_known, это последнее известное состояние. Что делать с прибором — Что-то не работает.
временная ошибка бэкенда умного дома — повторите позже: Облако Рокет Хоум временно недоступно. Повторите через минуту. Если ошибка не проходит, напишите в поддержку.
access token expired and refresh failed … please log in again: Связь MCP-сервера с вашим аккаунтом rocket-home.ru устарела. Войдите на ai.rocket-home.ru ещё раз, токены агентов при этом продолжат работать.
400 Accept must contain both 'application/json' and 'text/event-stream': Клиент ждёт ответ только в JSON, а сервер отвечает потоком событий. Пришлите оба типа в Accept или подключитесь через mcp-remote.
400 Unsupported protocol version: Клиент назвал версию протокола MCP, которую сервер не знает. Список поддерживаемых версий есть в тексте ошибки. Обновите клиент.
405 Method Not Allowed или 415 Content-Type must be 'application/json': Клиент использует старый транспорт «HTTP + SSE» или шлёт тело не в JSON. Выберите в настройках транспорт Streamable HTTP.

Справочник¶

Адрес	`https://ai.rocket-home.ru/mcp`
Транспорт	Streamable HTTP без сессий: каждый запрос — отдельный `POST` с одним сообщением JSON-RPC. `GET` и `DELETE` отвечают `405`, тело не в JSON — `415`. Ответ приходит как `text/event-stream`.
Заголовки	`Content-Type: application/json` — обязательно; `Authorization: Bearer rh_agent_…` — для вызова инструментов; `Accept` — если указан, то с обоими типами `application/json, text/event-stream`
Версии протокола	от `2024-11-05` до актуальной; клиент и сервер договариваются при `initialize`. Без заголовка `Mcp-Protocol-Version` сервер считает версию `2025-03-26`.
Формат токена	`rh_agent_<ключ>_<секрет>`, 54 символа. Сервер хранит только хэш секрета.
Размер запроса	не больше 1 МиБ
Время ответа прибора	до 3 секунд; состав дома кэшируется на 30 секунд
Инструменты	`list_structure`, `get_device_status`, `control_device`, `list_automations`, `get_automation`, `create_automation`, `update_automation`, `toggle_automation`, `set_automation_argument_values`, `delete_automation`
Prompts	`rocket_home_device_control`, `rocket_home_automations`

Параметры инструментов:

list_structure: Без параметров. Возвращает локации с комнатами и приборами. У прибора есть capabilities — чем управлять: имя, values или range и unit. Есть и properties — что читать. Именно эти имена и значения агент передаёт в control_device.
get_device_status: device_id (UUID, обязательно).
control_device: device_id (UUID), capability (имя из list_structure), value (строка), все обязательны. В ответе — состояние прибора и признак confirmed: подтвердил ли прибор команду.
list_automations: location_id и active — необязательные фильтры.
get_automation, delete_automation: automation_id (UUID).
toggle_automation: automation_id; необязательно is_active (без него — переключить) и arguments (только вместе с is_active=true).
set_automation_argument_values: automation_id и arguments — полный набор значений параметров.
create_automation: location_id, name, triggers, condition_blocks; необязательно description, is_active, lead_seconds, arguments. Формат триггеров и блоков — Язык автоматизаций.
update_automation: automation_id, name, triggers, condition_blocks, lead_seconds, arguments; необязательно description и is_active.

Полные схемы параметров клиент получает в ответе на tools/list.

См. также

Нашли ошибку на странице или не получилось? Напишите нам: rocket-home-ru@yandex.ru или в Telegram-группу https://t.me/RocketHome — укажите адрес страницы и что пошло не так.