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

BestrankMCP связывает AI-ассистентов (Cursor, Claude Desktop и др.) с внешними продуктами
через MCP-токены. Сейчас поддерживаются Bitrix24, Jira Server/Data Center,
Яндекс Метрика, Яндекс DataLens, DaData, МТС Exolve, Bestrank Convertor,
Telegram (личный аккаунт) и Telegram Bot.

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

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

1. Войдите в административный раздел.
2. Создайте Подключение (для Telegram Bot понадобится токен от BotFather) и нажмите «Проверить».
3. Токены → Создать токен — выберите продукт и подключение, отметьте возможности. Для Telegram разрешите нужные диалоги на вкладке Чаты и каналы, для Telegram Bot — адресатов на вкладке Чаты для записи. Для DataLens одобрите воркбуки и датасеты.
4. Скопируйте ключ токена (показывается один раз) и готовый фрагмент конфигурации с уникальным URL токена.
5. В AI-клиенте укажите уникальный адрес вида https://mcp.bestrank.ru/mcp/t/<код>/ (из вкладки Способы подключения карточки токена) и этот ключ. Общий адрес https://mcp.bestrank.ru/mcp/ тоже работает, но при нескольких токенах на одном хосте надёжнее уникальный URL.

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

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

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

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

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

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

1. Подключения → Создать.
2. Выберите продукт: Bitrix24, Jira Server/Data Center, Яндекс Метрика, Яндекс DataLens, DaData, МТС Exolve, Bestrank Convertor, Telegram или Telegram Bot.
3. Заполните поля (адрес портала и вебхук/OAuth для Bitrix24; URL и логин/пароль для Jira; OAuth-токен для Метрики; для DataLens — Organization ID и authorized key JSON; для DaData — API-ключ и секретный ключ; для Exolve — API-ключ приложения; для Convertor — адрес сервиса и API-ключ; для Telegram — номер телефона, код из приложения и при необходимости пароль 2FA; для Telegram Bot — токен от BotFather).
4. Нажмите Проверить — сервис убедится, что доступ работает.
5. Сохраните подключение.

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

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

1. Токены → Создать токен.
2. Вкладка Основное — имя, срок; продукт (Bitrix24 / Jira / Метрика / DataLens / DaData / Exolve / Convertor / Telegram / Telegram Bot / системный) задаётся при создании и не меняется.
3. Вкладка Подключение — выберите сохранённое подключение того же продукта.
4. Пока подключение не выбрано, вкладки Возможности, Данные портала (Bitrix24), Данные DataLens, Чаты и каналы (Telegram) и Логи для продуктового токена недоступны.
5. Системный токен (platform) работает без подключения — только заявки MCP и пользовательские промпты.
6. Вкладка Возможности — отметьте инструменты, ресурсы и промпты выбранного продукта плюс системные.
7. Для Bitrix24: вкладка Данные портала — справочники, базы знаний и шаблоны БП
   (подробно в § 8).
8. Для Яндекс DataLens: вкладка Данные DataLens — Scan и одобрение воркбуков/датасетов
   (подробно в § 3.4).
9. Для Telegram: вкладка Чаты и каналы — найдите чаты, каналы, форумы или личные диалоги
   и нажмите Разрешить; без этого ассистент не сможет читать историю и писать сообщения
   (подробно в § 3.6 и § 7.11).
10. Вкладка Логи — какие вызовы писать в журнал.
11. Сохраните токен и скопируйте значение ключа — оно показывается один раз.

На что влияет выбор подключения: с каким порталом Bitrix24, инстансом Jira, аккаунтом Метрики, организацией DataLens, кабинетом DaData, приложением Exolve или сервисом Convertor будет работать AI; какие права API доступны при проверке; для Bitrix24 — сканирование Данных портала; для DataLens — реестр Данных DataLens.

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).

3.3. Яндекс Метрика

Bestrank MCP читает счётчики и отчёты через API Яндекс Метрики. Нужен OAuth-токен
Яндекса с правом чтения статистики (metrika:read). Токен хранится в подключении
на сервере — в AI-клиент его вводить не нужно.

Как получить OAuth-токен

1. В административном разделе откройте Подключения → создайте подключение
   Яндекс Метрика.
2. Нажмите Получить токен (если на сервере задан ClientID приложения Bestrank)
   или укажите ClientID своего приложения с metrika:read и затем
   Получить токен. Откроется страница Яндекса — войдите под аккаунтом
   с доступом к нужным счётчикам и разрешите доступ.
