2026-07-11 · обновлено 2026-08-14

Зачем API-клиенту MCP-сервер

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

Доступ модели к сети при этом ограничен: хорошая интеграция оставляет выполнение в API-клиенте, где уже есть окружения, секреты, история и правила, а агенту выдаёт только явно разрешённые действия.

Что такое Model Context Protocol

Model Context Protocol, или MCP, — открытый протокол обмена между AI-приложением и внешним источником данных или действий. В его архитектуре есть три роли:

Хост — приложение, в котором работает пользователь и модель: IDE, десктопный ассистент или агентная среда.
MCP-клиент — соединение внутри хоста с конкретным MCP-сервером.
MCP-сервер — программа, которая объявляет доступные возможности и выполняет запросы.

Сообщения MCP основаны на JSON-RPC 2.0. Для локального процесса обычно используют stdio, для удалённого сервера — Streamable HTTP. Во время инициализации стороны согласуют версию протокола и возможности, после чего клиент может запросить каталог инструментов.

MCP-сервер публикует три основных вида возможностей. Инструменты (tools) выполняют действия, например запускают сохранённый запрос. Ресурсы (resources) отдают контекст для чтения: список коллекций, схему OpenAPI или пример ответа. Промпты (prompts) задают повторяемые сценарии работы. API-клиенту необязательно реализовывать всё сразу; для начала достаточно небольшого набора инструментов и ресурсов.

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

Скрипты и тесты запроса в Tetiva — то, что агент запускает через MCP — Сохранённые запросы и коллекции доступны агенту через MCP

Как агент находит и вызывает запрос

После подключения хост получает описание инструментов и их 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"]
  }
}

Узнав идентификатор запроса из ресурса или отдельного поиска, агент вызывает инструмент:

{
  "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"
    }
  ]
}

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

Сценарий 2: запрос из текстового описания

Другой пример: «Создай запрос, который получает заказы клиента за последнюю неделю». Агент читает доступную OpenAPI-схему или gRPC-дескрипторы, находит подходящий метод и предлагает черновик. Затем API-клиент создаёт запрос в выбранной коллекции.

Здесь полезно разделить инструменты: draft_request только строит представление, save_request меняет коллекцию, run_request обращается к сети. Пользователь может проверить метод, URL, параметры и окружение между этапами. Для неоднозначного описания агент должен задать вопрос, а не угадывать, какой метод вызвать в production.

Схема улучшает точность: модель видит допустимые поля и значения enum, обязательные параметры и тип авторизации. Но она не заменяет бизнес-контекст. Если API принимает status=CLOSED, это ещё не означает, что закрытие заказа разрешено текущей роли.

Где проходит граница безопасности

MCP не делает инструмент безопасным автоматически. API-клиенту нужны собственные ограничения:

разрешённый список коллекций, окружений и хостов;
отдельное подтверждение для POST, PATCH, PUT и DELETE;
запрет production по умолчанию или отдельный профиль доступа;
подстановка секретов после решения модели, без передачи их в контекст модели;
сокращение или маскирование чувствительных заголовков и полей ответа;
лимиты времени, размера ответа и числа вызовов;
журнал: кто, когда, каким инструментом и с какими несекретными аргументами воспользовался.

Удалённый MCP-сервер также требует HTTPS, аутентификации и проверки Origin. Локальный сервер по HTTP разумно привязывать только к loopback; при транспорте stdio сетевой порт вообще не нужен. Со скриптами коллекций сложнее: агент не должен незаметно запускать произвольный код с доступом ко всей файловой системе. В Tetiva они выполняются в песочнице Goja, что уменьшает область доступа, но разрешения коллекции всё равно нужно проверять.

Так зачем API-клиенту MCP-сервер

Польза MCP-сервера в API-клиенте — чётко проведённая граница. Агент работает с каталогом типизированных операций, а контроль над сетью и секретами остаётся у клиента. Пользователь видит план и результат. Начинать проще с чтения схем и безопасного набора smoke-тестов на тестовом окружении; создание и изменяющие запросы стоит открывать, когда подтверждения, лимиты и аудит уже работают.