Как спроектировать MCP-инструменты над существующим API

У внутренней системы есть десятки HTTP-эндпоинтов: поиск заказов, строки, доставки и статусы. Перед регистрацией MCP tools полезно спроектировать небольшой фасад под рабочие вопросы. Разберём контракт и локальную функцию, которая собирает сводку заказа из ответа старой системы. Результатом будет проверенный бизнес-адаптер для последующего подключения к MCP-серверу.

Выберите результат, который нужен пользователю

Для вопроса о заказе сотруднику нужны текущий этап, ожидаемая доставка и причина задержки. Внутреннее API может отдавать их тремя запросами. MCP-инструмент get_order_summary принимает номер заказа и собирает эти данные внутри адаптера. Так модель выбирает понятную операцию, а особенности старой системы остаются в обычном коде.

Не объединяйте в один инструмент несвязанные действия. Получение сводки и изменение адреса доставки требуют разных проверок и полномочий. Для первого достаточно чтения, второе меняет состояние бизнеса. Удобный фасад сокращает технические шаги, сохраняя явные границы операций.

Спроектируйте вход и результат до реализации

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

В результате нужны стабильный order_id, человекочитаемый статус, время актуальности и необходимые сведения о доставке. Если доставка ещё не создана, верните явное состояние pending, сохранив найденный заказ. Ошибку зависимости не следует превращать в «заказ не найден». В MCP можно описать outputSchema и передавать объект в structuredContent; клиент также должен уметь обработать ошибку инструмента.

Соберите адаптер как обычную функцию

Ниже три части исходного ответа сводятся в компактный объект. Внешние запросы в примере заменены фикстурой. В реальном сервере эту функцию вызывает обработчик зарегистрированного tool, а клиент получает её результат через tools/call. До подключения протокола уже можно проверить смысл преобразования.

def order_summary(raw):
    shipment = raw.get("shipment")
    return {"order_id": raw["order"]["id"],
            "status": raw["order"]["status"],
            "delivery": {"state": "scheduled", "date": shipment["date"]}
                        if shipment else {"state": "pending", "date": None},
            "as_of": raw["as_of"]}
raw = {"order": {"id": "O-7", "status": "packing", "internal_flag": 9},
       "shipment": None, "as_of": "2026-10-28T10:00:00Z"}
result = order_summary(raw)
assert result["delivery"]["state"] == "pending"
assert "internal_flag" not in str(result)
print(result)

Подключайте протокол после проверки контракта

Сначала выполните функцию на заказах с доставкой, без доставки и с недоступным источником. Затем проверьте discovery: инструмент виден через tools/list, схема соответствует фактическим аргументам, вызов возвращает ожидаемые поля. Отдельно проверьте заказ, к которому у пользователя нет доступа.

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

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

Следующим этапом добавляйте только те операции, которые закрывают подтверждённые рабочие запросы. Так MCP-каталог остаётся понятным, а старое API можно менять за фасадом, сохраняя контракт, на котором уже основаны сценарии агента.

Продолжить проект на практике

Фасад стоит довести до полноценного контракта с клиентом. В платном курсе AI Agent Integrations PRO: MCP вы соберёте сервер с типизированными инструментами и структурированными ответами, пройдёте discovery и обработку результата. Затем добавите ограничения доступа и тесты, чтобы интеграция работала как часть AI-приложения.

Откройте программу курса и выберите следующий этап своего проекта.

По теме: Структурированный ответ MCP tool: как не потерять типы данных.