3. Скопируйте токен со страницы Яндекса (длинная строка) и вставьте в поле
   OAuth-токен.
4. Нажмите Применить — загрузится список счётчиков. При желании выберите
   счётчик по умолчанию.
5. Нажмите Проверить, затем сохраните подключение.

Важно: в поле токена вставляется строка со страницы Яндекса после разрешения
доступа, а не ClientID приложения. Поле ClientID на форме — только помощник
для кнопки «Получить токен», в Connection не сохраняется.

Если кнопка неактивна и ClientID пуст — на сервере не задан
YANDEX_METRIKA_OAUTH_CLIENT_ID. Укажите свой ClientID или попросите оператора
настроить переменную. Токен также можно получить
из своего OAuth-приложения
и вставить вручную.

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

Каталог: Яндекс Метрика на Инструменты MCP
(фильтр Яндекс Метрика). SEO-сценарии — playbooks ym_seo_* поверх отчётных tools.

3.4. Яндекс DataLens

Bestrank MCP читает каталог воркбуков, датасетов и дашбордов через
Public API DataLens.
Нужен сервисный аккаунт организации с authorized key и ID организации DataLens
(x-dl-org-id). Ключ хранится в подключении — в AI-клиент его не вводят.

Для Public API у организации должен быть активный тариф DataLens (платёжный аккаунт /
рабочие места в Настройки → Тарифы и оплата). Строка в биллинге Cloud сама по себе
API не включает.

Ответ API License is required при уже активном тарифе часто означает не «нет
оплаты», а ограничение/проверку лицензии на стороне DataLens для service account.
Bestrank подключается только через SA; для диагностики сравните тот же запрос с IAM
пользователя (yc iam create-token) — см. таблицу ошибок ниже.

В поле Private key вставляйте блок -----BEGIN PRIVATE KEY----- … из JSON authorized key
(поле private_key). Блок BEGIN PUBLIC KEY и весь JSON файла сюда не подходят.

Права сервисного аккаунта

Назначьте роли на организацию в Яндекс Облаке (см. роли DataLens) —
не только «роли в каталоге» folder:

Альтернатива одной ролью на организацию: datalens.admin — полный доступ ко всем воркбукам и уже включает metaReader. Для read-only MCP обычно достаточно visitor + metaReader + Просмотр на выбранные воркбуки.

Как создать подключение DataLens

1. В Яндекс Облаке создайте сервисный аккаунт и назначьте роли из таблицы выше.
2. Создайте authorized key и скачайте JSON (id, service_account_id, private_key).
3. В административном разделе: Подключения → Создать → продукт Яндекс DataLens.
4. Укажите Organization ID (x-dl-org-id) — значение bpf… из настроек DataLens
   (не for-subaccount-…, не folder b1g…, не «Идентификатор DataLens»).
5. Заполните Service account ID, Key ID и Private key.
6. Нажмите Проверить → сохраните.
7. Токены → Создать токен → продукт Яндекс DataLens → выберите это подключение.
8. На вкладке Данные DataLens выполните Scan и одобрите нужные воркбуки/датасеты —
   они станут MCP-справочниками для ассистента.

Типичные ошибки «Проверить» (DataLens)

IAM-токен сервер получает из private key и обновляет сам при истечении
(и при первом 401 после протухания кэша).

Workbook id в подключение не задаётся: ассистент берёт его из dl_v1_list_workbooks
или из одобренного реестра.

Важно: данных нет. После подключения ассистент не получит строки таблиц и цифры
с чартов / дашбордов. MCP DataLens — только навигация по воркбукам, объектам и схеме
полей. Значения отчётов — в UI DataLens. Подробнее: каталог DataLens.

Каталог: Яндекс DataLens на Инструменты MCP.

3.5. DaData

Bestrank MCP обогащает компании, адреса, банки и контакты через
API DaData. Нужны API-ключ и секретный ключ
из личного кабинета. Ключи хранятся в
подключении — в AI-клиент их вводить не нужно.

Как создать подключение DaData

1. Зарегистрируйтесь на dadata.ru и откройте
   профиль → API.
2. Скопируйте API-ключ и секретный ключ.
3. В административном разделе: Подключения → Создать → продукт DaData.
4. Вставьте оба ключа → Проверить (увидите оценку тарифа и остатки лимитов) → сохраните.
5. Токены → Создать токен → продукт DaData → выберите это подключение.

