MCP для AI

Вайбкод публикует два MCP-сервера для AI-агентов — подходят для Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf, Gemini CLI и любого другого клиента с поддержкой Model Context Protocol.

• mcp-vibe-api — инструменты для работы с Битрикс24 через API Вайбкод.
• mcp-docs — справочник по REST-методам Битрикс24.

Установка mcp-vibe-api | Инструменты (53) | HTTP-транспорт | mcp-docs | Безопасность

Что можно делать через MCP

Подборка диалогов с AI-агентом и инструментов, которые агент реально вызывает. Помогает оценить возможности mcp-vibe-api и подобрать набор скоупов для ключа.

Аналитика по сделкам

Пользователь: Покажи сумму сделок в работе по каждому ответственному за последний месяц.

Агент по очереди вызывает:

1. aggregate_entities для сущности deals с фильтром по closeDate, агрегатом sum по полю amount и группировкой по assignedById.
2. list_entities для сущности users — чтобы заменить идентификаторы на имена сотрудников.

Скоуп ключа: crm, user.

Создание и публикация бота

Пользователь: Зарегистрируй бота с именем «Помощник» и пришли тестовое сообщение в чат с моим коллегой.

Агент по очереди вызывает:

1. manage_bot с действием register — создаёт бота на портале.
2. manage_bot с действием get_events — получает идентификатор диалога с коллегой из входящего события.
3. manage_bot_messages с действием send — отправляет приветственное сообщение в нужный диалог.

Скоуп ключа: imbot.

Развёртывание приложения на сервере

Пользователь: Подними новый сервер в Bitrix Cloud и разверни туда архив с приложением.

Агент по очереди вызывает:

1. manage_server с действиями list_providers, list_plans, list_regions, list_images — собирает каталог.
2. manage_server с действием create — создаёт сервер в выбранной конфигурации.
3. manage_server с действием get — ждёт, пока статус станет RUNNING и CONNECTED.
4. manage_server_deploy с действием deploy — запускает конвейер развёртывания (загрузка архива, установка, systemd, проверка работоспособности).
5. manage_server_deploy с действием logs — читает журналы при ошибках.

Скоуп ключа: vibe:infra.

Подключение собственного провайдера AI

Пользователь: Добавь мой ключ OpenAI и сделай тестовый запрос к gpt-4o.

Агент по очереди вызывает:

1. manage_ai_credentials с действием list_providers — выясняет идентификатор провайдера OpenAI.
2. manage_ai_credentials с действием create — сохраняет ключ. Провайдер проверяется до записи и возвращает 422 CREDENTIAL_INVALID, если ключ не работает.
3. ai_chat с действием chat и параметром model: "openai/gpt-4o" — отправляет тестовый запрос через AI Router.

Скоуп ключа: vibe:ai.

Оставить запрос в поддержку через AI

Пользователь: Эндпоинт /v1/deals/aggregate иногда возвращает пустой ответ — заведи тикет с подробностями.

Агент по очереди вызывает:

1. get_me — забирает идентификатор портала и текущий тариф для поля context.
2. manage_feedback с действием create — отправляет тикет с категорией BUG, заголовком, описанием воспроизведения и сериализованным context (эндпоинт, тело запроса, код ответа).

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

mcp-vibe-api

Сервер, который даёт AI-агенту доступ к Битрикс24 через API Вайбкод. Дальше — установка, параметры запуска, инструменты, Resources, Prompts и HTTP-транспорт.

Установка

Пакет @bitrix24/mcp-vibecode-api. После установки доступна команда mcp-vibe-api. Нужен Node.js версии 18 или выше — подойдёт любая актуальная LTS-сборка (18, 20, 22).

npm install -g @bitrix24/mcp-vibecode-api

Регистрация в клиенте через CLI

Если клиент умеет управлять MCP-серверами через консоль, конфиг-файл редактировать не нужно — достаточно одной команды.

Claude Code:

claude mcp add vibecode -- mcp-vibe-api --key vibe_api_your_key_here --api-url https://vibecode.bitrix24.tech

Команда добавит сервер в локальный конфиг текущего пользователя. Чтобы поделиться настройкой со всем проектом, добавьте флаг -s project — конфиг попадёт в .mcp.json репозитория. Управлять списком: claude mcp list, claude mcp remove vibecode.

Codex CLI:

codex mcp add vibecode -- mcp-vibe-api --key vibe_api_your_key_here --api-url https://vibecode.bitrix24.tech

