Подключение BestrankMCP

BestrankMCP связывает AI-ассистентов (Cursor, Claude Desktop и др.) с внешними продуктами
через MCP-токены. Сейчас поддерживаются Bitrix24 и Jira Server/Data Center.

Один MCP-токен = один продукт. Креды хранятся в разделе Подключения и могут
использоваться несколькими токенами.

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

1. Войдите в административный раздел.
2. Создайте Подключение (меню Подключения в шапке административного раздела; Bitrix24: портал + вебхук/OAuth; Jira: URL + логин/пароль) и нажмите «Проверить».
3. Токены → Создать токен — выберите продукт и подключение, отметьте возможности.
4. Скопируйте ключ токена (показывается один раз).
5. В AI-клиенте укажите https://mcp.bestrank.ru/mcp/ и этот ключ.

Каталог: Инструменты MCP (секции по продуктам).

1. Вход в административный раздел

1. Откройте административный раздел на https://mcp.bestrank.ru (или вашем зеркале инстанса).
2. Войдите под учётной записью администратора (роли admin или superadmin).
3. Разделы Подключения и Токены.

2. Подключения и MCP-токен

2.1. Раздел «Подключения» в админке

В шапке административного раздела откройте Подключения — здесь хранятся учётные данные продуктов (не в AI-клиенте).

1. Подключения → Создать.
2. Выберите продукт: Bitrix24 или Jira Server/Data Center.
3. Заполните поля (адрес портала и вебхук/OAuth для Bitrix24; URL и логин/пароль для Jira).
4. Нажмите Проверить — сервис убедится, что доступ работает.
5. Сохраните подключение.

Одно подключение можно привязать к нескольким MCP-токенам (например, отдельные токены для отделов с разным набором возможностей).

2.2. Создание MCP-токена

1. Токены → Создать токен.
2. Вкладка Основное — имя, срок; продукт (Bitrix24 / Jira / системный) задаётся при создании и не меняется.
3. Вкладка Подключение — выберите сохранённое подключение того же продукта.
4. Пока подключение не выбрано, вкладки Возможности, Данные портала (Bitrix24) и Логи для продуктового токена недоступны.
5. Системный токен (platform) работает без подключения — только заявки MCP и пользовательские промпты.
6. Вкладка Возможности — отметьте инструменты, ресурсы и промпты выбранного продукта плюс системные.
7. Для Bitrix24: вкладка Данные портала — справочники, базы знаний и шаблоны БП
   (подробно в § 8).
8. Вкладка Логи — какие вызовы писать в журнал.
9. Сохраните токен и скопируйте значение ключа — оно показывается один раз.

На что влияет выбор подключения: с каким порталом Bitrix24 или инстансом Jira будет работать AI; какие права REST/API доступны при проверке; для Bitrix24 — сканирование Данных портала и динамические ресурсы с портала.

2.3. Просмотр данных для AI

После сохранения токена откройте Изменить:

• Вкладка Ресурсы — у каждого ресурса кнопка Просмотр: что увидит AI.
• Для Bitrix24: вкладка Данные портала — Просмотр у одобренных справочников, баз знаний и шаблонов БП.

Для шаблонов полей CRM в попапе выберите тип (лид, сделка и т.д.), затем Загрузить.
Для бизнес-процессов выберите сущность и нажмите Загрузить.

Важно: для Bitrix24 просмотр и сканирование портала доступны только если у токена выбрано рабочее подключение и проверка прошла успешно (кнопка Проверить на странице подключения).

3. Учётные данные продуктов

3.1. Bitrix24: входящий вебхук

Если используете входящий вебхук:

1. В портале Bitrix24: Разработчикам → Другое → Входящий вебхук.
2. Создайте вебхук от имени пользователя с нужными правами (задачи, CRM, почта и т.д.).
3. Скопируйте полный URL вебхука из портала и разберите его по частям (см. ниже).

Пример URL вебхука:

https://company.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/

Завершающий слэш в URL на портале можно оставить — при вводе в форму важны домен, ID и ключ.

Эти значения указываются в форме подключения Bitrix24 в разделе Подключения.

OAuth: укажите токен доступа приложения Bitrix24 в том же подключении.

3.2. Jira Server / Data Center

В подключении Jira укажите:

• URL инстанса (например https://jira.company.ru);
• логин и пароль пользователя с нужными правами на проекты и задачи.

После Проверить сохраните подключение и выберите его на вкладке Подключение у MCP-токена с продуктом Jira.

Каталог возможностей Jira — в разделе Jira на странице Инструменты MCP (вверху выберите фильтр Jira).

4. Транспорты MCP

Раздел для администраторов и технических специалистов. Пользователю AI обычно достаточно
адреса /mcp/ и ключа токена из быстрого старта.

Один и тот же набор возможностей доступен через разные способы подключения.
Для продакшена рекомендуется Streamable HTTP (/mcp/).

Авторизация remote-транспортов: Authorization: Bearer … с MCP-токеном из административного раздела.
Legacy SSE на production-сервере выключен по умолчанию — long-lived соединения нагружают prod; включайте только если клиент не поддерживает Streamable HTTP.

5. Подключение в MCP-клиенте

В mcp.json указывайте "type" явно: streamable-http для /mcp/, sse для legacy SSE.

5.1. Streamable HTTP (рекомендуется)

Канонический URL для клиента: https://mcp.bestrank.ru/mcp/ (только HTTPS, завершающий /).
Указывайте его в mcp.json, curl и сторонних MCP-клиентах (MiniMax Code и др.) — так не зависите от редиректов балансировщика.

Обязательные заголовки для Streamable HTTP:

Без Accept сервер отвечает 406 Not Acceptable.

Endpoint: https://mcp.bestrank.ru/mcp/.

5.1.1. Cursor — пример mcp.json

{
  "mcpServers": {
    "bestrank-bitrix24": {
      "type": "streamable-http",
      "url": "https://mcp.bestrank.ru/mcp/",
      "headers": {
        "Authorization": "Bearer ВАШ_MCP_ТОКЕН",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Данные Bitrix24 и Jira настраиваются в Подключениях и привязываются к токену на вкладке Подключение.
Отдельные заголовки продуктов в AI-клиенте не нужны и не поддерживаются.

5.1.2. Проверка через curl

curl -X POST "https://mcp.bestrank.ru/mcp/" \
  -H "Authorization: Bearer ВАШ_MCP_ТОКЕН" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

5.1.3. Поведение сервера

Сервер BestrankMCP на пути /mcp применяет edge-правила до обработки JSON-RPC:

Редиректы http → https на уровне хостинга по-прежнему возможны до приложения; для надёжности клиенту лучше сразу указывать https://mcp.bestrank.ru/mcp/.

Для администратора инстанса (self-hosted): переменная MCP_REQUIRE_HTTPS=true запрещает любые не-HTTPS запросы к /mcp (включая локальные без прокси). По умолчанию отклоняется только явный X-Forwarded-Proto: http от балансировщика.

Browser-тестеры (MCP Playground, Agent Studio и т.п.): Cursor и smoke CORS не используют. Чтобы открыть /mcp/ из браузера, задайте MCP_CORS_ORIGINS=* (как у публичных docs MCP) или allowlist конкретных origin через запятую. Пустое значение — CORS выключен. Preflight OPTIONS при включённом CORS отвечает без Bearer.

5.2. Legacy SSE (опционально)

Доступен только если администратор включил MCP_ENABLE_SSE=1 на сервере.

• SSE-поток: GET https://mcp.bestrank.ru/mcp-sse/sse
• JSON-RPC: POST https://mcp.bestrank.ru/mcp-sse/messages/

Тот же заголовок Authorization, что и для /mcp/. Учётные данные продукта хранятся в выбранном подключении токена.

В конфиге клиента (type: sse) в поле url указывайте только адрес SSE-потока — https://mcp.bestrank.ru/mcp-sse/sse (метод GET). Адрес …/mcp-sse/messages/ (POST, JSON-RPC) клиент подставляет по протоколу MCP; в url его указывать не нужно.

5.2.1. Cursor / Claude Desktop

{
  "mcpServers": {
    "bestrank-bitrix24-sse": {
      "type": "sse",
      "url": "https://mcp.bestrank.ru/mcp-sse/sse",
      "headers": {
        "Authorization": "Bearer ВАШ_MCP_ТОКЕН"
      }
    }
  }
}

Если Cursor не подключается к чистому SSE, используйте bridge mcp-remote:

{
  "mcpServers": {
    "bestrank-bitrix24-sse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.bestrank.ru/mcp-sse/sse",
        "--header",
        "Authorization: Bearer ВАШ_MCP_ТОКЕН"
      ]
    }
  }
}

Учётные данные Bitrix24 и Jira хранятся на сервере в Подключениях и привязаны к MCP-токену.
Отдельные заголовки продуктов в клиенте не поддерживаются.

После сохранения конфигурации перезапустите MCP-соединение в клиенте. Успешное подключение можно проверить в административном разделе в разделе Сессии (для HTTP-транспортов).

6. Какие возможности доступны

Полный каталог с описаниями — на Инструменты MCP. Вверху страницы выберите продукт в фильтре (Bitrix24, Jira, все).

Что именно увидит AI, задаётся на вкладке Возможности токена (разрешённый список) и правами учётной записи в выбранном подключении (проверка при создании подключения и при работе токена).

Для Bitrix24 по-прежнему доступны группы вроде Задачи, CRM, Календарь и другие — см. каталог с фильтром по продукту.

7. Ресурсы MCP

7.1. Tools и Resources

Инструменты (tools) — это действия: «найти сделки», «создать задачу», «прочитать список».

Ресурсы (resources) — справочная информация для ассистента: схемы полей, стадии, шаблоны бизнес-процессов, допустимые значения списков. Клиент читает ресурс, а не «вызывает» его как функцию. Это помогает ассистенту понять структуру данных до обращения к Bitrix24.

7.2. Разрешённый список на токене

На вкладке Ресурсы в форме токена отметьте только нужные справочники и гайды.
AI увидит только выбранные ресурсы.

7.3. Статические и динамические URI

В каталоге не дублируются десятки однотипных URI там, где достаточно шаблона и индекса на портале.

7.4. CRM

• bitrix24://crm/usage-guide — порядок: find → card → related → отчёты.
• bitrix24://crm/portal-dictionary — агрегат: поля, встроенные справочники, statusIndex с entityId для стадий.
• bitrix24://crm/statuses/{entity_id} — один шаблонный resource; конкретный entity_id берётся из portal-dictionary, отдельные URI на каждый справочник стадий в resources/list не публикуются.
• bitrix24://crm/fields/{entity_type_id}, categories/{entity_type_id} — шаблоны с параметром (тип CRM выбирается при чтении).

Подробнее: CRM.

7.5. Бизнес-процессы

• bitrix24://bizproc/entity-bindings — каталог сущностей портала (CRM, смарт-процессы, списки, лента) и binding_key.
• При B24-auth в resources/list — отдельный URI на сущность: bitrix24://bizproc/templates/crm-deal, crm-sp-128, lists-59, feed-42 и т.д. В административном разделе подпись: «Шаблоны бизнес-процессов: …» с названием сущности.
• Шаблоны (read): list_bizproc_workflow_templates, get_bizproc_workflow_template_by_id, resolve_bizproc_entity_binding.
• Runtime (read): resolve_bizproc_document_id, list_bizproc_workflow_instances, summarize_bizproc_workflow_instances, get_bizproc_entity_workflow_snapshot, list_bizproc_workflow_tasks, interaction/validate для запуска и завершения заданий.
• Write (start_*, terminate_*, kill_*, complete_*, delegate_*) — только доверенным токенам; обязателен confirm=true. В picker помечены badge «изменяет данные».
• Рекомендуемый whitelist: read-tools для аналитики; write — отдельно, по необходимости.
• Scope Bitrix24: bizproc; для instances и запуска часто нужны права администратора.
• Группа в административном разделе: Бизнес-процессы с подгруппами (Шаблоны, Экземпляры, Запуск, Задания, Изменяют портал).

Подробнее: Бизнес-процессы.

7.6. Структура компании

• Resources: bitrix24://company-structure/usage-guide, department-fields, team-fields, employee-fields, member-roles.
• Scope Bitrix24: humanresources; группа в административном разделе: Структура компании.
• Write-tools (create_company_*, set_company_node_members, …) — только с confirm=true.

Подробнее: Структура компании.

7.7. Данные портала (справочники и БЗ)

Одобренные на вкладке Данные портала записи доступны как:

• bitrix24://portal/dict/{entry_id} — справочник (iblock-список)
• bitrix24://knowledge-base/collection/{entry_id} — база знаний

См. § 8 и Данные портала.

7.8. Публичная документация на сайте

На сайте Bestrank MCP опубликованы два раздела для администраторов и внедренцев:

Каталог Инструменты MCP описывает возможности сервиса. У конкретного MCP-токена ассистент видит только то, что отмечено на вкладке Возможности в форме токена. Настройка доступа AI — Подключения, Возможности, Ресурсы и Данные портала в административном разделе, а не через публичные страницы сайта.

7.9. Частые вопросы

• Не вижу шаблоны БП для списков — проверьте права Bitrix24 (bizproc), подключение на вкладке Bitrix24 и список на вкладке Ресурсы.
• Много URI стадий CRM — устаревшее поведение; сейчас используйте шаблон statuses/{entity_id} и portal-dictionary.

7.10. Промпты MCP

Промпты — готовые сценарии для ассистента (не путать с инструментами и ресурсами).

Базовые и пользовательские

На форме токена откройте вкладку Возможности → тип Промпты:

1. Отметьте нужные сценарии в каталоге (отдельно от инструментов и ресурсов).
2. При необходимости откройте Создать промпт или Редактировать.
3. Если сценарию нужны инструменты или ресурсы, которых нет в разрешённом списке,
   административный раздел покажет предупреждение «Не хватает…» — сам сценарий при этом можно оставить включённым.

Редактор текста шаблона

В модалке редактирования:

Подписи в списках вида Человеческое имя (технический_id), чтобы было видно, что попадёт в {{tool:…}} / {{resource:…}}.

Зависимости от tools/resources для каталога собираются автоматически из плейсхолдеров в тексте при сохранении. Отдельно задаются только права REST Bitrix24, если они нужны сценарию.

Плейсхолдеры в тексте шаблона:

Группа в списке — навигационная метка (group_name); scopes Bitrix24 задаются отдельно и влияют на отметку доступности по probe.

Базовые сценарии календаря — в Календарь → Промпты.
Сценарии мессенджера — в Мессенджер → Промпты.

8. Данные портала

Обзор вкладки, API и troubleshooting — Данные портала.

8.1. Что это

Вкладка Данные портала объединяет три типа per-token данных Bitrix24 в одной таблице с фильтром:

Для сканирования нужны данные Bitrix24 и проверка прав на вкладке Bitrix24.

Пример строк в таблице реестра

{entry_id} — ID строки реестра на вкладке, не iblock_id / collection_id Bitrix24.

8.2. Справочники портала

На портале Bitrix24 много списков значений: курсы, типы документов, журналы почты, статусы в пользовательских полях CRM. Технически каждый такой список — инфоблок (iblock).

BestrankMCP не отдаёт ассистенту все списки автоматически. Вы сканируете портал, одобряете нужные строки (фильтр Справочники), при необходимости настраиваете Поля (колонки MCP resource).

Подробнее о привязках и лимитах — Списки → Справочники портала.

Пример привязок (колонка Привязки в реестре — где справочник используется на портале):

Один iblock может иметь несколько привязок — в таблице одна строка, все места в колонке Привязки.

Пошаговая настройка

1. Вкладка Bitrix24 — данные портала, Проверить подключение к Bitrix24.
2. Данные портала → фильтр Справочники → Сканировать портал.
3. При необходимости Поля — выбор колонок для bitrix24://portal/dict/{entry_id}.
4. Если элементов ≤ 100 — Одобрить.
5. Вкладка Ресурсы — URI справочника включён (добавляется при одобрении).

Лимит 100 элементов: при большем числе — search_list_dictionary_values / resolve_list_dictionary_value (см. Списки).

После одобрения ассистент получает значения, привязки и elementFields через resource bitrix24://portal/dict/{entry_id}. Для полей CRM — см. CRM.

8.3. Базы знаний

На портале Bitrix24 База знаний 2.0 — отдельные коллекции документов (регламенты, инструкции, FAQ). BestrankMCP не отдаёт все базы автоматически: вы сканируете портал, одобряете нужные коллекции (фильтр Базы знаний), при необходимости ограничиваете запись через Запись.

Пример коллекций

Пошаговая настройка

1. Вкладка Bitrix24 — данные портала, Проверить подключение к Bitrix24 (нужны права на базы знаний).
2. Данные портала → фильтр Базы знаний → Сканировать портал.
3. Одобрить нужные строки (коллекции).
4. При необходимости Запись — снять галочки с mutate-tools, если ассистенту нужно только чтение (по умолчанию после approve разрешены все операции записи).
5. Вкладка Ресурсы — URI bitrix24://knowledge-base/collection/{entry_id} включён (добавляется при одобрении).

После одобрения ассистент читает дерево документов через resource bitrix24://knowledge-base/collection/{entry_id} и tools вроде search_knowledge_base_documents, read_knowledge_base_document_full. Запись в чужую коллекцию вернёт kb_collection_not_allowed.

Подробнее: База знаний → Allowlist.

8.4. Шаблоны бизнес-процессов

Фильтр БП показывает обнаруженные шаблоны только при scope bizproc в probe и embedded-кредах. В реестре approve нет — строки со статусом discovered; доступ ассистенту настраивается на вкладке Ресурсы.

Пример сущностей (binding_key → URI в resources/list):

Каталог всех сущностей портала — resource bitrix24://bizproc/entity-bindings (рекомендуется прочитать ассистенту до вызова tools).

Пошаговая настройка

1. Вкладка Bitrix24 — embedded-креды, probe со scope bizproc.
2. Данные портала → фильтр БП → Scan (или Обновить).
3. Просмотр у строки — preview шаблонов как при MCP resources/read.
4. Вкладка Ресурсы — включите URI bitrix24://bizproc/templates/{binding_key} для нужных сущностей.
5. На вкладке Инструменты — whitelist read-tools (list_bizproc_workflow_templates, snapshot и т.д.); write-tools (start_bizproc_workflow, …) — отдельно, с confirm=true.

Подробнее: Бизнес-процессы → Реестр.

8.5. Частые вопросы (данные портала)

Справочники

Почему один справочник — одна строка, хотя привязок несколько?
Один iblock может использоваться в CRM и в нескольких списках. Дубликаты объединяются; все места — в колонке привязок (фильтр Справочники).

Почему в привязке техническое имя вроде PROPERTY_746?
Bitrix24 не отдал подпись поля. Обновите подпись на портале и выполните Scan снова.

В превью только ID и название, хотя в «Поля» выбрано больше колонок
Нажмите Сохранить в модалке «Поля». Подробнее — Списки.

Ассистент не видит справочник
Статус Одобрен, элементов ≤ 100, ресурс на вкладке Ресурсы. См. § 12.

Базы знаний

Scan не находит базы
Проверьте scope note в probe и embedded-креды на вкладке Bitrix24.

Ассистент не может создать документ
Коллекция Одобрена, но в Запись сняты mutate-tools — включите нужные (create_knowledge_base_document и др.).

Бизнес-процессы

Фильтр БП пуст
Нет scope bizproc в probe или креды не embedded.

В реестре есть шаблоны, ассистент их не видит
Включите URI bitrix24://bizproc/templates/{binding_key} на вкладке Ресурсы и соответствующие tools на вкладке Инструменты.

9. Зачем нужно логирование

Журнал событий в BestrankMCP нужен для:

• аудита — кто и когда вызывал tools от имени портала;
• отладки — почему ассистент получил 403 или пустой ответ Bitrix24;
• контроля нагрузки — какие инструменты используются чаще всего.

Настройки на вкладке Логи токена:

Глобальные параметры статистики и захвата B24 задаются на уровне инстанса (отдельно от вкладки Логи конкретного токена): stats_enabled, stats_b24_capture_enabled, срок хранения.

Без логирования аналитика в административном разделе будет неполной.

10. Аналитика в административном разделе

Раздел Аналитика в меню /admin:

Используйте События для расследования конкретного сбоя, Статистику — для обзора трендов, Сессии — чтобы убедиться, что клиент подключился после настройки mcp.json.

11. Если AI показывает неверные данные

Если ассистент вернул данные, которые не совпадают с Bitrix24, Jira или другой системой:

1. Напишите в чате, что именно неверно и как должно быть.
2. Попросите отправить заявку о проблеме — это доступно с любого MCP-токена.
3. Укажите, какой раздел сбоит (задача, сделка, тикет Jira…), если известно.

Менять подключение или токен для отправки не нужно.

Как следить за своими заявками

Попросите ассистента показать ваши заявки — откроется список с текущим статусом каждой (например: новая, в работе, исправлено).

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

Готовые сценарии: промпт «Мои заявки MCP» на вкладке Возможности токена и раздел Системные возможности.

Администратор, который настраивает токен, может отправить заявку из административного раздела кнопкой «Работает неверно» при просмотре возможности — это отдельный путь для проверки в админке, не обязателен пользователю AI.

12. Частые проблемы

При вопросах по интеграции — bestrank.ru или контакты в подвале сайта.