Тарифы и деньги

• Подписка (suggestions / findById): дневной лимит; полнота полей растёт от
  «Лёгкого» к «Максимальному» (тарифы).
• Аффилиаты (findAffiliated) — только «Максимальный».
• Стандартизация (clean) и компания по email / бренд — pay-per-use с баланса
  (~0,20 ₽ и ~7 ₽). Нужен секретный ключ.

Каталог: DaData на Инструменты MCP
(фильтр DaData). Сценарии — playbooks dadata_*.

3.6. Telegram

Bestrank MCP работает с вашим личным аккаунтом Telegram (не ботом): читает диалоги,
ищет чаты и при явном разрешении отправляет сообщения. Сессия хранится в подключении
на сервере — в AI-клиент пароль и код из Telegram вводить не нужно.

Требования на сервере: администратор инстанса должен задать TELEGRAM_API_ID и
TELEGRAM_API_HASH (приложение на my.telegram.org). Если при
создании подключения видите ошибку «Telegram на сервере ещё не настроен» — обратитесь к
оператору.

Как создать подключение Telegram

1. Подключения → Создать → продукт Telegram.
2. Укажите номер телефона в международном формате (+79990000000) → Отправить код.
3. Введите код из Telegram → Подтвердить код.
4. Если на аккаунте включена двухфакторная защита — введите пароль 2FA → Войти.
5. При необходимости укажите прокси (если сервер не достучится до Telegram напрямую):
   вставьте ссылку из Telegram (https://t.me/proxy?...) или заполните поля вручную
   (SOCKS5, HTTP, MTProto).
6. Нажмите Проверить, затем сохраните подключение.

Номер телефона в подключении не сохраняется — только авторизованная сессия и данные
аккаунта (user id, @username).

MCP-токен Telegram

1. Токены → Создать токен → продукт Telegram.
2. Вкладка Подключение — выберите сохранённое подключение Telegram.
3. Вкладка Чаты и каналы — найдите нужные диалоги (Найти по типу: чаты, каналы,
   форумы, личные, архив, избранное) и нажмите Разрешить у каждого чата, с которым
   может работать ассистент. Список Разрешённые показывает уже одобренные.
4. По желанию для группового чата откройте Отправители и ограничьте, чьи сообщения
   читать (пустой список = от всех).
5. Вкладка Возможности — отметьте инструменты, ресурсы и промпты (группы вроде
   «Групповые чаты», «Переписка», «Справка Telegram»).
6. Сохраните токен и подключите AI-клиент к https://mcp.bestrank.ru/mcp/ с ключом токена.

Важно: история и отправка сообщений работают только в разрешённых чатах. Список
чатов аккаунта (list_chats, list_channels и др.) — для поиска; запись и чтение истории
требуют шага «Разрешить» в админке (или соответствующего resource в Возможностях).

Каталог: Инструменты MCP с фильтром Telegram — группы
Групповые чаты, Каналы,
Форумы, Личные чаты,
Папки, Переписка,
Справка. Подробнее о ресурсах и инструментах — § 7.11.

3.7. МТС Exolve

Bestrank MCP работает с API МТС Exolve: SMS, проверка номеров
(Number Lookup / HLR), история звонков, текстовая расшифровка и речевая аналитика.
Нужен API-ключ приложения из личного кабинета Exolve. Ключ хранится в подключении —
в AI-клиент его вводить не нужно.

Как создать подключение Exolve

1. Войдите в личный кабинет Exolve и откройте нужное приложение.
2. Скопируйте API-ключ (раздел ключей приложения; см. также
   как начать работу с API).
3. В административном разделе: Подключения → Создать → продукт МТС Exolve.
4. Вставьте API-ключ → Проверить → сохраните.
5. Токены → Создать токен → продукт МТС Exolve → выберите это подключение.

Что умеет AI

• SMS — отправка (с подтверждением в диалоге), список и счётчик сообщений, альфа-имена отправителя.
• Number Lookup — активность номера, оператор и регион, лучшее время звонка; массовые отчёты по списку номеров.
• Звонки — история и карточка звонка.
• Транскрипт и речевая аналитика — по записи звонка (на одном номере в ЛК Exolve обычно включено что-то одно).

Номера в формате 7XXXXXXXXXX. Документация API: docs.exolve.ru.

Каталог: Инструменты MCP с фильтром МТС Exolve — группы
SMS, Number Lookup,
Звонки, Транскрипт и аналитика.

3.8. Telegram Bot

Telegram Bot — отдельный продукт для бота, созданного через
BotFather. Он не открывает личные диалоги владельца аккаунта:
бот видит только события и чаты, доступные ему по правилам Telegram.

Как подключить бота

1. Создайте бота в BotFather и скопируйте его токен.
2. В административном разделе выберите Подключения → Создать → Telegram Bot.
3. Вставьте токен, нажмите Проверить и сохраните подключение. Bestrank сам
   зарегистрирует webhook; вручную указывать его в BotFather не нужно.
4. Создайте MCP-токен продукта Telegram Bot и выберите это подключение.
5. На вкладке Чаты для записи добавьте числовой ID чата или публичный @username.
   Пустой список запрещает отправку и изменение сообщений.
6. На вкладке Возможности выберите нужные операции: сообщения, медиа, модерацию,
   форумы, Rich Messages или временные сообщения.

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

Каталог: Telegram Bot. Техническая справка:
Инструменты Telegram Bot.

3.9. Bestrank Convertor

Bestrank Convertor — конвертация документов и извлечение таблиц через MCP:
ссылка или текст → Markdown, HTML, PDF и другие форматы; короткие задачи — сразу,
длинные — через очередь (старт → получение результата по id).

Нужны адрес сервиса Convertor и API-ключ. Креды хранятся в подключении —
в AI-клиент их вводить не нужно.

Convertor в Bestrank MCP — отдельный продукт с API-ключом. Параллельно сценарии
конвертации доступны из контура Bitrix через модуль Маркетплейса
Bestrank AI Коннектор. Решения для бизнеса
и приложение Bitrix24
Bestrank AI Коннектор —
это другой канал запуска, не замена подключения Convertor в админке.

Как создать подключение Convertor

1. Получите адрес сервиса и API-ключ Convertor.
2. В административном разделе: Подключения → Создать → продукт Bestrank Convertor.
3. Укажите адрес сервиса и API-ключ → Проверить → сохраните.
4. Токены → Создать токен → продукт Bestrank Convertor → выберите это подключение.

Что умеет AI

• Конвертация — по ссылке или из текста; сразу или через очередь.
• Таблицы — извлечение таблиц из документа по ссылке (sync / async).
• Справка — допустимые форматы и лимит размера файла.

Каталог: Bestrank Convertor — группы
Конвертация, Таблицы,
Система, Сценарии.

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

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

Один и тот же набор возможностей доступен через разные способы подключения.
Для продакшена рекомендуется Streamable HTTP с уникальным URL токена
(https://mcp.bestrank.ru/mcp/t/<код>/). Общий endpoint https://mcp.bestrank.ru/mcp/
остаётся совместимым.

Некоторые AI-клиенты объединяют несколько серверов с одинаковым url в конфиге
(даже при разных ключах). Уникальный path на токен как раз разводит такие endpoint’ы.
Код в path не заменяет ключ: авторизация по-прежнему через Authorization: Bearer ….

Авторизация remote-транспортов: Authorization: Bearer … с MCP-токеном из административного раздела.
На уникальном URL сервер дополнительно проверяет, что path относится к этому же токену.
На URL провайдера (/mcp/pr/<provider>/) сервер проверяет, что продукт токена совпадает с сегментом пути
(иначе 401 provider_mismatch). Этот адрес не заменяет уникальный URL для повседневной работы
в AI-клиенте — он нужен для стабильной ссылки в карточках внешних каталогов.
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/t/<код>/ — скопируйте готовый фрагмент
на вкладке Способы подключения карточки токена (только HTTPS, завершающий /).
Общий URL https://mcp.bestrank.ru/mcp/ тоже принимается; для нескольких токенов на одном хосте
предпочтителен уникальный адрес.

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

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

5.1.1. Пример mcp.json (уникальный URL)

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

Замените <код> и ключ значениями из карточки токена (вкладка Способы подключения).

5.1.2. Пример mcp.json (общий URL)

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

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

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

curl -X POST "https://mcp.bestrank.ru/mcp/t/<код>/" \
  -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.4. Поведение сервера

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

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

Для администратора инстанса (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
• SSE-поток (уникальный): GET https://mcp.bestrank.ru/mcp-sse/t/<код>/sse
• JSON-RPC (общий): POST https://mcp.bestrank.ru/mcp-sse/messages/
• JSON-RPC (уникальный): POST https://mcp.bestrank.ru/mcp-sse/t/<код>/messages/

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

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

5.2.1. Пример mcp.json (уникальный SSE)

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

5.2.2. Пример mcp.json (общий SSE)

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

Если клиент не подключается к чистому 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_ТОКЕН"
      ]
    }
  }
}

