GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
Все руководства

· reAPI Team

Вызовы инструментов MCP: почему они перестают работать после смены API

Проследи путь вызовов инструментов MCP от обнаружения и поддержки моделью до выполнения и возврата результатов. Выясни причину сбоя при переходе на другой API до повторной попытки или отправки платных задач.

Вызовы инструментов MCP: почему они перестают работать после смены API

Сервер MCP показывает статус «Подключено». Но ассистент по-прежнему отвечает обычным текстом или говорит, что проверил задачу, не показывая результат. Если это началось после смены API модели, сначала выясни, что прошло через новое подключение, и только потом снова меняй промпт.

Подключённый сервер инструментов и модель, способная запрашивать инструменты, — разные части приложения. MCP задаёт обнаружение и вызов инструментов. Затем хост должен предоставить модели нужные инструменты, выполнить любой запрошенный ею разрешённый вызов и вернуть результат.[1][2] Успех на первом шаге не доказывает, что сработал последний.

Найди инструмент в списке, полученном клиентом

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

Если инструмента нет, проверь выбранный сервер, поддерживаемый транспорт и аутентификацию в процессе, где работает клиент. Текущая спецификация MCP допускает, что доступные инструменты зависят от предоставленных полномочий.[1] Поэтому видимость одного инструмента не доказывает, что тот же вызывающий код видит все инструменты сервера.

Для подключения к reAPI в документации указан удалённый Streamable HTTP с пользовательским заголовком авторизации Bearer. Клиент, который поддерживает только вход через OAuth без пользовательских заголовков, не сможет подключиться с такой конфигурацией.[3] Повтор инструкции для модели не добавит транспорт или механизм учётных данных, которых нет у клиента.

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

Сравни обнаруженную схему с тем, что видит модель

Рассмотрим вымышленный инструмент только для чтения. Он ищет существующую задачу по ID. Этот фрагмент иллюстрирует запись обнаружения; это не полный ответ протокола и не инструмент, который мы развернули:

{
  "name": "inspect_task_example",
  "description": "Look up the status of an existing task.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task_id": { "type": "string" }
    },
    "required": ["task_id"]
  }
}

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

Это конкретное место, где можно исправить адаптер. Более длинный промпт с просьбой «правильно использовать инструмент» не восстановит отсутствующую схему. Сравни два объекта, прежде чем добавлять инструкции или снова менять провайдера.

В этом примере сравни task_id в трёх местах: в обнаруженном свойстве, в свойстве для модели и в аргументах, которые хост затем передаёт инструменту. Везде должно подразумеваться одно и то же обязательное строковое значение. Если преобразователь в одном месте переименовал его в id, а в другом оставил task_id, возникло несоответствие. Используй поддерживаемую API модели оболочку определения, сохранив имя, тип и обязательность этого поля.

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

Модель запросила инструмент или только сказала, что воспользуется им?

Изучи структуру ответа модели. Обычная фраза «Я проверю задачу» — это не структурированный вызов инструмента. Отказ, обычный ответ, некорректный вызов и корректный вызов требуют разных следующих шагов, даже если все они пришли в успешных HTTP-ответах.

Если запрос содержал правильную схему, но вызов не вернулся, проверь поддержку модели, настройки выбора инструментов и использованный маршрут. Автоматический выбор инструмента может привести к обычному ответу; настройка, отключающая инструменты, может помешать их выбору. Поддержка более строгих значений выбора инструментов тоже зависит от модели.[2] Не считай каждое отсутствие вызова некорректными аргументами.

Маршрутизация важна, когда посредник выбирает провайдера. В документации OpenRouter описан параметр require_parameters, ограничивающий маршруты провайдерами, которые поддерживают все запрошенные параметры. Настройки предпочтений по умолчанию, включая предпочтения для инструментов, — не то же самое, что строгая фильтрация.[4] Проверь резервные модели и маршрут, который обработал запрос. Не переноси эту специфичную для провайдера опцию в другой API, считая, что она будет работать так же.

