Ошибки — MCP Docs

Ответ с ошибкой — стандартное сообщение JSON-RPC 2.0. В версии 2026-07-28 спецификация ввела политику распределения кодов, чтобы реализации не конфликтовали с кодами протокола.

Как сервер отвечает на неизвестную версию, расхождение заголовков и неизвестный метод, проверяет бесплатная проверка MCP-сервера.

Структура#

typescript

{
  jsonrpc: "2.0";
  id?: string | number;
  error: { code: number; message: string; data?: unknown; }
}

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

Распределение кодов#

Для общих сбоев протокола MCP использует стандартные коды JSON-RPC 2.0: -32700 и от -32600 до -32603. Диапазон от -32000 до -32099 JSON-RPC резервирует для реализационных ошибок сервера, и MCP делит его так.

Диапазон Статус

от -32000 до -32019 Прежние. Коды, которые реализации выбрали до введения политики. Новые коды в этом поддиапазоне выделять НЕЛЬЗЯ, а новым реализациям их СЛЕДУЕТ не использовать вовсе. Кроме -32002 (см. ниже), получатель НЕ ДОЛЖЕН предполагать у этих кодов конкретный смысл.

от -32020 до -32099 Зарезервированы для спецификации MCP. Определяются только ею и записываются в схеме. Реализации НЕ ДОЛЖНЫ выдавать коды из этого диапазона, не определённые спецификацией, и ДОЛЖНЫ использовать определённые только с заданным смыслом.

Диапазон	Статус
от `-32000` до `-32019`	Прежние. Коды, которые реализации выбрали до введения политики. Новые коды в этом поддиапазоне выделять НЕЛЬЗЯ, а новым реализациям их СЛЕДУЕТ не использовать вовсе. Кроме `-32002` (см. ниже), получатель НЕ ДОЛЖЕН предполагать у этих кодов конкретный смысл.
от `-32020` до `-32099`	Зарезервированы для спецификации MCP. Определяются только ею и записываются в схеме. Реализации НЕ ДОЛЖНЫ выдавать коды из этого диапазона, не определённые спецификацией, и ДОЛЖНЫ использовать определённые только с заданным смыслом.

Новые коды для других целей СЛЕДУЕТ выделять вне диапазона, зарезервированного JSON-RPC (от -32768 до -32000): остальная часть целых чисел доступна для прикладных ошибок.

Коды MCP#

Код	Название	Когда возникает
`-32020`	`HeaderMismatch`	Заголовки HTTP не совпадают со значениями в теле запроса или обязательные заголовки отсутствуют либо искажены. HTTP-статус `400`.
`-32021`	`MissingRequiredClientCapability`	Для запроса нужна возможность, которую клиент не объявил. В `data.requiredCapabilities` перечень недостающих. HTTP-статус `400`.
`-32022`	`UnsupportedProtocolVersion`	Сервер не поддерживает версию из запроса. В `data` поля `supported` и `requested`. HTTP-статус `400`.

Пример UnsupportedProtocolVersionError:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32022,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2026-07-28", "2025-11-25"],
      "requested": "1900-01-01"
    }
  }
}

Клиенту СЛЕДУЕТ выбрать из supported общую версию и повторить запрос или показать пользователю ошибку, если совместимой версии нет.

Другие ошибки по умолчанию#

Ситуация	Код и статус HTTP
В запросе нет обязательного поля `_meta` (версии протокола или возможностей клиента)	`-32602` (неверные параметры), HTTP `400`
Сервер не реализует запрошенный метод	`-32601` (метод не найден), HTTP `404`
Неизвестный инструмент, некорректный запрос	`-32602`
Ресурс не найден	`-32602` (до 2026-07-28 `-32002`)

Устаревшие коды#

Коды, определённые прежними версиями, остаются зарезервированными и не будут использованы заново. Реализации ревизии 2026-07-28 НЕ ДОЛЖНЫ выдавать эти коды:

-32002 — ресурс не найден (2025-11-25 и ранее; заменён на -32602). Клиентам СЛЕДУЕТ по-прежнему принимать -32002 от серверов прежних версий.
-32042 — требуется элицитация по URL (только 2025-11-25).

Коды, введённые в черновике этой ревизии, перенумерованы: HeaderMismatch из -32001 в -32020, MissingRequiredClientCapability из -32003 в -32021, UnsupportedProtocolVersion из -32004 в -32022. Ошибка HeaderMismatchError добавлена в схему, раньше она существовала только в тексте о транспорте.

Ошибки, которые чисто локальны для реализации (например, таймаут внутри SDK), спецификация пока не кодирует. Реализации, которые показывают такие ошибки в виде структур JSON-RPC, должны сделать так, чтобы их нельзя было принять за ошибки от собеседника.

Ошибки инструментов#

Вызов инструмента различает ошибки протокола (неизвестный инструмент, некорректный запрос, сбой сервера, возвращаются как ошибки JSON-RPC) и ошибки выполнения (сбои API, неверные данные, бизнес-логика, возвращаются в результате с isError: true). Подробнее: «Инструменты».