Тестирование MCP-серверов: основы

Тестирование MCP-сервера - проверка того, что сервер соблюдает спецификацию Model Context Protocol, его инструменты, ресурсы и промпты работают правильно, подключаться к нему безопасно, а языковые модели используют его так, как задумано. В статье разобраны основы: чем такое тестирование отличается от привычного, из каких уровней состоит, что требует спецификация и какие есть официальные инструменты.

Требования в статье соответствуют версии спецификации 2026-07-28. Базовые понятия протокола (хост, клиент, сервер, примитивы, транспорты) описаны в статье Что такое MCP.

Кратко

Чем отличается от тестирования API

MCP-сервер часто служит обёрткой над обычным API, и привычные методы тестирования API к нему применимы. Специфичны для MCP три вещи.

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

Есть уровень протокола. Кроме бизнес-логики, сервер обязан соблюдать правила MCP: выбор версии, обязательные поля каждого запроса, объявление возможностей, типы ошибок, поведение транспорта. Клиент другого производителя опирается на эти правила, а не на код сервера.

Поведение с моделью недетерминировано. Один и тот же запрос пользователя в разных запусках и на разных моделях может привести к разным последовательностям вызовов инструментов. Один прогон сценария показывает, что он может работать, но не что он работает надёжно. Этот уровень проверяют статистически: на наборах задач и повторных прогонах.

Уровни тестирования

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

Соответствие протоколу

Проверки ниже следуют прямо из требований спецификации.

Обнаружение возможностей и версии

• Каждый сервер обязан реализовать server/discover. В ответе - поддерживаемые версии протокола (supportedVersions) и возможности сервера (capabilities).
• Запрос с версией, которую сервер не поддерживает, отклоняется ошибкой UnsupportedProtocolVersionError (код -32022); поддерживаемые версии перечислены в поле data ошибки.
• Каждый запрос несёт в _meta поля io.modelcontextprotocol/protocolVersion и io.modelcontextprotocol/clientCapabilities. Запрос без любого из них отклоняется с кодом -32602 (Invalid params).
• Если серверу нужна возможность клиента, которую запрос не объявил, например elicitation, сервер возвращает MissingRequiredClientCapabilityError (код -32021) с названиями недостающих возможностей.
• Сервер объявляет только те возможности, которые реализует: сервер, объявивший tools, обязан отвечать на tools/list.

Инструменты

• Список, который возвращает tools/list, не должен зависеть от соединения или от других запросов. Он может зависеть от авторизации запроса, например от прав (scopes) токена.
• Инструменты следует возвращать в детерминированном порядке: клиенты кешируют список, а порядок влияет на кеш промптов модели.
• inputSchema обязана быть корректным объектом JSON Schema, а не null. Диалект по умолчанию - JSON Schema 2020-12. Для инструмента без параметров спецификация рекомендует { "type": "object", "additionalProperties": false }.
• Если инструмент объявляет outputSchema, его структурированные результаты (structuredContent) обязаны соответствовать этой схеме.
• Имя инструмента - от 1 до 128 символов, только латинские буквы, цифры, _, - и .; в пределах сервера имена уникальны.

Ошибки

Спецификация разделяет два вида ошибок, и тест проверяет, что каждый случай попадает в нужный:

Разница важна для модели. Ошибку выполнения инструмента хост передаёт модели, и модель может исправить вызов. Ошибку протокола обычно обрабатывает приложение, и до модели она не доходит. До SEP-1303 реализации возвращали неверные аргументы по-разному; текущая спецификация возвращает все ошибки проверки входных данных как ошибки выполнения инструмента.

Многоэтапные запросы (MRTR)

Для сервера, который запрашивает у клиента дополнительные данные (resultType: "input_required"):

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

Транспорты

• stdio: в стандартный поток вывода попадают только сообщения MCP. Любой другой вывод, например журнал или отладочная печать, ломает протокол. Журнал пишется в стандартный поток ошибок.
• Streamable HTTP: сервер работает за балансировщиком нагрузки без привязки клиента к экземпляру, потому что с версии 2026-07-28 сессии протокола нет. Состояние, которое нужно между вызовами, передаётся в явных идентификаторах, и их отдельно проверяют на безопасность.

Официальные инструменты

MCP Inspector

MCP Inspector - эталонный инструмент разработчика для тестирования и отладки MCP-серверов. Распространяется npm-пакетом @modelcontextprotocol/inspector, требует Node.js 22.19.0 или новее и содержит три клиента:

Сервер передаётся командой, которая его запускает (stdio), или адресом (Streamable HTTP):

# Локальный сервер по stdio
npx @modelcontextprotocol/inspector node build/index.js

# Удалённый сервер по Streamable HTTP
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

CLI выполняет один запрос (--method) и завершается с кодом, по которому видно тип сбоя, поэтому скрипт или задача CI может на него опираться:

Минимальная дымовая проверка в CI: сервер запускается, отдаёт нужный инструмент, его схемы проходят строгую проверку, а вызов выполняется успешно.

set -euo pipefail

# The server starts and exposes the get_weather tool
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("get_weather")' > /dev/null

# Tool schemas have no error-level problems (exit code 6 otherwise)
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/list --strict > /dev/null

# The call succeeds (exit code 5 if the result has isError: true)
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name get_weather --tool-arg city=Boston > /dev/null

Для серверов с авторизацией у CLI есть флаг --stored-auth-only: он использует сохранённый токен и сразу завершается с auth_required, а не открывает браузер, которым задача CI воспользоваться не может.

Набор тестов соответствия

Набор тестов соответствия (conformance, репозиторий modelcontextprotocol/conformance) проверяет реализации клиентов и серверов на соответствие спецификации. Для сервера он выступает клиентом: отправляет тестовые запросы, записывает ответы и проверяет их, в том числе сверяет каждое сообщение JSON-RPC с JSON-схемой спецификации.

# List the server scenarios
npx @modelcontextprotocol/conformance list --server

# Run all server scenarios against a server over HTTP
npx @modelcontextprotocol/conformance server --url http://localhost:3000/mcp

Результаты каждого сценария сохраняются в results/server-<scenario>-<timestamp>/checks.json со статусом каждой проверки. Известные сбои можно записать в YAML-файл и передать флагом --expected-failures, тогда CI падает только на новых.

Набор служит ориентиром для официальных SDK: SDK уровня Tier 1 обязан проходить все тесты соответствия, SDK уровня Tier 2 - не меньше 80 процентов. С SEP-2484 изменение протокола с наблюдаемым поведением получает финальный статус только вместе со сценарием соответствия, который покрывает его требования. Сравнение контрактов между версиями сервера описано в статье Регрессионное тестирование MCP-сервера.

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

Спецификация и документ Security Best Practices описывают атаки, которые касаются MCP-серверов. Для каждой есть проверяемое требование:

Атаки, на которых основаны эти требования, описаны в статье Безопасность MCP, схема авторизации - в статье Авторизация в MCP, а prompt injection и способы его тестирования - в статье Prompt injection.

Оценка на моделях

Соответствие протоколу показывает, что клиент может работать с сервером. Может ли модель с ним выполнять задачи, показывает только запуск модели. Этот подход Anthropic описывает в руководстве по созданию инструментов для агентов.

1. Задачи. Набор реалистичных задач на реальных данных, у каждой проверяемый результат: точный ответ или проверка другой моделью. Хорошие задачи требуют нескольких вызовов инструментов.
2. Прогоны. Каждая задача выполняется в цикле: модель получает задачу и инструменты, вызывает их и получает результаты, пока не даст ответ.
3. Метрики. Точность ответов, время задач и вызовов инструментов, число вызовов инструментов, расход токенов и ошибки инструментов.
4. Анализ. Причины видны в стенограммах. Много повторных вызовов указывает на отсутствие постраничной выдачи или фильтров. Частые неверные аргументы указывают на неясные описания или названия параметров.
5. Итерации. После изменения инструментов или описаний тот же набор запускается снова. Часть задач держат отдельно, чтобы убедиться, что улучшение не ограничено задачами, на которых его настраивали.

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

Отладка

• Первый шаг - подключиться к серверу через MCP Inspector и вызвать инструменты напрямую, без модели и хоста.
• Сервер на stdio пишет журнал только в стандартный поток ошибок; хост этот поток перехватывает. Для HTTP-серверов журналы собирают на стороне сервера, например через OpenTelemetry.
• Хост может запускать stdio-сервер с неопределённым рабочим каталогом и ограниченным набором переменных окружения. Пути в конфигурации указывают абсолютные, а нужные серверу переменные задают явно в конфигурации хоста.
• Если подключение не работает, проверяют версию протокола и поля _meta: server/discover показывает, какие версии поддерживает сервер.

Термины

Источники

• Спецификация Model Context Protocol, версия 2026-07-28(откроется в новой вкладке) (на английском)
• Tools, спецификация 2026-07-28(откроется в новой вкладке) (на английском)
• Multi Round-Trip Requests, спецификация 2026-07-28(откроется в новой вкладке) (на английском)
• MCP Inspector(откроется в новой вкладке) (на английском)
• MCP Inspector, клиент CLI(откроется в новой вкладке) (на английском)
• Debugging(откроется в новой вкладке) (на английском)
• Security Best Practices(откроется в новой вкладке) (на английском)
• SEP-1303: Input Validation Errors as Tool Execution Errors(откроется в новой вкладке) (на английском)
• SEP-2484: Require Conformance Tests for Standards Track SEPs to Reach Final Status(откроется в новой вкладке) (на английском)
• Набор тестов соответствия MCP, GitHub(откроется в новой вкладке) (на английском)
• Writing effective tools for agents, Anthropic, 11 сентября 2025(откроется в новой вкладке) (на английском)