Windows (Claude Desktop / Cowork): не используйте "command": "npx" напрямую — путь C:\Program Files\nodejs\npx.cmd ломается при spawn. Обёртка:

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

Пробелы в Authorization: Bearer … внутри args на Windows Claude Desktop режет — передавайте Bearer через env и Authorization:${AUTH_HEADER} без пробела после двоеточия.

5.4. Claude Desktop / Cowork (Windows)

Claude Desktop и режим Cowork читают %APPDATA%\Claude\claude_desktop_config.json и поддерживают только stdio-серверы (command + args). Поля url / type: streamable-http в этом файле не работают — нужен bridge mcp-remote к нашему Streamable HTTP endpoint.

Рекомендуемый конфиг (уникальный URL токена):

{
  "mcpServers": {
    "bestrank-bitrix24": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://mcp.bestrank.ru/mcp/t/<код>/",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ВАШ_MCP_ТОКЕН"
      }
    }
  }
}

Запасной вариант — полный путь к npx.cmd (where npx в PowerShell):

{
  "mcpServers": {
    "bestrank-bitrix24": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.bestrank.ru/mcp/t/<код>/",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ВАШ_MCP_ТОКЕН"
      }
    }
  }
}

Без Node.js — Go-бинарник mcp-remote: укажите абсолютный путь к .exe в "command", те же args без npx.