Запись попадёт в ~/.codex/config.toml. Передать API-ключ через переменные окружения вместо аргументов: codex mcp add vibecode --env VIBE_API_KEY=vibe_api_your_key_here --env VIBE_API_URL=https://vibecode.bitrix24.tech -- mcp-vibe-api. Для проектного scope создайте .codex/config.toml в корне репозитория и пропишите блок [mcp_servers.vibecode] напрямую.

Gemini CLI:

gemini mcp add vibecode mcp-vibe-api --key vibe_api_your_key_here --api-url https://vibecode.bitrix24.tech

Запись попадёт в ~/.gemini/settings.json. Передать ключ через переменные окружения: gemini mcp add -e VIBE_API_KEY=vibe_api_your_key_here -e VIBE_API_URL=https://vibecode.bitrix24.tech vibecode mcp-vibe-api. Для проектного scope используйте .gemini/settings.json в корне репозитория.

Регистрация через конфиг-файл

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS, %APPDATA%\Claude\claude_desktop_config.json на Windows):

{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--key", "vibe_api_your_key_here", "--api-url", "https://vibecode.bitrix24.tech"]
    }
  }
}

Cursor (.cursor/mcp.json в корне проекта):

{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--key", "vibe_api_your_key_here", "--api-url", "https://vibecode.bitrix24.tech"]
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.vibecode]
command = "mcp-vibe-api"
args = ["--key", "vibe_api_your_key_here", "--api-url", "https://vibecode.bitrix24.tech"]

Запуск без глобальной установки

Если глобально установить пакет нельзя, замените mcp-vibe-api на npx -y @bitrix24/mcp-vibecode-api в любом конфиге выше. Пример для Claude Desktop:

{
  "mcpServers": {
    "vibecode": {
      "command": "npx",
      "args": ["-y", "@bitrix24/mcp-vibecode-api", "--key", "vibe_api_your_key_here", "--api-url", "https://vibecode.bitrix24.tech"]
    }
  }
}

Ключ из одноразового кода

Этот способ нужен, только если владелец передал одноразовый код вместо ключа. Обменяйте код по инструкции «Код вместо ключа»: ключ сохраняется в приватный .env проекта как VIBE_API_KEY. Не переносите его в чат, аргументы запуска или конфигурацию MCP. Исключите .env из git, убедитесь, что он не отслеживается, и установите права 600 до записи секрета (в Windows — эквивалентный доступ только владельцу). Не включайте вывод переменных или трассировку оболочки.

mcp-vibe-api читает окружение своего процесса и не загружает .env автоматически. Родительский клиент должен получить переменную до запуска MCP. В отдельной POSIX-оболочке прочитайте только эту переменную как данные, без исполнения .env, затем из той же оболочки запустите клиент:

set +x
unset VIBE_API_KEY
if ! VIBE_API_KEY=$(LC_ALL=C awk '
  /^VIBE_API_KEY=/ { count++; value = substr($0, 14) }
  END {
    if (count == 1 && value ~ /^[A-Za-z0-9_]+$/) print value
    else exit 1
  }
' .env) || [ -z "$VIBE_API_KEY" ]; then
  unset VIBE_API_KEY
  printf '%s\n' 'Cannot load VIBE_API_KEY from .env. Stop before starting the client.' >&2
  exit 1
fi
export VIBE_API_KEY

После записи или изменения .env обновите окружение родительского процесса и полностью перезапустите MCP-клиент. Изменение файла само по себе не меняет окружение уже работающего клиента. Для GUI-клиента передайте только VIBE_API_KEY при запуске либо используйте поддерживаемый envFile: отдельный приватный файл с единственной переменной VIBE_API_KEY, правами 600, исключённый из git и не отслеживаемый им. Общий .env проекта в envFile не указывайте.

Claude Code, .mcp.json проекта: подстановка переменной окружения передаёт значение из окружения клиента, не сохраняя секрет в файле:

{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--api-url", "https://vibecode.bitrix24.tech"],
      "env": { "VIBE_API_KEY": "${VIBE_API_KEY}" }
    }
  }
}

Codex CLI, ~/.codex/config.toml: список env_vars разрешает передачу переменной из окружения клиента:

[mcp_servers.vibecode]
command = "mcp-vibe-api"
args = ["--api-url", "https://vibecode.bitrix24.tech"]
env_vars = ["VIBE_API_KEY"]

Cursor, .cursor/mcp.json: подстановка ${env:VIBE_API_KEY} берёт значение из окружения клиента:

