mcpsnoop v0.22.0

Wireshark для MCP. mcpsnoop находится между вашим AI-клиентом и вашим MCP-сервером и записывает каждый JSON-RPC кадр, которым они обмениваются, без изменений с обеих сторон. Наблюдайте за ним в реальном времени в терминале, проваливайте CI на основе найденного или отправляйте его в ваш бэкенд трассировки в виде OpenTelemetry-спанов.

Проблема

Официальный MCP Inspector подключается как собственный клиент, поэтому он никогда не видит, что ваш клиент (Cursor, Claude Code, Codex) на самом деле отправляет вашему серверу. А всё, что ждёт поступления запроса, не может показать вызов, который модель так и не сделала или сделала с неправильными аргументами. Когда инструмент молча не вызывается, возможности не совпадают или вызов просто зависает, вам остаётся копаться в логах и гадать.

Вместо этого mcpsnoop находится в реальном пути данных. Оберните команду вашего сервера им и наблюдайте за каждым JSON-RPC кадром в реальном времени, пока ваш настоящий клиент и сервер общаются.

В CI

Эта страница также является листингом для mcpsnoop GitHub Action, поэтому вот он целиком. Он проверяет записанную сессию, регистрирует каждую находку как оповещение сканирования кода и проваливает задание на основе того, что вы задали в качестве условия.

permissions:
  security-events: write
  contents: read

steps:
  - uses: kerlenton/[email protected]
    with:
      session: artifacts/session.jsonl

Нет захвата под рукой? Запишите одну сессию своим клиентом один раз, закоммитьте её, и пусть действие воспроизводит её против каждой сборки. Ни модель, ни API-ключ не запускаются в CI. Воспроизведение проверяется так же, как любой захват, и задание также завершается с ошибкой, когда сервер стал хуже, чем в записи. Сервер, доступный через Streamable HTTP, получает target со своей конечной точкой, а запись воспроизводится через любой из транспортов.

steps:
  - uses: kerlenton/[email protected]
    with:
      replay: tests/mcp/claude-code-session.jsonl
      server: node dist/index.js

Закрепите любую нужную версию. Самая новая доступна на странице релизов. Все входные и выходные данные описаны в разделе The GitHub Action ниже, а все сигналы, по которым может завершиться сбоем проверка, — в docs/CI.md.

OpenTelemetry

Ревизия MCP 2026-07-28 объявляет устаревшим протокольный Logging и рекомендует реализациям переходить на stderr при stdio или на OpenTelemetry для структурированной наблюдаемости. mcpsnoop поддерживает оба варианта, не затрагивая клиент или сервер. Строки stderr stdio-сервера отображаются в потоке рядом с его кадрами, а каждый запрос становится спаном, следующим семантическим конвенциям OpenTelemetry для MCP.

mcpsnoop export -T otlp -o trace.json   # spans from a capture
mcpsnoop --otlp-endpoint http://localhost:4318/v1/traces -- node build/index.js   # spans as calls complete

Вызов инструмента приходит в виде спана с именем tools/call search, несущего mcp.method.name, gen_ai.tool.name и error.type, поэтому он попадает в дашборд, созданный для MCP, а не для mcpsnoop. Живые метрики инструментов для Prometheus — на расстоянии одного флага. Оба описаны в docs/OPENTELEMETRY.md.

Быстрый старт

Увидьте это сразу, без какой-либо настройки.

mcpsnoop demo

Чтобы использовать его по-настоящему, оберните ваш сервер в MCP-конфигурацию вашего клиента.

{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

Всё, что идёт после --, — это команда, которая обычно запускает ваш сервер. Подставьте ту, которую вы уже используете, например python server.py, npx -y @scope/server или скомпилированный бинарник.

В Claude Desktop вам не нужно вносить это изменение вручную.

mcpsnoop wrap my-server     # route my-server through mcpsnoop
mcpsnoop unwrap my-server   # put it back

wrap находит claude_desktop_config.json, при первом запуске копирует его в claude_desktop_config.json.mcpsnoop.bak и перезаписывает только запись этого одного сервера, поэтому ваше форматирование и все остальные серверы остаются нетронутыми. Внутри перезаписанной записи ключи возвращаются в алфавитном порядке. unwrap восстанавливает файл и удаляет резервную копию, как только ни один сервер больше не обёрнут. После любого из этих действий перезапустите Claude Desktop, так как MCP-серверы запускаются один раз при старте.

Затем используйте свой клиент как обычно и откройте UI.

mcpsnoop

Никаких флагов, никаких путей к сокетам, никакого порядка запуска, который нужно запоминать. Shim и UI находят друг друга сами, а UI подгружает прошлые сессии с диска.

Для сервера с потоковой передачей по HTTP запускайте mcpsnoop как обратный прокси.

mcpsnoop http --target http://localhost:3000/mcp --listen :7000

HTTP-статус каждого ответа отображается в потоке, поэтому ответ, не содержащий собственного сообщения JSON-RPC, всё равно остаётся видимым кадром, а не пустотой. Это охватывает запрос 401, 403 при отклонённом Origin, 202, подтверждающий уведомление, и 502, когда целевой сервер вообще недоступен. Заголовок WWW-Authenticate ответа 401 сохраняется дословно и показывается в инспекторе, поскольку он указывает схему аутентификации и метаданные ресурса, к которым следует обратиться далее. Фильтруйте по статусу с помощью status:401 в TUI или по любой ошибке с помощью status:err. Код 4xx или 5xx считается ошибкой, поэтому запуск mcpsnoop check по умолчанию завершается неудачей на нём, а вызов, на который он ответил, читается как неудавшийся, а не как всё ещё ожидающий.

Нет собственного сервера? Попробуйте по-настоящему на опубликованном тестовом сервере, управляемом вашим собственным клиентом. Чтобы просмотреть сессию после того, как она произошла, см. просмотр прошлых сессий из логов.

Установка

npm

Инструментарий Go не требуется. Большинство серверов MCP написаны на Node или Python, поэтому это самый короткий путь.

npx mcpsnoop -- node build/index.js

Пакет npm не содержит собственного кода. Шесть платформенных пакетов содержат по одной сборке, и npm устанавливает только тот, который соответствует вашей машине, поэтому во время установки ничего не нужно скачивать и ничего не нужно разблокировать в прокси. Чтобы сохранить его, а не загружать при каждом запуске, выполните npm i -g mcpsnoop.

Homebrew

brew install mcpsnoop

Go

go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest