· обновлено
Зачем API-клиенту MCP-сервер
Коллекция в API-клиенте обычно рассчитана на человека: открыть папку, выбрать окружение, нажать Send, прочитать ответ. AI-агент умеет рассуждать о задаче, но сам по себе не знает, какие коллекции у вас сохранены, как подставить переменные и где безопасно выполнить запрос. MCP-сервер превращает эти операции в описанный интерфейс, который агент может обнаружить и вызвать.
Это не означает, что модель получает неограниченный доступ к сети. Хорошая интеграция делает обратное: оставляет выполнение в API-клиенте, где уже есть окружения, секреты, история и правила, а агенту выдаёт только явно разрешённые действия.
Что такое Model Context Protocol
Model Context Protocol, или MCP, — открытый протокол обмена между AI-приложением и внешним источником данных или действий. В его архитектуре есть три роли:
- Host — приложение, в котором работает пользователь и модель: IDE, десктопный ассистент или агентная среда.
- Client — соединение внутри host с конкретным MCP-сервером.
- Server — программа, которая объявляет доступные возможности и выполняет запросы.
Сообщения MCP основаны на JSON-RPC 2.0. Для локального процесса обычно используют stdio, для удалённого сервера — Streamable HTTP. Во время инициализации стороны согласуют версию протокола и возможности, после чего клиент может запросить каталог инструментов.
MCP-сервер публикует три основных вида сущностей. Tools выполняют действия, например запускают сохранённый запрос. Resources отдают контекст для чтения: список коллекций, схему OpenAPI или пример ответа. Prompts задают повторяемые сценарии работы. API-клиенту необязательно реализовывать всё сразу; для начала достаточно небольшого набора tools и resources.
Важно не перепутать направление. MCP-клиент внутри API-инструмента подключается к чужим серверам. MCP-сервер внутри API-клиента, наоборот, позволяет внешнему агенту работать с вашими коллекциями. Tetiva использует второй вариант: встроенный сервер предоставляет контролируемый доступ к сохранённым запросам.
Как агент находит и вызывает запрос
После подключения host получает описание инструментов и их JSON Schema. Условный API-клиент может объявить такой tool:
{
"name": "run_saved_request",
"description": "Run one saved API request in an allowed environment",
"inputSchema": {
"type": "object",
"properties": {
"requestId": { "type": "string" },
"environment": { "type": "string" }
},
"required": ["requestId", "environment"]
}
}
Узнав идентификатор запроса из resource или отдельного поиска, агент вызывает инструмент:
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "run_saved_request",
"arguments": {
"requestId": "orders/get-by-id",
"environment": "staging"
}
}
}
API-клиент подставляет URL и секреты локально, выполняет запрос и возвращает структурированный результат: статус, безопасную часть заголовков, тело и длительность. Секретный токен не обязан попадать в контекст модели вообще.
Сценарий 1: агент прогоняет smoke-тесты
Представьте запрос: «Проверь staging после деплоя и объясни ошибки». Агент действует по ограниченному плану:
- Читает список коллекций и находит папку
smoke. - Запрашивает доступные окружения и выбирает
staging. - Запускает только помеченные как безопасные проверки.
- Сопоставляет статусы и утверждения с ожидаемыми значениями.
- Возвращает отчёт с упавшими шагами и request ID для поиска в логах.
Коллекция остаётся исполняемой спецификацией, а агент берёт на себя выбор шагов и объяснение результата. Это особенно полезно для смешанного набора HTTP и gRPC-запросов: человеку не нужно вручную переключаться между папками и сводить ответы.
Простой результат инструмента лучше вернуть данными, а не длинным текстом:
{
"suite": "smoke",
"environment": "staging",
"passed": 8,
"failed": 1,
"failures": [
{
"requestId": "orders/create",
"status": 503,
"assertion": "expected 201"
}
]
}
Такая форма позволяет host показать таблицу, модели — сделать вывод, а CI — сохранить артефакт без разбора свободного текста.
Сценарий 2: запрос из обычного описания
Другой пример: «Создай запрос, который получает заказы клиента за последнюю неделю». Агент читает доступную OpenAPI-схему или gRPC-дескрипторы, находит подходящий метод и предлагает черновик. Затем API-клиент создаёт запрос в выбранной коллекции.
Здесь полезно разделить tools: draft_request только строит представление, save_request меняет коллекцию, run_request обращается к сети. Пользователь может проверить метод, URL, параметры и окружение между этапами. Для неоднозначного описания агент должен задать вопрос, а не угадывать, какой production-метод вызвать.
Схема улучшает точность: модель видит допустимые поля и enum, обязательные параметры и тип авторизации. Но она не заменяет бизнес-контекст. Если API принимает status=CLOSED, это ещё не означает, что закрытие заказа разрешено текущей роли.
Где проходит граница безопасности
MCP не делает инструмент безопасным автоматически. API-клиенту нужны собственные ограничения:
- разрешённый список коллекций, окружений и хостов;
- отдельное подтверждение для
POST,PATCH,PUTиDELETE; - запрет production по умолчанию или отдельный профиль доступа;
- подстановка секретов после решения модели, без передачи их в prompt;
- сокращение или маскирование чувствительных заголовков и полей ответа;
- лимиты времени, размера ответа и числа вызовов;
- журнал: кто, когда, каким tool и с какими несекретными аргументами воспользовался.
Удалённый MCP-сервер также требует HTTPS, аутентификации и проверки Origin. Локальный сервер разумно привязывать к loopback, а не ко всем сетевым интерфейсам. Скрипты коллекций заслуживают отдельного внимания: агент не должен незаметно запускать произвольный код с доступом ко всей файловой системе. В Tetiva они выполняются в песочнице Goja, что уменьшает область доступа, но разрешения коллекции всё равно нужно проверять.
MCP — интерфейс, а не автопилот
Польза MCP-сервера в API-клиенте не в «магии AI», а в чёткой границе. Агент получает каталог типизированных операций, клиент сохраняет контроль над сетью и секретами, а пользователь видит план и результат. Начните с чтения схем и запуска безопасной smoke-папки на тестовом окружении. Добавляйте создание и изменяющие запросы только тогда, когда подтверждения, лимиты и аудит уже работают.