Если структурированный вызов пришёл, перестань отлаживать выбор и проследи за этим вызовом. Модель запросила действие, но приложение всё ещё должно его выполнить. В руководстве OpenRouter по вызову инструментов прямо сказано, что за выполнение отвечает вызывающая сторона, а не модель.[2]

Проследи за одним и тем же ID вызова во время выполнения и возврата

Вот продолжение вымышленного примера в формате сообщений Chat Completions. ID и результат придуманы. Это фрагменты сообщений для проверки, а не скрипт отправки запроса:

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_example_1",
        "type": "function",
        "function": {
          "name": "inspect_task_example",
          "arguments": "{\"task_id\":\"example_task_7\"}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_example_1",
    "content": "{\"task_id\":\"example_task_7\",\"status\":\"processing\"}"
  }
]

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

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

Сверь имя и аргументы переданного инструмента с запрошенным вызовом. В этом примере поиск должен получить example_task_7; если хост по ошибке использовал предыдущий ID задачи, он выполнил другой поиск, даже если сервер вернул корректный результат. Сохрани соответствие между ID вызова модели, запуском инструмента и возвращённым содержимым. Так неправильный результат задачи станет заметен до того, как модель включит его в уверенный ответ. Исправь это локальное соответствие, не меняя схему исходного инструмента и не расширяя его доступ.

При потоковой передаче вызовов дождись полного набора аргументов. В OpenRouter описан сбор дельт по индексу вызова и разбор после того, как строка аргументов сформирована полностью.[2] Ранний фрагмент, оборвавшийся посреди task_id, ещё не является корректным JSON. Отличай его от полной строки аргументов, которая всё равно остаётся некорректной.

Во втором сообщении выше указан тот же ID вызова, что и в первом. В документированном цикле Chat Completions после хода ассистента с вызовом инструмента следует сообщение с результатом для каждого запрошенного вызова.[2] Если вернулось несколько вызовов, сохрани идентификатор и результат каждого. Отправка одного результата под каждым ID может создать видимость завершённого диалога, хотя к запрошенным действиям будут прикреплены не те данные.

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

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

Не скрывай ошибки инструментов

MCP различает проблемы протокола и ошибки выполнения инструмента. Неизвестный инструмент или некорректный запрос протокола может привести к ошибке JSON-RPC. Ошибка выполнения инструмента, в свою очередь, может вернуться с isError: true.[1] Сохрани это различие и связанное сообщение при преобразовании результата для модели.

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

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

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

Заверши проверку подключения до отправки генерации

В reAPI начни с относящихся к проблеме инструментов, которые не отправляют задачу. В справочнике MCP указано, что поиск моделей, получение схемы, оценка стоимости, проверка статуса задачи и баланса не списывают кредиты. submit_task — отдельный случай: вызов, создающий задачу, тарифицируется как эта задача.[3]

Документированный сервер не хранит состояние и принимает одно сообщение JSON-RPC на HTTP-запрос, а не массивы пакетных сообщений. Для медиа нужны общедоступные URL по HTTP или HTTPS, а не base64 или data URI.[3] Если сбой возник на этапе выполнения, проверь эти реальные требования интерфейса; не отправляй генерации снова и снова для проверки соединения.

Сохрани возвращённый ID задачи и запрашивай именно эту существующую задачу. В документации reAPI отправка задачи названа неидемпотентной: повторный запрос на создание может создать ещё одну платную задачу.[3] Если ответ на отправку потерян, выполни проверку приёма, а не считай, что запрос не сработал.

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

Источники

  1. Model Context Protocol, Tools specification, revision 2026-07-28. Дата обращения: 16 ноября 2026 года. Версии протокола и реализации серверов могут различаться.
  2. OpenRouter, «Tool Calling Across Any Model: Write the Loop Once, Swap the Model String», официальное руководство, обновлено 24 сентября 2026 года. Дата обращения: 16 ноября 2026 года.
  3. reAPI, MCP Server documentation. Проверено 16 ноября 2026 года. Для этого руководства не проводились тесты живой генерации или совместимости клиента.
  4. OpenRouter, «Provider Routing», официальная документация, разделы «Requiring Providers to Support All Parameters» и «Default parameter preferences». Дата обращения: 16 ноября 2026 года.
Все руководства