Debugging with MCP Inspector

MCP Inspector — официальный отладчик протокола: временный MCP-клиент с веб-интерфейсом, который подключается к вашему серверу вместо Claude или Cursor. Устанавливать не нужно:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Inspector поднимает две части: прокси, который запускает ваш сервер как дочерний процесс и говорит с ним по stdio, и браузерный UI (по умолчанию на localhost:6274). Для HTTP-серверов вместо команды указывается URL endpoint.

Рабочий цикл в UI:

• Connect — выполняется рукопожатие; сразу видно согласованную версию протокола и capabilities сервера. Если подключение висит — сервер упал на старте, смотрите панель stderr.
• Tools — список из tools/list с полными JSON Schema. Проверьте глазами: описания понятны? enum-значения на месте? Модель будет видеть ровно это.
• Выбор инструмента открывает форму аргументов, сгенерированную по схеме. Вызовите с валидными аргументами, потом с невалидными — убедитесь, что первое возвращает ожидаемый content, а второе аккуратно отбивается ошибкой валидации.
• Resources и Prompts — чтение ресурсов по URI, раскрытие шаблонов, предпросмотр сообщений промпта.
• Панель уведомлений показывает notifications от сервера, а история запросов — сырые кадры JSON-RPC в обе стороны. Чтение этих кадров — лучший способ довести понимание протокола из прошлых уроков до автоматизма.

Правило профессионала: ни один сервер не подключается к реальному клиенту, пока не прошёл полный круг в Inspector. Отладка внутри Claude Desktop медленнее на порядок: перезапуски, поиск логов, отсутствие сырых кадров.

У Inspector есть режим без браузера — для скриптов и CI:

# Список инструментов
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# Вызов инструмента с аргументами
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name search_orders \
  --tool-arg status=paid --tool-arg limit=5

# Чтение ресурса
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method resources/read --uri orders://o_1

Каждая команда выполняет полный цикл: запуск сервера, initialize, вызов метода, вывод результата в stdout — уже вашего терминала, в виде JSON. Это идеальный материал для smoke-скрипта:

#!/usr/bin/env bash
set -euo pipefail
npm run build
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/list | grep -q 'search_orders' || {
  echo 'FAIL: search_orders not listed'; exit 1;
}
echo 'smoke: OK'

Такой скрипт занимает секунды и ловит целый класс регрессий: сервер не собирается, падает на старте, инструмент выпал из списка, схема сломалась. Добавьте его в pre-commit или CI-пайплайн рядом с юнит-тестами — и «зелёный Inspector» станет частью definition of done, а не ручным ритуалом.

Для сложных конфигураций (env-переменные, несколько серверов) Inspector принимает файл конфигурации через --config с тем же форматом, что у клиентов, — удобно гонять именно ту конфигурацию, которую вы отдадите пользователям.

Каталог граблей, собранный сообществом за два года. Проверяйте по порядку.

Unexpected token / JSON parse error при подключении. Классика: что-то пишет в stdout. Ваш console.log, баннер библиотеки при импорте, npm-скрипт, печатающий команду. Диагностика: node dist/index.js < /dev/null — до кадров протокола stdout обязан быть пуст. Лечение: все логи в stderr, болтливые зависимости — изолировать.

Инструмент не виден в списке. Регистрация после server.connect(), упавший при старте код до регистрации, либо клиент закэшировал старый список — переподключитесь.

Валидация отбивает корректные на вид аргументы. Помните: все значения из формы Inspector и из --tool-arg приходят строками; если схема ждёт z.number(), используйте z.coerce.number() либо проверяйте типы аргументов на стороне вызова. Это же спасает от расхождений между клиентами.

Долгие инструменты обрываются по таймауту. У клиентов есть лимит на вызов (обычно около минуты). Для долгих операций шлите progress notifications или дробите операцию на шаги.

«В Inspector работает, в Claude Desktop — нет». Почти всегда — различие окружений. Клиент запускает сервер не из вашего шелла: другой PATH (npx может не найтись — пишите абсолютный путь к node), нет ваших переменных окружения (передавайте через env-блок конфига), другой рабочий каталог (никаких относительных путей к файлам). Смотрите логи клиента: у Claude Desktop это файлы mcp*.log в каталоге логов приложения.

Структурируйте собственные stderr-логи — префикс сервера, метод, длительность: при инциденте у пользователя вы попросите именно этот лог.