Суть
MCP-сервер соблазнительно сгенерировать из OpenAPI-спецификации: взял свагер, получил инструменты, готово. Это работает ровно до момента, когда агент видит каталог. Сотня методов, названных языком системы, а не языком задачи, — и модель начинает разбираться, что из этого комбинировать, вместо того чтобы делать дело.
Фасад переворачивает подход: сервер — это тонкая оболочка, которая формулирует что можно сделать в терминах предметной области. проверить_клиента, создать_заявку, статус_заявки — а остальные сто двадцать методов остаются внутри и вызываются сервером самостоятельно.
Зачем это нужно
Контекст модели ограничен, и описания инструментов расходуют его до того, как начнётся работа. Но дело даже не только в токенах: чем больше вариантов, тем ниже точность выбора. Агент, которому дали двести инструментов, тратит шаги на исследование каталога и ошибается в комбинациях.
Канонический антипример — официальный MCP соцсети X: 200+ инструментов, механически выгруженных из OpenAPI. Агент в нём тонет. Противоположный пример — ВкусВилл: сервер стартовал с трёх инструментов, вырос до восьми, и этого хватает, чтобы собрать корзину по рецепту. Инструменты сформулированы так, что понятно, как ими пользоваться, и продуктовая задача решается двумя-тремя вызовами.
Как работает
Укрупняйте до бизнес-операции. Хорошая гранулярность — законченное действие, после которого состояние мира изменилось осмысленно. Плохая — обёртка над одним HTTP-вызовом.
Скрывайте топологию. Агенту не нужно знать, что за фасадом три микросервиса, очередь и таблица в 1С. Это знание не помогает ему выбрать действие, зато занимает контекст и привязывает его к вашей внутренней структуре.
Чтение и изменение — разные вещи. У них разные права и разные политики подтверждения. Смешивать их в одном инструменте — значит терять возможность потребовать подтверждение только на опасном.
MCP — это подключение, а не вся интеграция. Права, политика и журнал действий остаются на вашей стороне; протокол их не приносит. Соответственно, и валидировать прикладной результат — тоже ваша работа: сервер вернул 200, но это ещё не значит, что бизнес-действие выполнено корректно.
Пример
✘ механический экспорт OpenAPI ✔ фасад бизнес-действий
getClientById(...) проверить_клиента(...)
getClientAccounts(...) создать_заявку(...)
getAccountLimits(...) статус_заявки(...)
postApplication(...)
patchApplicationStatus(...) 3–7 операций уровня бизнеса,
... ещё ~120 методов остальное скрыто внутри сервераГде укрупнение превращается в божественный инструмент
Признак не в числе параметров самом по себе, а в том, есть ли среди них переключатель режима. Инструмент с параметром action или mode, от значения которого зависит смысл остальных полей, — это не один инструмент, а несколько, склеенных в одну сигнатуру: модель вынуждена сначала выбрать режим, потом догадаться, какие поля в нём обязательны, и ошибается на обоих шагах.
Рабочие ориентиры границы: у действия один смысл и один результат; обязательных параметров немного и они не зависят друг от друга; описание умещается в пару предложений без слова «если». Как только описание начинает ветвиться — действие пора разрезать обратно.
Как версионировать фасад
Имена действий — это публичный контракт, на который агенты уже завязаны, поэтому меняются они по правилам API, а не по удобству. Изменения за фасадом не должны быть видны снаружи: в этом и смысл фасада — legacy меняется, имя действия остаётся.
Когда меняться должен сам контракт, новое действие добавляется рядом со старым, старое помечается устаревшим и живёт до тех пор, пока по трассировке видно обращения к нему (Agent Observability). Ломающее переименование без переходного периода означает, что все агенты-потребители сломаются одновременно и молча — модель просто не найдёт инструмент и пойдёт придумывать обходной путь.
Когда фасад не нужен
Если инструмент один и он ваш — обвязка избыточна. Правило про 3–7 действий имеет смысл там, где за сервером стоит система с десятками методов; для микроинструмента, который один раз сходил в память и вернул значение, MCP вообще может быть лишним слоем.
Дисциплина своего сервера
Помимо укрупнения действий, разница между учебным сервером и рабочим складывается из нескольких решений, каждое из которых легко пропустить.
Схема — единственный источник правды. Описание инструмента и его схема должны совпадать: если в тексте написано «не больше двадцати позиций», ограничение обязано стоять и в схеме. Расхождение этих двух мест — типовая ошибка, и агент верит схеме, а человек описанию.
Заполняйте аннотации. Пометки вида «только чтение», «разрушающее», «идемпотентное» — это то, на чём хост строит политику подтверждений. Пустые аннотации лишают его опоры: он не может отличить безопасный вызов от необратимого и вынужден либо спрашивать про всё, либо не спрашивать ни про что.
Готовьте вывод для модели, а не для человека. Контекст дорогой: markdown вместо разметки страницы, усечение длинного ответа с явной подсказкой, как получить продолжение, лимиты прямо в схеме.
Вход от модели — враждебный вход. Сервер стоит на границе доверия и обязан проверять аргументы сам: выход за разрешённые пути, подстановка флагов, обращение к чужим ресурсам. Полагаться на то, что модель не пришлёт вредное, нельзя — она транслирует то, что пришло ей на вход, а туда попадают и внешние данные (см. Prompt Injection).
В stdio-транспорте stdout — это канал протокола. Один случайный print в код сервера ломает разбор JSON-RPC на стороне клиента. Логи и отладка идут только в stderr, а шумные инициализации выполняются до старта сервера. Отдельно коварно то, что мусор в stdout может прилететь не от вашего кода, а от установки зависимости при первом запуске.
Связано с
- MCP — сам протокол, примитивы и архитектура
- Tool Calling — как агент вызывает инструменты и почему их описания стоят контекста
- Tool Retrieval — что делать, когда инструментов всё-таки много и укрупнить их нельзя
- Context Window — почему каталог инструментов конкурирует с полезным контекстом
- Agent Governance — права и журнал действий, которые протокол не приносит