Шлюз коннекторов (MCP)

Шлюз позволяет Коворку и связанным приложениям Вайбкод вызывать инструменты сервисов, подключённых к порталу. Работает по протоколу MCP Streamable HTTP без сессий.

Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: ключ устройства Коворка или допущенного приложения

Кто может вызывать

Коворк использует ключи устройства с назначением cowork-desktop. Приложению нужны явно выданный действующий vibe:connectors и действующее приложение с персональным ключом приложения или OAuth-ключом приложения. Владелец и портал должны совпадать с ключом. Пока функция не включена для портала, маршруты отвечают 404 ROUTE_NOT_FOUND. При включённой функции остальные ключи получают 403 CONNECTOR_KEY_NOT_ALLOWED.

Приложение действует от лица владельца ключа, а не зрителя страницы или пользователя из заголовков. Оно видит только общие подключения PORTAL, разрешённые правилом администратора и правами владельца. Скоуп не создаёт подключения и правила. Точный белый список: GET /v1/connectors, POST /v1/connectors/mcp, GET /v1/connectors/write-tickets/{id} и GET /v1/me; остальные ручки и операции хоста, включая заявки и управление подключениями, закрыты.

Допущенное приложение получает data.connectorHost в GET /v1/me: host = VIBE_APP, applicationId, connectionScope = PORTAL, mcpUrl = /v1/connectors/mcp и confirmationMode = web_owner. Отсутствие блока не выдаёт доступ. Допуск и права проверяются заново при каждом запросе.

Пока функция выключена, путь отвечает 404 ROUTE_NOT_FOUND на любой запрос — до проверки ключа, метода и тела. Если функция включена только для части порталов или сотрудников, ключ вне этого круга получает тот же 404 сразу после проверки ключа.

Запрос

POST /v1/connectors/mcp

POST /v1/connectors/mcp принимает одно сообщение JSON-RPC 2.0 до 256 КиБ, пакет сообщений отклоняется. Методы: initialize, notifications/initialized, ping, tools/list, tools/call. Когда функция включена, GET и DELETE Коворка отвечают 405, приложения — 403 CONNECTOR_KEY_NOT_ALLOWED.

curl https://vibecode.bitrix24.tech/v1/connectors/mcp \
  -H "Authorization: Bearer YOUR_COWORK_DESKTOP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

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

Мета-инструменты: connectors_available, connectors_find_tools и connectors_run_tool; отдельный инструмент имеет имя slug__tool. Недоступный инструмент возвращает UNKNOWN_TOOL. Для результата принятой операции BRIDGE используйте connectors_get_result.

Успешный платный вызов списывает баланс текущего портала; владелец ключа указан в проводке, приложение и ключ — в журнале вызовов. Сохраняется существующий мягкий суточный лимит с границей дня UTC. Бесплатные вызовы и отказы не списывают баланс. ACCOUNT_FROZEN, INSUFFICIENT_BALANCE, DAILY_CAP_REACHED и COMPANY_BUDGET_EXHAUSTED закрывают исполнение до вызова вендора.

Для WRITE нужны правило администратора READ_WRITE, ключ с правом записи и включённая для портала функция записи. Приложению требуется одобрение владельца в веб-кабинете, заголовок версии десктопа не нужен. Минимальная версия десктопа, включая пустую версию, закрывающую запись, действует только для Коворка. Хост читает собственный билет через API хоста, ждёт решения человека и повторяет вызов с теми же аргументами и ключом. Одобрение потребляется один раз. Платный отказ до исполнения не потребляет уже одобренный билет. Чувствительные аргументы и секреты вендора не попадают в карточку подтверждения или журнал администратора.

Коды ошибок

Ошибки инструментов приходят в ответе tools/call с isError: true и кодом в _meta["vibe/error"].code.

Операции BRIDGE

Каждый запуск BRIDGE, включая вызов через connectors_run_tool, требует UUID в params._meta["vibe/idempotencyKey"]. Это метаданные, а не аргумент инструмента. После таймаута или потери ответа повторяйте то же действие с теми же UUID, аргументами и ключом. Для нового действия создавайте другой UUID. Повтор UUID с другими данными даёт CONNECTOR_OPERATION_CONFLICT; автоматически повторять такой отказ нельзя.

