Как обернуть свой API в MCP-сервер

Обернуть свой API в MCP - задача не столько техническая, сколько проектная. Код обёртки пишется быстро; вся работа в том, что именно и как вы отдаёте агенту.

Что стоит отдавать

Соблазн - отразить API один в один. Так делать не надо.

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

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

Не отдавайте опасное на старте. Удаление, массовые изменения, операции с деньгами. Их добавляют осознанно, по одной, и обычно с подтверждением человеком - см. безопасность.

Полезный тест перед добавлением инструмента: можете ли вы назвать конкретный вопрос агента, на который он отвечает? Если нет, инструмент не нужен.

Описания решают всё

Это главная мысль статьи. Агент выбирает инструмент по описанию, и от него зависит больше, чем от кода.

Хорошее описание отвечает на четыре вопроса:

• Что делает - одной фразой.
• Когда применять - конкретно, с признаком: «когда известен номер заказа».
• Когда не применять - самый пропускаемый пункт и самый полезный. Он предотвращает лишние вызовы.
• Что вернётся, включая случай «ничего не найдено».

Плохо: «Работа с заказами».

Хорошо: «Возвращает заказ и его позиции по номеру. Применять, когда номер известен. Для поиска заказов клиента есть отдельный инструмент. Если заказ не найден, возвращает пустой результат, а не ошибку».

То же касается аргументов: каждый параметр нужно описать так, чтобы агент понял, что туда класть. Параметр type без перечисления допустимых значений гарантирует ошибки.

И ещё одно: один инструмент делает одну вещь. Инструмент с параметром «режим» на пять значений - это пять инструментов, которые агент будет путать.

Аутентификация

Два сценария, и они устроены по-разному.

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

Пользователей несколько. Токен передаётся при инициализации сессии, и сервер работает от имени конкретного человека. Сложнее, но необходимо там, где важно разграничение доступа.

Правило, общее для обоих: секрет не должен попадать в контекст агента. Не делайте инструмент, принимающий токен параметром: агент увидит его, и он уйдёт провайдеру модели вместе со всем контекстом.

Лимиты

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

Что ограничивать:

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

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

Ошибки

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

Как написать сам сервер - MCP-сервер на Python. Пример на конкретной системе - MCP-сервер для 1С. Общая картина - гид по MCP.