Bitrix24 سرد ثمانية أخطاء شائعة عند تطوير خوادم MCP لـ LLMs

Разработчик команды AI Битрикс24 выпустил практический разбор ошибок, которые чаще всего ломают MCP-серверы для LLM. Главная мысль простая: MCP выглядит как детерминированная обёртка над API, но управляет этим слоем недетерминированная модель, поэтому привычные инженерные подходы здесь регулярно дают сбой.

Где всё ломается Первая проблема — авторизация.

В спецификации всё выглядит аккуратно: есть OAuth, понятные поля и ожидаемый flow. На практике разные клиенты MCP поддерживают это неравномерно: где-то авторизация работает частично, где-то с кастомными расширениями, а где-то почти не работает вовсе. Для локальных stdio-серверов это не так критично, но как только сервер выходит в сеть, начинается фрагментация.

Именно поэтому команды часто приходят к менее изящному, но стабильному варианту: заранее выпущенным токенам, которые пользователь вручную добавляет в конфиг. Вторая большая ловушка — желание просто завернуть Swagger в MCP один в один. Для разработчика это выглядит логично: каждый API-эндпоинт становится отдельным инструментом.

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

Человек справится, а модель легко потеряет состояние уже на середине маршрута.

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

Как проектировать инструменты

Вывод автора жёсткий, но полезный: MCP-инструмент нужно проектировать не как отражение структуры базы данных, а как действие, понятное пользователю. Если человеку нужно «поставить задачу Ивану на завтра», инструмент должен уметь принять имя, срок и текст задачи, а не заставлять модель отдельно искать user_id, потом task_id и потом связывать сущности. Чем более самодостаточен инструмент, тем выше шанс, что модель выполнит сценарий без сбоев и самодельной оркестрации внутри промпта.

«Инструменты должны отражать намерение пользователя, а не устройство вашей базы данных».

Вторая часть дизайна — тексты. Для модели описание инструмента, его название и поля входной схемы фактически заменяют интерфейс. Она не видит README, не знает архитектуру и не понимает авторские намерения вне JSON-схемы. Поэтому формулировки должны быть семантически плотными: короткими, но точными. Разница между `search_users`, `find_users` и `lookup_user_by_email` для LLM не косметическая, а поведенческая. То же касается ошибок: хорошее сообщение об ошибке не просто сообщает о сбое, а подсказывает, почему это случилось и что попробовать дальше.

Тесты и защита Классические юнит-тесты здесь необходимы, но их недостаточно.

Они проверяют код инструмента, а не то, как именно модель его выберет и вызовет. Поэтому в статье рекомендуют evals: наборы пользовательских запросов, на которых можно смотреть, какой инструмент был вызван, с какими параметрами и насколько ответ соответствует сценарию. Проблема в том, что поведение моделей нестабильно и меняется даже между соседними версиями.

То, что работало на одной версии GPT или Claude, может начать вести себя иначе после обновления, поэтому ручное тестирование в чате пока остаётся обязательной частью разработки. Отдельный блок посвящён безопасности. MCP расширяет поверхность атаки сразу с двух сторон: через пользователя с prompt injection и через данные, которые возвращает сам сервер или внешние системы.

Если инструмент имеет лишние права, модель рано или поздно попробует сделать больше, чем должна. Практический рецепт такой: минимум привилегий, фильтрация внешнего контента, явное подтверждение для необратимых действий и ограничение размера ответа. Автор советует возвращать только нужные поля, максимум 10–20 записей за раз и всегда помнить, что даже сильная модель перестаёт быть полезной, когда её контекст забит сырым JSON.

Что это значит MCP-серверы быстро переходят из экспериментов в

продакшн, и вместе с этим растёт цена ошибок в дизайне инструментов. Выигрывать будут не те команды, у которых больше API-методов, а те, кто умеет строить короткие, понятные и безопасные действия для модели, а затем постоянно перепроверять их на реальных сценариях.