{
  "mcpServers": {
    "vibecode": {
      "command": "mcp-vibe-api",
      "args": ["--api-url", "https://vibecode.bitrix24.tech"],
      "env": { "VIBE_API_KEY": "${env:VIBE_API_KEY}" }
    }
  }
}

В качестве альтернативы для stdio-сервера Cursor замените поле env на "envFile": "${workspaceFolder}/.env.mcp". Используйте отдельный приватный .env.mcp с единственной переменной VIBE_API_KEY, правами 600, исключённый из git и не отслеживаемый им. Общий .env проекта не подходит для envFile. В конфигурации хранится только ссылка на файл. Эти примеры — для Claude Code, Codex CLI и Cursor. У других клиентов проверяйте собственный механизм передачи окружения.

Для запуска без глобальной установки замените в этих конфигурациях "command": "mcp-vibe-api" на "command": "npx", а в начало args добавьте "-y", "@bitrix24/mcp-vibecode-api". Значение ключа в конфигурацию не добавляйте.

Доставка приложения и MCP

Код приложения может доставить VIBE_APP_KEY, а пакет — VIBE_API_KEY, VIBE_APP_KEY либо обе переменные. Прочитайте весь состав parts и выполните соответствующие exchange.save_steps по инструкции доставки приложения. Сохраните все перечисленные переменные без раскрытия секретов до настройки MCP.

Для каждого сохранённого ключа вычислите локально SHA-256 и сравните первые 16 шестнадцатеричных символов с key_fingerprint для соответствующего env_name из описания доставки или обмена JSON. Затем выполните отдельный обычный GET /v1/me с этим ключом в X-Api-Key и требуйте HTTP 200. Сверьте только поля, перечисленные для этой части в verification[i].compare: значение по каждому response_path в обычном ответе должно совпадать со значением по его expected_path в описании issued. Отсутствие поля или несовпадение значения означает неуспешную проверку. Проверка только API-части не проверяет ключ приложения. При claimed сравните каждую локальную переменную с её key_fingerprint. Если локального ключа нет, владелец перевыпускает его в карточке приложения. Новый код не восстанавливает доставленный ключ. Истечение срока или отмена кода оставляют активные ключи приложения рабочими, поэтому не удаляйте ключ работающего сервера.

Передавайте в процесс MCP только VIBE_API_KEY через окружение родительского клиента по приведённым выше инструкциям для своего клиента. VIBE_APP_KEY принадлежит приложению и не переносится в MCP. Доставка oauth_app без API-части не позволяет настроить MCP этим кодом. После изменения родительского окружения перезапустите работающий MCP-клиент.

Параметры запуска

Ключ и базовый URL передаются флагами командной строки или через переменные окружения. При коллизии флаг побеждает.

Установка ключа через переменную окружения, чтобы не хранить его в конфигах:

export VIBE_API_KEY="vibe_api_your_key_here"
export VIBE_API_URL="https://vibecode.bitrix24.tech"
mcp-vibe-api

Доступ по типу ключа

mcp-vibe-api работает с двумя типами ключей Вайбкод и при старте запрашивает /v1/me, чтобы определить тип. Дальше клиенту отдаются только те инструменты, которые ключ может использовать.

В описании каждой группы инструментов ниже указан тип ключа, который к ней подходит.

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

Все инструменты возвращают JSON. Для специализированных эндпоинтов есть типизированные обёртки — используйте их вместо call_api, когда они доступны: подсказки по параметрам и валидация выше. Инструменты сгруппированы в пять кластеров по типу задачи.

Данные Битрикс24 (28) — ключ портала

Чтение и запись данных портала: CRM-сущности, чаты и боты, расширения для CRM, телефония, файлы, бизнес-процессы, рабочее время. Подходит большинству задач AI-агента.

Сущности CRM и других модулей (10)

Покрывают единый CRUD-интерфейс над 40+ сущностями Битрикс24 — от сделок и контактов до задач, файлов, документов и записей смарт-процессов.

Поддерживаемые сущности: deals, contacts, companies, leads, quotes, activities, products, product-sections, statuses, currencies, deal-categories, requisites, timelines, invoices, items, smart-processes, tasks, calendar-events, files, folders, storages, users, departments, workgroups, chats, catalog-products, catalog-sections, catalog-prices, orders, order-statuses, basket-items, payments, sites, pages, doc-templates, documents, bookings, bizproc-templates, openline-configs, telephony-lines и другие.

Чаты (1)

Скоуп: im. Управляет чатами и сообщениями на стороне пользователя. Для чатов, принадлежащих боту, нужен manage_bot_chat.

