Проектирование MCP-сервера: уроки консолидации инструментов Amplitude

Когда мы только запустили MCP-сервер, запросы клиентов побудили команды в Amplitude предоставить свою функциональность в виде инструментов. Обычно это был один инструмент на один эндпоинт API. Результатом стали избыточное раздувание контекста, пересекающиеся инструменты и множество подсказок, необходимых, чтобы заставить модель вызывать нужный. К июню подключение к нашему серверу загружало 96 инструментов.

Проблема заключалась в том, что каждый инструмент, добавляемый нами для одного клиента, также создавал контекст для каждого клиента. Нишевые запросы редко совпадали с тем, что было нужно другим пользователям, поэтому большинство пользователей платили «контекстную стоимость» за инструменты, к которым они никогда не притронутся.

Тревожным звонком для нас стал случай с клиентом, который запускал Sonnet с окном контекста в 200 тыс. токенов. Когда их клиент перечислял наши инструменты, одно только подключение к нашему серверу расходовало 57% этого объема еще до единого вызова инструмента.

Почему бы просто не полагаться на поиск инструментов?

Некоторые клиенты, такие как Claude Code, поддерживают поиск инструментов, который загружает определения инструментов только тогда, когда они нужны. Для большинства других клиентов включение поиска инструментов — это решение, принимаемое владельцами клиента, а не сервера. По умолчанию все определения загружаются сразу.

На основе нашей телеметрии пользователей Amplitude, подключающихся к серверу, мы пришли к выводу, что безопаснее всего предполагать, что каждый инструмент стоит токенов при каждом подключении, по трем причинам:

• Большинство клиентов по-прежнему по умолчанию загружают каждое определение инструмента сразу.
• В Amazon Bedrock поиск инструментов работает только через API InvokeModel, а не через более распространенный API Converse.
• Корпоративные шлюзы часто кэшируют список инструментов один раз и никогда не обновляют его.

Стоимость токенов — не единственная проблема. Лишние инструменты также увеличивают вероятность ошибки. Чем больше инструментов вы предоставляете, тем чаще модель выбирает не тот. Даже с поиском инструментов собственные оценки Anthropic показывают, что Opus 4.5 делает правильный выбор только в 88% случаев, а старые модели справляются значительно хуже. Anthropic также отмечает, что неправильный выбор инструментов — один из самых частых сбоев, особенно когда инструменты имеют похожие имена.

Создавайте инструменты вокруг результатов, а не эндпоинтов

Мы перестроили наш каталог вокруг трех правил.

1. Не зеркальте свой API

Наши инструменты зеркалили наш API, поэтому модели приходилось вызывать несколько из них в правильном порядке и передавать между ними идентификаторы. Агенты плохо с этим справляются. Самым простым способом предотвратить пересечения и сократить контекст описаний было объединение инструментов на основе того, как они используются.

Мы заменили группы инструментов-эндпоинтов одним инструментом на один объект: кохорта, график, дашборд, флаг. Каждый из них принимает действие и перенаправляет запросы к существующим обработчикам. Количество инструментов для работы с кохортами сократилось с девяти до одного.

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

Объединение также показывает, чего не хватает. Не было инструмента для получения списка кохорт, так как не было соответствующего эндпоинта, поэтому агенты вызывали инструмент поиска кохорт с выдуманными идентификаторами. list — это новый маршрут, а не переименование.

Каждое действие сохраняет свой собственный уровень разрешений и аудиторское событие. Это важно. Если защитить объединенный инструмент на уровне самого рискованного действия, пользователи с правами только на чтение потеряют доступ к чтению; если защитить на уровне наименьшего риска, вы откроете запись. Мы разрешаем доступ для каждого действия до запуска обработчика.

2. Объединяйте функциональность на основе использования, даже если она пересекает границы нескольких продуктов

Границы инструментов должны определяться реальным использованием, а не линиями, которые проводит API. У нас был один поисковый инструмент на продукт: графики, дашборды, блокноты, кохорты. Телеметрия показала, что агенты вызывают два или три из них подряд для одного и того же запроса, потому что нечеткие указания вроде «найди анализ удержания» не уточняют, к какому именно типу объектов это относится.

Теперь существует единый инструмент поиска, который принимает список типов сущностей и ищет по всем ним за один вызов. Это позволяет агенту выполнять более динамичные поисковые запросы по нескольким продуктам, вместо того чтобы поддерживать разрозненные поисковые вызовы для каждой сущности.

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

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

Графики — хороший пример такого процесса. Создание графика в Amplitude состоит из трех шагов: создать изменение графика, сохранить его, добавить на дашборд. Дашборд отклоняет несохраненное изменение, поэтому порядок имеет значение. У нас были инструменты, которые копировали эти шаги: один для запроса данных и возврата идентификатора изменения графика, один для отрисовки графика по этому идентификатору и один для сохранения изменения.

