Инструменты (tools)

Сервер может открыть инструменты, которые вызывает языковая модель: запросы к базам данных, вызовы API, вычисления. Каждый инструмент однозначно определяется именем и содержит метаданные со схемой.

Модель управления#

Инструменты рассчитаны на управление моделью: модель сама находит и вызывает их, исходя из контекста и запросов пользователя. Но протокол не навязывает интерфейс.

Возможности сервера#

Сервер, который поддерживает инструменты, ДОЛЖЕН объявить возможность tools:

{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

listChanged показывает, пришлёт ли сервер уведомление при изменении перечня инструментов.

Перечень, который сервер отдаёт в ответ на tools/list, МОЖЕТ быть пустым и МОЖЕТ меняться со временем, но НЕ ДОЛЖЕН зависеть от соединения или от побочных эффектов других запросов. Он МОЖЕТ различаться в зависимости от переданной авторизации: например, можно вернуть только те инструменты, которые разрешены выданными правами. Порядок инструментов СЛЕДУЕТ делать детерминированным: так клиенту проще кэшировать перечень, а у модели выше шанс попасть в кэш подсказки.

Сообщения#

Список инструментов#

Операция поддерживает постраничную выдачу и кэширование.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "tools": [
      {
        "name": "get_weather",
        "title": "Weather Information Provider",
        "description": "Get current weather information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "City name or zip code" }
          },
          "required": ["location"]
        }
      }
    ],
    "nextCursor": "next-page-cursor",
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

Вызов инструмента#

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "New York" }
  }
}

Ответ несёт content (массив элементов) и признак isError:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy" }
    ],
    "isError": false
  }
}

В примерах опущены поля _meta, но каждый запрос ДОЛЖЕН включать обязательные поля. Подробнее: «Протокол».

Недостаточно данных#

Сервер МОЖЕТ ответить на tools/call результатом input_required, если для вызова нужны дополнительные данные. Клиент собирает их и повторяет вызов с полем inputResponses и, если сервер его прислал, с requestState. Идентификатор JSON-RPC у повторного запроса ДОЛЖЕН отличаться от идентификатора первого. Механизм описан на странице «Шаблоны обмена».

Уведомление об изменении перечня#

Серверу, объявившему listChanged, СЛЕДУЕТ отправлять notifications/tools/list_changed клиентам, которые открыли поток subscriptions/listen с фильтром toolsListChanged: true.

Поля Tool#

Для инструмента без параметров рекомендуется схема { "type": "object", "additionalProperties": false }.

Имена#

• Длина имени СЛЕДУЕТ составлять от 1 до 128 символов.
• Регистр СЛЕДУЕТ учитывать.
• Допустимые символы СЛЕДУЕТ ограничить латинскими буквами, цифрами, подчёркиванием (_), дефисом (-) и точкой (.).
• Пробелы, запятые и другие спецсимволы НЕ СЛЕДУЕТ использовать.
• Имя СЛЕДУЕТ делать уникальным в пределах сервера.

Уникальность ограничена одним сервером. Клиенты и прокси, которые собирают инструменты с нескольких серверов, СЛЕДУЕТ реализовать способ различения, например приставку с идентификатором сервера. Название сервера из serverInfo для этого не годится: оно не гарантирует уникальности.

Заголовки из параметров (x-mcp-header)#

Сервер МОЖЕТ пометить параметр инструмента свойством x-mcp-header. Тогда клиент при работе по Streamable HTTP ДОЛЖЕН продублировать значение в заголовок Mcp-Param-{имя}. Это позволяет балансировщикам и прокси направлять запросы по значению параметра, не разбирая тело. Ограничения и кодирование значений описаны на странице «Транспорты». Чувствительные параметры (пароли, ключи, токены, персональные данные) помечать так НЕ СЛЕДУЕТ: заголовки видны посредникам.

Результаты#

Результат может быть неструктурированным (content) или структурированным (structuredContent).

Все типы содержимого поддерживают необязательные аннотации (аудитория, приоритет, время изменения).

Структурированный результат#

Инструменты с состоянием#

В MCP нет сессий на уровне протокола, поэтому сервер не может опираться на неявное состояние соединения. Если инструменту нужно хранить состояние между вызовами (корзина, открытый браузер, транзакция), сервер возвращает явный дескриптор из инструмента создания и принимает его аргументом в последующих вызовах. Для протокола дескриптор — обычная строка. Это нормативно не регулируется, а спецификация даёт рекомендации.

• Авторизация. Для серверов с аутентификацией дескриптор лишь имя, и права нужно проверять при каждом вызове. Без аутентификации дескриптор фактически токен предъявителя, его нужно генерировать с достаточной энтропией (например, UUIDv4) и ограничить срок жизни.
• Непрозрачность. Дескрипторы с внутренней структурой провоцируют разбор и угадывание.
• Срок жизни. Правила хранения СЛЕДУЕТ указать в описании инструмента создания, например «корзины удаляются через 24 часа простоя».
• Ошибка просроченного дескриптора. Вызов с просроченным или неизвестным дескриптором СЛЕДУЕТ завершать ошибкой выполнения инструмента, чтобы модель могла создать новый.

Ошибки#

Есть два вида ошибок.

1. Ошибки протокола касаются структуры запроса, и модель вряд ли исправит их сама: неизвестный инструмент, некорректный запрос, сбой сервера. Они возвращаются как стандартные ошибки JSON-RPC, например с кодом -32602.
2. Ошибки выполнения содержат подсказки, по которым модель может исправиться и повторить: сбой API, неверный формат даты, значение вне диапазона, нарушение бизнес-логики. Они передаются в результате с isError: true.

Клиенты МОГУТ передавать модели ошибки протокола, а ошибки выполнения СЛЕДУЕТ передавать, чтобы модель могла исправиться.

Безопасность#

Серверы ДОЛЖНЫ проверять все входные данные инструментов, реализовывать контроль доступа, ограничивать частоту вызовов и очищать выходные данные. Клиентам СЛЕДУЕТ запрашивать подтверждение для чувствительных операций, показывать пользователю входные данные до вызова (чтобы не допустить утечки), проверять результаты перед передачей модели, ограничивать время вызова и вести журнал использования.