Боты (3)

Управление ботами на платформе Битрикс24 — регистрация, чаты, обмен сообщениями. Скоуп ключа: imbot.

CRM-расширения и работа с порталом (13)

Действие download принимает fileId — идентификатор объекта Диска, целое положительное число. Это значение поля id из ответа на upload, а не его fileId. В ответе приходят content с содержимым файла в base64, contentType, size в байтах и filename, когда портал прислал имя файла. Файл больше 10 МиБ отклоняется кодом FILE_TOO_LARGE — за таким обращайтесь к Скачать файл напрямую с тем же ключом API. Отсутствующий файл отвечает ENTITY_NOT_FOUND.

Универсальный вызов API Вайбкод (1)

Пример вызова: call_api({ method: "GET", path: "/v1/calls/statistics" }).

Инструмент читает только JSON-конверты платформы, поэтому часть маршрутов он отклоняет до отправки запроса. Маршрут, отдающий байты, — это NON_JSON_RESPONSE_UNSUPPORTED: за файлами Диска идите через manage_file, за вложениями CRM, чертежами приложений и объектами хранилища — своим HTTP-клиентом. Браузерные точки входа потоков OAuth и подключения отвечают перенаправлением и отклоняются кодом REDIRECT_ROUTE_UNSUPPORTED, потому что переход по нему унёс бы ключ API на адрес, который выбирает не платформа. Полный адрес вместо пути и путь, выходящий за пределы /v1/, отвечают INVALID_PATH.

AI (2) — ключ портала

Подключение AI-моделей через AI Router и управление BYOK-учётными данными. Скоуп: vibe:ai.

Сборка приложений (13) — ключ портала

Создание приложений Битрикс24, развёртывание серверной части на облачных VM, настройка плейсментов в интерфейсе портала.

Инфраструктура (4)

Облачные серверы для приложений и Black Hole-туннели. Скоуп: vibe:infra.

Приложения (5)

Публикация приложений (3)

Плейсменты (1)

Скоуп: placement.

Действие list_bound (под капотом — GET /v1/placements) возвращает список placement-кодов, привязанных на платформе Вайбкод, и — при наличии токена сессии (Authorization: Bearer) — дополнительное поле handlers. Это массив с фактическим URL-обработчиком из Битрикс24 для каждого кода: { placement, handler, misbound, title?, options?, langAll? }. Тип: Array<{...}> | undefined — поле отсутствует, если запрос пришёл без Bearer, у приложения нет привязанных плейсментов или ответ Битрикс24 не удалось получить. Базовый список placements возвращается в каждом из этих случаев.

Исход сверки с аккаунтом читается по полю data.portalSync, а не по наличию или длине handlers: ok — аккаунт вернул все привязанные коды, drift — часть кодов аккаунт не вернул и они перечислены в data.missingOnPortal, unknown — привязка не подтверждена. Причина значения, отличного от ok, приходит в data.portalSyncReason: no_oauth_session, empty_vibe_list, b24_unreachable, unpublished или missing_on_portal. Значение unknown привязку не подтверждает. При причине unpublished (приложение снято с каталога) аккаунт всё равно опрашивается, поэтому handlers и признак misbound в ответе есть — в остальных случаях unknown приходит без handlers.

Поле handlers строится как пересечение нашего App.placements с ответом Битрикс24-метода placement.get. Коды, которые есть в нашей базе и отсутствуют у Битрикс24, в handlers не попадают и дают portalSync равный drift: пользователь видит привязку на платформе Вайбкод, а на аккаунте её нет — например, регистрацию сняли через интерфейс Битрикс24. Базовый список data.placements при этом остаётся прежним, несовместимых изменений в форме ответа нет.

Пример (наличие handlers):

{
  "success": true,
  "data": {
    "placements": ["CRM_DEAL_DETAIL_TAB", "LEFT_MENU"],
    "appId": "5b5c7e6f-…",
    "appTitle": "My App",
    "handlers": [
      {
        "placement": "CRM_DEAL_DETAIL_TAB",
        "handler": "https://myapp.example.com/deal-tab",
        "title": "My tab",
        "options": {},
        "langAll": { "ru": { "TITLE": "Моя вкладка" } }
      }
    ],
    "portalSync": "drift",
    "portalSyncReason": "missing_on_portal",
    "missingOnPortal": ["LEFT_MENU"]
  }
}

В примере выше LEFT_MENU есть в placements и отсутствует в handlers — на аккаунте он не привязан, что и сказано полями portalSync и missingOnPortal. Возвращается повторной регистрацией через bind. Пример без handlers (вызов без Bearer или нет привязок):