Из 18 703 пользователей, запрашивавших данные, 20% перешли к отрисовке графика и менее 5% сохранили его.

Поле обоснования объясняет почему. Каждый инструмент на нашем сервере имеет один необязательный параметр под названием Tool Rationale, представляющий собой «Краткое объяснение причин вызова этого инструмента». Агенты заполняют его примерно в трех четвертях случаев без каких-либо указаний. Когда запросы останавливаются на этом этапе, обоснования выглядят так: «сохранить изменение графика для анализа на дашборде». Агент пытался сохранить график, но так и не прошел всю цепочку.

Теперь агент отправляет определение и получает данные обратно за один вызов. Сохранение также поддерживается в виде кнопки на отрисованном графике, о чем рассказано в разделе «Приложения MCP» ниже. То, что раньше было 16 инструментами для графиков, превратилось всего в четыре. Подобные многошаговые инструменты стали важным шагом, помогшим нам сократить контекст.

Еще два источника контекста

Навыки и CLI

Описания инструментов загружаются при каждом подключении, поэтому длинные инструкции увеличивают затраты для каждого пользователя. Мы перенесли описания в навыки: файлы уценки (Markdown), которые агент загружает только тогда, когда они нужны для задачи. На сегодняшний день их 37, они охватывают такие темы, как создание графика, диагностика ошибок и составление еженедельной сводки.

Они находятся в публичном репозитории с лицензией MIT (amplitude/mcp-marketplace), который подключается к серверу как подмодуль git. Добавление или исправление навыка — это пул-реквест в этот репозиторий. Те файлы обслуживают как хосты, устанавливающие плагин напрямую, так и хосты, подключающиеся по протоколу MCP.

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

Для редко используемых операций API не добавляйте инструменты. Мы поместили CLI за один инструмент, чтобы новый эндпоинт работал в день своего выпуска. Права доступа определяются с помощью HTTP-метода, а неизвестные команды трактуются как операции записи.

Приложения MCP

Приложения MCP позволяют человеку проверить деструктивное или конфиденциальное действие перед его выполнением, что и делает такие действия безопасными для публичных агентов. Параметр 'confirmed: true' не решает эту проблему. Модель просто установит его.

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

Приложения также позволяют нам добавлять функциональность без увеличения контекста. Инструмент с видимостью, установленной в значение app, может вызываться интерфейсом, но никогда не передается в список модели, поэтому он ничего не стоит при подключении. Не каждый хост пока поддерживает приложения MCP, поэтому сохраняйте резервный вариант.

Развертывание и мониторинг

Мы выпускали каждое изменение за функциональным флагом, по одному на каждую область продукта. Активация флага заменяет старые инструменты на новые за один шаг, поэтому ни одна организация никогда не видит их одновременно. Сначала мы включили флаги для внутренних организаций, а затем поэтапно развернули их для клиентов. Наши менеджеры по работе с клиентами (CSM) знали, что и когда меняется, поэтому могли заранее предупредить аккаунты, у которых были настроены автоматизации на базе старых инструментов.

Пока каждый флаг проходил стадию внедрения, мы следили за двумя показателями:

• Частота ошибок при вызове инструментов
• Частота восстановления: совершил ли агент успешный вызов в течение пяти минут после неудачного?

Восстановление — это то, чему мы отдавали приоритет. Инструмент, который выдает ошибку с понятным сообщением, — это нормально. Инструмент, который выдает ошибку и оставляет агента в неведении, — нет. В несколько объединенных инструментов была добавлена проверка, которой не было в старых, поэтому поначалу частота ошибок возросла. Это означало, что проверка выполняла свою работу: некорректное определение теперь отклоняется на этапе схемы с сообщением, которое подсказывает агенту, что нужно исправить, вместо того чтобы приводить к сбою на бэкенде. Показатель восстановления оставался высоким на протяжении всего развертывания, а значит, агенты использовали эти сообщения для успешного выполнения вызова.

Как только изменения стали доступны всем клиентам, мы проанализировали MCP-сервер, как и любой другой продукт, в Amplitude. Мы отслеживали удержание пользователей в разных организациях и увидели его рост. За последние 12 недель среди внешних клиентов удержание оставалось стабильно высоким. 67% пользователей вернулись через неделю, 59% — через четыре недели, а 50% — через восемь. Быстрее всего росло число активных пользователей. Меньший каталог привлек больше людей и позволил существующим пользователям делать больше.

Начните с того, как агенты используют ваши инструменты

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

Если вы создаете MCP-сервер, обратите внимание на то, где агенты сталкиваются с трудностями. Какие инструменты они вызывают вместе? На каком этапе они останавливаются, не завершив задачу? Используйте эти закономерности, чтобы решить, что объединить, перенести в навык или обработать в пользовательском интерфейсе. Затем измерьте, могут ли агенты завершить работу — и восстановиться, если что-то пойдет не так.