MCP vs API vs CLI: что выбрать для AI-агента?

Агента просят получить все счета. Вызов проходит успешно. В ответе корректный JSON, список выглядит правдоподобно. Только позже выясняется, что ответ учитывал первую страницу.

Именно такой тест я бы провёл перед спором MCP vs API vs CLI. MCP подходит, когда клиенту агента нужно обнаруживать инструменты, CLI удобен агенту в терминале, прямой API даёт явное управление последовательностью действий. В каждом случае нужно проверить, позволяет ли интерфейс выразить задачу целиком и подтвердить её завершение.

Мы воспроизвели одну задачу чтения счетов на реальном коде интерфейсов Norman с синтетическими данными. Маленький набор успешно прочитали все три варианта. Более крупный выявил общую проблему наших операций списка в MCP и CLI. Это узкое сравнение контрактов интерфейсов, без рейтинга моделей и выводов о надёжности production.

Чем MCP, API и CLI отличаются для агента?

REST API предоставляет программе адреса операций, параметры и ответы. CLI упаковывает операции в команды, флаги, стандартный вывод и коды завершения. MCP позволяет клиенту агента находить и вызывать именованные инструменты со схемами входных данных. Этот механизм описан в спецификации инструментов MCP.

Часто это разные уровни одного продукта. CLI обращается к API, и MCP-инструмент может обращаться к тому же API. Обёртка не получает автоматически все возможности backend. Кто-то выбирает, какие аргументы показать, какие значения подставить по умолчанию и какие поля ответа сохранить.

Сейчас этот выбор стал особенно актуален. Первого сентября AuditFile представила платформу агентов с управлением через CLI, API и MCP. Десятого сентября OpenAI выпустила Agents API в публичной бете с управляемой средой исполнения. Это заявления поставщиков, а не доказательства преимущества одного интерфейса. Они превращают выбор инструментов вокруг агента в конкретное продуктовое решение.

Наш предыдущий обзор бухгалтерских MCP-серверов отвечал на вопрос, у каких поставщиков есть сервер. Здесь вопрос уже: способна ли выбранная операция выполнить вашу задачу полностью?

Как мы сравнивали одну задачу со счетами?

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

В эксперименте работали опубликованный пакет Norman CLI, зарегистрированные инструменты счетов Norman через настоящий MCP SDK и класс пагинации backend Norman. Все HTTP-запросы перехватывались и получали ответы из искусственных наборов данных. MCP использовал соединение в памяти. Учётные данные, рабочие сервисы, база данных и языковая модель в тесте не участвовали.

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

Прямой API-клиент переходил по возвращённым ссылкам на продолжение. Для MCP и CLI использовались заявленные операции списка счетов. Перед попытками продолжить чтение мы изучили схему инструмента и справку команды. Наличие параметра в REST API не считалось доказательством существования такого же аргумента инструмента или флага.

Что произошло, когда понадобилась следующая страница?

Все три пути вернули небольшой набор полностью. Все три правильно получили известный счёт за одно обращение к backend. Различие появилось, когда коллекция счетов перестала помещаться на странице.

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

Причина оказалась конкретной. Класс пагинации backend принимает page и page_size. Проверенные обёртки предоставляли limit, передавали его без преобразования и не давали выбрать страницу. Повышение лимита не увеличивало ответ. Прямое использование настоящего API-параметра размера страницы позволяло получить весь большой тестовый набор одним запросом.

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

Один REST-запрос с пагинацией по умолчанию тоже возвращал только первую страницу. API не собирал коллекцию автоматически: цикл выполнял написанный нами клиент. Преимущество здесь заключалось в наличии параметров для продолжения чтения.

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

Может ли агент обойти отсутствие параметра?

Мы попробовали очевидный следующий шаг. CLI отверг неподдерживаемый флаг --page до обращения к backend. Добавленный вне заявленной схемы аргумент page в MCP-вызове при протестированной конфигурации SDK снова возвращал первую страницу. Этот аргумент до backend не доходил.

Результат относится к конкретным версиям, а не к обязательным свойствам MCP или CLI. Другая реализация может предоставлять пагинацию или сама забирать все страницы. Пагинация списка инструментов MCP также не означает автоматического перелистывания счетов, которые возвращает отдельный инструмент.

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

Если у клиента отдельно настроен доступ к API, он может перейти к нему. Это уже сценарий с двумя интерфейсами, и сравнение должно зафиксировать переключение. Такой обход не доказывает, что исходная команда списка самостоятельно выполнила всю задачу.

Какой интерфейс выбрать для рабочего процесса?

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

Для агента в терминале CLI предоставляет команды и машиночитаемый вывод без отдельного подключения инструментов. В знакомстве с Norman CLI описан такой сценарий. Проверяйте справку конкретной команды и её JSON-ответ: большой каталог команд ещё не означает, что все параметры API доступны через терминал.

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

Я бы оставил общей операцию backend и проверял каждую обёртку на одинаковых данных. В статье об агентном harness мы обсуждали выполнение и проверку действий. Полнота интерфейса является ещё одним необходимым условием: более сильная среда исполнения не создаёт отсутствующий аргумент.

Что проверить перед подключением агента?

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

Для неизменяемого тестового набора можно использовать такое условие завершения:

assert next_page is None
assert len(set(returned_ids)) == expected_count

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

Затем проверьте остановку. Может ли вызывающая сторона распознать недостающие данные, объяснить ограничение и прекратить попытки? Изменяет ли повторный вызов запрос по существу? Существует ли доступный и явно настроенный альтернативный путь? Зафиксируйте ответы до того, как начнёте измерять скорость или стоимость.

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