{
  "success": true,
  "data": {
    "placements": [],
    "appId": "5b5c7e6f-…",
    "appTitle": "My App",
    "portalSync": "unknown",
    "portalSyncReason": "empty_vibe_list"
  }
}

Платформенное управление (8) — управляющий ключ

Эта группа доступна только управляющим ключам Вайбкод (формат vibe_live_...).

Служебные (2) — любой ключ

Доступны и ключу портала, и управляющему.

Resources

URI вида vibe://... отдают справочные материалы для AI-агента.

Prompts

Готовые мульти-шаговые подсказки для AI-агента. Активируются клиентом по имени.

HTTP-транспорт

Помимо stdio (используется по умолчанию) mcp-vibe-api поддерживает HTTP-транспорт. Подходит для серверных интеграций, где stdio неудобен.

mcp-vibe-api \
  --key vibe_api_your_key_here \
  --api-url https://vibecode.bitrix24.tech \
  --http \
  --http-token "$(openssl rand -hex 32)" \
  --allowed-origins https://your-client.example.com

Клиент отправляет POST http://127.0.0.1:3001/mcp с заголовками:

Authorization: Bearer <token>
Content-Type: application/json

Сервер не запускается, если --http указан без токена. Сами токены не пишутся в журналы — на старте указывается только их источник (флаг или переменная окружения).

mcp-docs

Справочник по REST API Битрикс24: методы, скоупы, плейсменты, типы и категории приложений. Работает офлайн без API-ключа — все данные встроены в пакет.

Установка

Пакет @bitrix24/mcp-docs. После установки доступна команда mcp-docs. API-ключ не нужен — справочник встроен в пакет и работает без сети.

npm install -g @bitrix24/mcp-docs

Регистрация в клиенте

Через CLI:

claude mcp add bitrix24-docs -- mcp-docs
codex mcp add bitrix24-docs -- mcp-docs
gemini mcp add bitrix24-docs mcp-docs

Через конфиг-файл:

{
  "mcpServers": {
    "bitrix24-docs": {
      "command": "mcp-docs"
    }
  }
}

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

Дополнительно сервер публикует ресурс с гайдом по REST API и промпт bitrix24-rest-intro — введение в REST и в синтаксис Вайбкод-прокси.

Прямое использование API Вайбкод без MCP

Если MCP-клиент недоступен, дайте AI-модели API-ключ и ссылку на полный справочник:

Вот мой API-ключ Вайбкод: vibe_api_your_key_here
Полная документация: https://vibecode.bitrix24.tech/llms-full.txt

Опишите вашу задачу...

mcp-vibe-api подключается к любому клиенту с поддержкой Model Context Protocol — Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf, Gemini CLI и другим. Прямой ключ без MCP подойдёт даже клиентам без поддержки протокола, например ChatGPT.

Если владелец передал одноразовый код вместо ключа, передайте агенту код и адрес самоописания. Агент выполнит обмен кода и приватное сохранение ключа. Используйте шаблон без действующего кода:

Мой код для VibeCode платформы: VIBE-… (обменяй на ключ)

Документация: https://vibecode.bitrix24.tech/v1/me

Опишите вашу задачу...

Прямые запросы API затем используют локальный VIBE_API_KEY, не раскрывая его в чате. Для загрузки переменной выполните шаги из раздела «Ключ из одноразового кода». Если у агента нет доступа к HTTP или приватному файлу, попросите владельца выполнить обмен кода вручную по инструкции.

Безопасность

• Передавайте API-ключ через переменную окружения VIBE_API_KEY или флаг --key — не вписывайте ключ в скрипты, репозитории и публичные конфиги. Всегда указывайте вместе с ним VIBE_API_URL или --api-url того Вайбкода, где выпущен ключ.
• Создавайте отдельный ключ для каждого AI-агента и оставляйте только нужные скоупы — ключи vibe_api_... поддерживают список скоупов и срок действия.
• Для серверных сценариев настраивайте IP-вайтлист и фиксированный срок жизни ключа.
• В HTTP-транспорте используйте Bearer-токен из --http-token или VIBE_MCP_HTTP_TOKEN и оставляйте --host 127.0.0.1, если внешний доступ не нужен.
• Если ключ скомпрометирован — отзовите его в разделе ключей и создайте новый.

Смотрите также

• Ключи и авторизация
• Эндпоинты API Вайбкод
• AI Router
• Обратная связь