Проверка до Claude (PowerShell):

$env:AUTH_HEADER = "Bearer ВАШ_MCP_ТОКЕН"
cmd /c npx -y mcp-remote https://mcp.bestrank.ru/mcp/t/<код>/ --transport http-only --header "Authorization:$env:AUTH_HEADER"

Процесс должен оставаться запущенным (stdio). Ошибка "C:\Program" is not recognized означает, что нужна обёртка cmd /c.

После сохранения конфига полностью закройте Claude Desktop (включая иконку в трее) и запустите снова.

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

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

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

Полный каталог с описаниями — на Инструменты MCP. Вверху страницы выберите продукт в фильтре (Bitrix24, Jira, Яндекс Метрика, DataLens, DaData, МТС Exolve, Bestrank Convertor, Telegram, Telegram Bot, все).

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

В сайдбаре вкладки Возможности блок Системные (Система, Производственный календарь, Блог, Сценарии для агента) открывается отдельными пунктами. Фильтр Все группы показывает только продуктовые группы. Сценарии для агента включаются и выключаются галочками как обычные инструменты — удобно, если AI-клиент плохо показывает prompts и resources «из коробки».

Для 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.

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

7.11. Telegram

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

Инструменты (tools)

Инструменты изменяющие данные (отправка, папки, «прочитано») требуют confirm=true
в вызове. Формат текста: plain (обычный), md или html.

Ресурсы (resources)

Чтение и отправка — через tools (get_messages, send_message) с peer из allowlist.
Карточек …/{peer_id} в каталоге ресурсов нет.

Исходящие сообщения через MCP автоматически дополняются пометкой
«Сообщение отправлено через AI-агента и BestrankMCP» со ссылкой на сайт.

Разрешённые чаты (allowlist)

1. На вкладке Чаты и каналы нажмите Найти (тип: все, чаты, каналы, форумы, личные…).
2. У нужной строки — Разрешить.
3. Для отзыва — вкладка Разрешённые → Отозвать.

Без разрешения get_messages и send_message вернут ошибку «чат не разрешён».

Опционально: Отправители у группового чата — если список не пуст, ассистент читает
только сообщения от выбранных людей.

Промпты

Готовые сценарии: краткий пересказ переписки, выжимка по недавним диалогам, подготовка
ответа. Включаются на вкладке Возможности → Промпты (группа Переписка Telegram).

Документация по группам: Справка Telegram, Переписка,
Групповые чаты.

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. Частые проблемы

12.1. Ошибки кнопки «Проверить» (подключения)

Сообщения ниже появляются в разделе Подключения после Проверить. Сначала смотрите
красный текст статуса и при необходимости фрагмент «Ответ API: …».

12.2. MCP-клиент и токен

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