Tools: инструменты

описана редакция 2026-07-28, сверено со спецификацией 4 октября 2026

Источник - страница Tools спецификации. В примерах ниже для краткости опущено поле _meta; в настоящем запросе оно обязательно.

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

Сервер с инструментами обязан объявить возможность tools.

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

listChanged означает, что сервер будет сообщать об изменении списка.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

{
  "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"]
        }
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

Правила для списка:

• список может быть пустым и может меняться со временем;
• список не должен зависеть от соединения и от других запросов по нему;
• список может зависеть от прав, с которыми пришёл запрос: например, сервер покажет только то, что разрешено выданными областями доступа;
• серверу следует возвращать инструменты в одном и том же порядке, пока набор не изменился: так клиент может кэшировать список;
• запрос поддерживает постраничную выдачу и кэширование: поля ttlMs и cacheScope в результате обязательны.

Если в схеме нет поля $schema, она читается как JSON Schema 2020-12. Для инструмента без параметров спецификация рекомендует схему, которая принимает только пустой объект.

{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": { "type": "object", "additionalProperties": false }
}

Имена. Имени следует быть длиной от 1 до 128 знаков и состоять из латинских букв, цифр, подчёркивания, дефиса и точки. Регистр букв следует считать значимым. Уникальность действует в пределах одного сервера: если клиент собирает инструменты с нескольких серверов, ему следует самому разводить совпадающие имена, например приставкой.

Аннотации. Клиент обязан считать аннотации ненадёжными, если они получены не от доверенного сервера. Подробнее - на странице «Отравление инструментов».

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

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

Сервер может ответить не готовым результатом, а просьбой о дополнительных данных (resultType: "input_required"). Тогда клиент собирает данные и повторяет вызов - см. «Многошаговые запросы».

Поле content - список блоков. Допустимые типы блоков:

Поле structuredContent несёт структурированный результат - любое значение JSON. Если у инструмента есть outputSchema, сервер обязан возвращать результат, который ей соответствует, а клиенту следует его проверять. Для совместимости серверу следует дублировать структурированный результат текстом в блоке text.

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "Invalid departure date: must be in the future. Current date is 08/08/2025." }
    ],
    "isError": true
  }
}

Сессий в протоколе нет, поэтому сервер не может связать два вызова «по соединению». Рекомендация спецификации (она не является требованием): инструмент, создающий состояние, возвращает явный идентификатор, и следующие вызовы принимают его как обычный аргумент.

// вызов
{ "name": "create_basket", "arguments": {} }

// результат
{
  "content": [{ "type": "text", "text": "Created basket bsk_a1b2c3" }],
  "structuredContent": { "basket_id": "bsk_a1b2c3" }
}

// следующий вызов
{ "name": "add_item", "arguments": { "basket_id": "bsk_a1b2c3", "sku": "..." } }

Советы спецификации к таким идентификаторам:

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

Серверу, объявившему listChanged, следует присылать уведомление notifications/tools/list_changed тем клиентам, которые открыли поток subscriptions/listen и попросили об этом.

Раздел Security Considerations спецификации.

Сервер обязан:

• проверять все входные данные инструмента;
• разграничивать доступ;
• ограничивать частоту вызовов;
• очищать результат перед выдачей.

Клиенту следует:

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

Параметры, помеченные x-mcp-header, попадают в заголовки HTTP и видны промежуточным узлам. Секреты и персональные данные так помечать не следует. Как работает эта пометка, описано на странице «Транспорты».