Как подключить AI-агента к Онто через MCP

Главное

Онто предоставляет один и тот же MCP-сервер для разных AI-клиентов. Необязательно использовать Cherry Studio: можно работать в Codex, Claude Code, Qwen Code или другом клиенте с поддержкой Streamable HTTP.

Параметр	Значение
Название сервера	onto
Тип подключения	Streamable HTTP / HTTP
URL	https://app.ontonet.ru/mcp
HTTP-заголовок	X-Onto-Api-Key: ВАШ_API_КЛЮЧ

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

API-ключ — это секрет, аналог пароля. Передавайте его только локальному доверенному клиенту. Не публикуйте ключ в общих чатах, документах, скриншотах и репозиториях.

Шаг 1. Получите API-ключ Онто

Откройте Онто и войдите под своей учётной записью.
Нажмите значок профиля в правом верхнем углу.

Нажмите значок шестерёнки. Откроется Личный кабинет.

Откройте вкладку API-ключи.

Введите название, например mcp-course, и нажмите Создать API-ключ.

Сразу скопируйте ключ: полностью он показывается только один раз.

Убедитесь, что ключ появился в таблице, и проверьте дату окончания действия.

Если значение ключа потеряно, восстановить его нельзя: удалите старый ключ и создайте новый.

Шаг 2. Выберите свой AI-клиент

Вариант A. Codex

В новом локальном чате Codex напишите:

Настрой для меня MCP-сервер onto.
Тип: Streamable HTTP.
URL: https://app.ontonet.ru/mcp
HTTP-заголовок: X-Onto-Api-Key: ВСТАВЬТЕ_СЮДА_ВАШ_API_КЛЮЧ

Сохрани настройку в пользовательской конфигурации Codex.
Для инструментов записи оставь запрос подтверждения.
После настройки проверь подключение и покажи доступные пространства Онто,
ничего не создавая, не изменяя и не удаляя.

Codex может попросить разрешение на изменение пользовательского файла конфигурации. Перед подтверждением проверьте URL и имя заголовка.

Ручной вариант — добавить в ~/.codex/config.toml:

[mcp_servers.onto]
url = "https://app.ontonet.ru/mcp"
http_headers = { "X-Onto-Api-Key" = "ВАШ_API_КЛЮЧ" }
default_tools_approval_mode = "writes"

Затем перезапустите Codex и проверьте сервер командой codex mcp list или /mcp.

Вариант B. Claude Code

В локальной сессии Claude Code напишите:

Настрой MCP-сервер onto для всех моих проектов.
Используй Streamable HTTP:
URL: https://app.ontonet.ru/mcp
Заголовок: X-Onto-Api-Key: ВСТАВЬТЕ_СЮДА_ВАШ_API_КЛЮЧ

После настройки проверь подключение. Никаких операций записи в Онто пока не выполняй.

Ручная команда:

claude mcp add --transport http --scope user onto https://app.ontonet.ru/mcp \
--header "X-Onto-Api-Key: ВАШ_API_КЛЮЧ"

Проверка: claude mcp list. Внутри Claude Code также можно открыть панель /mcp.

Вариант C. Qwen Code

В локальной сессии Qwen Code напишите:

Настрой пользовательский MCP-сервер onto.
Транспорт: HTTP.
URL: https://app.ontonet.ru/mcp
Заголовок: X-Onto-Api-Key: ВСТАВЬТЕ_СЮДА_ВАШ_API_КЛЮЧ
Не помечай сервер как доверенный для автоматической записи.
После настройки проверь подключение только операциями чтения.

Ручная команда:

qwen mcp add --transport http onto https://app.ontonet.ru/mcp \
--header "X-Onto-Api-Key: ВАШ_API_КЛЮЧ" --timeout 60000

Эквивалентная запись в .qwen/settings.json:

{
"mcpServers": {
"onto": {
"httpUrl": "https://app.ontonet.ru/mcp",
"headers": {
"X-Onto-Api-Key": "ВАШ_API_КЛЮЧ"
},
"timeout": 60000,
"trust": false
}
}
}

Вариант D. Cherry Studio

Cherry Studio — один из возможных графических клиентов, а не обязательный инструмент курса.

Откройте Settings → MCP → MCP Servers → Add Server.
Заполните поля:

Параметр	Значение
Name	onto
Type	Streamable HTTP / HTTP
URL	https://app.ontonet.ru/mcp
Headers	X-Onto-Api-Key: ВАШ_API_КЛЮЧ
Long Running Mode	выключен
Timeout	60 секунд

В Cherry Studio поле Headers использует знак =:

X-Onto-Api-Key=api-key-ваш_личный_ключ

Нажмите Save и включите сервер переключателем.
Откройте Work → Agent → Edit → MCP, подключите сервер onto к нужному агенту и начните новый чат.

Если у вас другой MCP-клиент

Найдите в нём добавление удалённого MCP-сервера и укажите:

Name: onto

Transport: Streamable HTTP

URL: https://app.ontonet.ru/mcp

Header name: X-Onto-Api-Key

Header value: ваш API-ключ Онто

Интерфейсы по-разному записывают заголовки: отдельной парой полей, JSON или строкой X-Onto-Api-Key=... / X-Onto-Api-Key: .... Смысл один: отправить HTTP-заголовок X-Onto-Api-Key со значением ключа.

Шаг 3. Универсальная проверка подключения

Независимо от выбранного клиента отправьте агенту:

Используй MCP-сервер onto.

Сначала получи инструкцию по работе с Onto MCP в режиме read_only,

затем покажи список пространств Онто, доступных моей учётной записи.

Ничего не создавай, не изменяй и не удаляй.

Успешный результат: агент вызвал инструменты Онто и вернул список доступных пространств.

Затем можно проверить учебное пространство:

В найденном учебном пространстве покажи доступные типы объектов и кратко

объясни их назначение. Работай только на чтение. Если пространство определить

однозначно нельзя, сначала попроси меня выбрать его из списка.

Безопасная работа

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

Запрос перед операцией записи:

Сначала найди нужное пространство и существующие объекты. Затем покажи точный

план изменений: что будет создано или изменено и какие связи появятся.

Не выполняй запись, пока я явно не отвечу «подтверждаю».

Диагностика

Симптом Что проверить

401 Unauthorized

Правильность и срок действия ключа; имя заголовка X-Onto-Api-Key; отсутствие лишних пробелов и кавычек.

403 Forbidden

Ключ распознан, но у пользователя нет доступа к пространству или операции.

Сервер не подключается

Тип Streamable HTTP и точный URL https://app.ontonet.ru/mcp.

Инструменты видны, но агент их не использует

Включён ли сервер для текущего агента/проекта; поддерживает ли модель tool calling; начат ли новый чат.

Тайм-аут

Повторите простой запрос списка пространств; установите тайм-аут 60–120 секунд.

Выбрано не то пространство

Запретите запись, запросите список пространств и укажите нужное явно.

Итоговый чек-лист

API-ключ создан и сохранён безопасно;
используется URL https://app.ontonet.ru/mcp;
передаётся заголовок X-Onto-Api-Key;
MCP-сервер называется onto и включён;
агент или модель поддерживает вызов инструментов;
тест вернул доступные пространства без изменения данных.