Быстрый READ

Синтетические инструменты bridge_test иллюстрируют контракт. Для своего коннектора используйте имя и схему аргументов из обнаружения. Быстрый READ сразу возвращает итоговый результат инструмента:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bridge_test__quick_read","arguments":{},"_meta":{"vibe/idempotencyKey":"123e4567-e89b-42d3-a456-426614174000"}}}

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"ok\":true}"}]}}

Pending и получение результата

Долгий вызов возвращает pending без isError. Это не ошибка вендора и не окончательный успех. Вызывайте connectors_get_result через tools/call на том же POST /v1/connectors/mcp; отдельного V1-адреса для результата нет:

{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"The operation is in progress. Retrieve its result later by operationId through connectors_get_result."}],"_meta":{"vibe/operation":{"id":"123e4567-e89b-42d3-a456-426614174000","status":"running","retryAfterMs":1000,"expiresAt":"2026-10-12T13:00:00.000Z","resultTool":"connectors_get_result"}}}}

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"connectors_get_result","arguments":{"operationId":"123e4567-e89b-42d3-a456-426614174000"}}}

Соблюдайте retryAfterMs и интервал не менее секунды. Опрос снова возвращает pending либо итоговый результат инструмента. Закрытие браузера, разрыв соединения и HTTP-таймаут прекращают ожидание, но не принятую работу. Не запускайте новое действие ради получения прежнего результата.

Платный WRITE

Отправьте WRITE с новым UUID:

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"bridge_test__approved_write","arguments":{},"_meta":{"vibe/idempotencyKey":"123e4567-e89b-42d3-a456-426614174001"}}}

Если требуется подтверждение, читайте билет через GET /v1/connectors/write-tickets/{id}, дождитесь одобрения владельца в веб-кабинете и повторите тот же вызов с теми же UUID и аргументами. Идентификатор JSON-RPC-запроса может измениться; UUID действия должен сохраниться. Возврат существующей операции выполняется до новой проверки оплаты и WRITE-подтверждения. Потребление подтверждения и резервирование операции атомарны: отказ допуска не расходует подтверждение и не запускает работу. Поэтому потерянный ответ запуска можно повторить без дополнительного эффекта и списания.

Владение, сроки и оплата

Для результата нужны прежние хост, ключ, портал Битрикс24, подключение и поколение авторизации, а также действующие права. Общий владелец не даёт другому приложению или ключу доступ. Переподключение или отзыв доступа скрывает старый результат и запрещает новый запуск под прежней авторизацией. Служебное восстановление продолжает расчёт уже принятой работы: валидный успешный платный результат оплачивается один раз, даже если его содержимое больше недоступно пользователю. Опрос и повтор не создают нового списания.

Цена фиксируется при резервировании операции. Успешное завершение относится к дню завершения по UTC с мягким суточным лимитом; одновременно принятые работы могут превысить этот лимит. До окончательного расчёта журнал показывает Выполняется без суммы оплаты. Завершение сохраняет исходное время вызова и привязку к хосту/приложению. Истёкший результат нельзя восстановить новым UUID; сохранённая запись защиты запрещает повторное исполнение старой операции.

Ошибки операций

Отказы инструмента приходят внутри HTTP 200 с isError: true и _meta["vibe/error"].code. CONNECTOR_OPERATION_CONFLICT — неповторяемый конфликт (HTTP-представление 409); CONNECTOR_OPERATION_NOT_FOUND — нейтральный неповторяемый отказ (HTTP-представление 404), в том числе для недоступного этому пользователю результата. Отсутствующие или неверные метаданные повтора дают INVALID_ARGUMENTS. Ограничения допуска дают BUSY, транспортный таймаут — VENDOR_UNAVAILABLE; ни один из них не доказывает отмену принятой внешней работы. Не превращайте неопределённость в новый WRITE. Существующие ошибки авторизации, недоступного инструмента и оплаты сохраняют силу.