Модуль 4 · Практика: пишем сервер · урок 8 из 14

Инспектор сервера

Проверять сервер скриптом check.py удобно, но неудобно смотреть, что именно летает по проводу, и неудобно показывать коллеге. Для этого есть MCP Inspector — официальный графический инструмент, который подключается к любому серверу и даёт потыкать его руками. В этом уроке разберём, как его запустить и на что смотреть.

Запуск

Инспектор — пакет для Node.js, устанавливать его не нужно: npx скачает и запустит нужную версию. Понадобится Node 22.19 или новее. Из папки проекта:

bash

npx @modelcontextprotocol/inspector uv run docs_server.py

Всё после имени пакета — команда запуска нашего сервера. Инспектор запустит его как дочерний процесс по stdio, точно так же, как это сделал бы Claude Code. С pip вместо uv команда будет npx @modelcontextprotocol/inspector python docs_server.py в активированном окружении.

Есть второй способ, через утилиту из SDK:

bash

uv run mcp dev docs_server.py

mcp dev делает то же самое: поднимает инспектор и подключает к нему сервер из файла. Разница в удобстве: не нужно помнить имя пакета.

В терминале появится ссылка вида http://localhost:6274/?MCP_INSPECTOR_API_TOKEN=.... Открывайте именно её, с токеном. Инспектор состоит из веб-страницы и небольшого локального сервера, который умеет запускать процессы на вашей машине, поэтому доступ к нему защищён одноразовым токеном. Набирать адрес по памяти без токена бесполезно.

Что на экране

Слева или сверху — панель подключения: транспорт (для нас stdio), команда и аргументы, переменные окружения. Если вы запустили инспектор с командой, всё уже заполнено, остаётся нажать «Connect». После подключения появляются вкладки. Какие именно — зависит от возможностей, которые объявил сервер: если сервер не отдаёт промпты, вкладки «Prompts» не будет.

Tools. Список инструментов. Выберите read_doc — справа появится описание, схема аргументов, развёрнутая в форму, и аннотации. Введите brief.md, нажмите вызов — ниже отобразится результат. Теперь введите brif.md и посмотрите, как выглядит ответ с is_error. Это самый быстрый способ проверить, что модель увидит то, что вы задумали: описания, подписи параметров, текст ошибок.

Resources. Список прямых ресурсов и шаблонов с MIME-типами. Пока пусто — ресурсы мы добавим через два урока и вернёмся сюда.

Prompts. Список промптов с аргументами. Заполняете аргументы — инспектор показывает сгенерированные сообщения. Тоже пока пусто.

Protocol. Полный журнал JSON-RPC: каждый запрос в паре с ответом, уведомления между ними. Здесь видно то, о чём мы говорили в уроке про архитектуру: tools/list, tools/call с аргументами, content в ответе. Когда что-то не работает, эта вкладка отвечает на вопрос «дошёл ли запрос и что вернулось».

Console. Стандартный поток ошибок процесса сервера. Именно сюда попадает то, что вы пишете через logging. Вызовите edit_doc и увидите нашу строку edit_doc: estimate.md. Если сервер падает при старте, traceback тоже будет здесь.

Вкладки Protocol и Console можно закрепить в боковой панели, чтобы они оставались на экране, пока вы работаете во вкладке Tools.

Типичный цикл работы

Запустили инспектор, подключились, проверили во вкладке Tools, что все инструменты на месте и описания читаются.
Вызвали каждый инструмент с правильными и заведомо неправильными аргументами. Смотрим, что ошибки понятны и не роняют сервер.
Открыли Protocol и убедились, что схема аргументов такая, как ожидалось: обязательные поля помечены, описания на месте.
Поправили код — перезапустили инспектор (или переподключились), повторили.

Три вещи, которые инспектор ловит лучше всего: случайный print() в stdout (сервер не подключится, а в Console будет видно, почему), опечатки в описаниях и параметры без описаний, и исключения, которые вылетают наружу вместо ToolError.

Режим командной строки

У инспектора есть режим --cli, который не открывает браузер, а выводит результат в терминал. Он пригодится для проверки в CI и для быстрых вопросов «какие инструменты у этого сервера»:

bash

npx @modelcontextprotocol/inspector --cli uv run docs_server.py --method tools/list

Вызов инструмента с аргументами:

bash

npx @modelcontextprotocol/inspector --cli uv run docs_server.py \
  --method tools/call --tool-name read_doc --tool-arg name=brief.md

Флаг --cli должен стоять первым, сразу после имени пакета: всё, что идёт после команды сервера, инспектор считает аргументами клиента. Результат — JSON, который можно передать в jq или сравнить с эталоном в тесте.

Чужие серверы

Инспектор подключается к любому серверу, не только к вашему. Хотите понять, что умеет сервер из npm или PyPI, прежде чем подключать его к Claude Code, — запустите его через инспектор и посмотрите вкладки Tools и Protocol. Для удалённого сервера укажите адрес:

bash

npx @modelcontextprotocol/inspector --server-url https://mcp.example.com/mcp --transport http

Это хороший способ оценить незнакомый сервер перед тем, как дать ему доступ к своим данным: видно каждый инструмент, его описание и аннотации.

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

Локальный сервер инспектора умеет запускать процессы. По умолчанию он слушает только localhost и защищён токеном; не отключайте ни то, ни другое и не открывайте инспектор на общий интерфейс сети. Если нужно показать сервер коллеге — покажите экран или дайте команду запуска.

Попробуйте сами

10–15 мин на рабочем месте

Запустите инспектор, подключитесь и вызовите edit_doc так, чтобы получить обе ошибки: «документа нет» и «фрагмент не найден». Найдите оба вызова во вкладке Protocol.
Временно добавьте print("привет") в начало docs_server.py и попробуйте подключиться. Прочитайте, что говорит Console. Уберите строку.
Выполните в режиме --cli запрос tools/list и сохраните вывод в файл. Подумайте, как использовать его в тесте: например, проверять, что у каждого параметра есть описание.

Коротко

npx @modelcontextprotocol/inspector uv run docs_server.py или uv run mcp dev docs_server.py — запуск инспектора с вашим сервером.
Открывать ссылку с токеном из терминала; инспектор умеет запускать процессы и потому защищён.
Tools — вызвать инструмент руками; Protocol — сырой JSON-RPC; Console — stderr сервера.
Инспектор ловит print() в stdout, плохие описания и исключения вместо ToolError.
Режим --cli с --method tools/list и tools/call — для CI и быстрых проверок.
Через инспектор удобно изучать чужие серверы до того, как давать им доступ.

Видеоверсия

Сценарий озвучки · 466 слов, ≈ 4 мин

Проверять сервер скриптом удобно, но неудобно смотреть, что именно летает по проводу. Для этого есть MCP Inspector — официальный графический инструмент, который подключается к любому серверу и даёт потыкать его руками.

Инспектор — пакет для Node, устанавливать его не нужно: команда «эн-пи-икс» скачает и запустит нужную версию. После имени пакета указываете команду запуска вашего сервера, и инспектор поднимет его как дочерний процесс — точно так же, как это сделал бы Claude Code. Есть и второй способ, через утилиту из SDK: команда «эм-си-пи дев» с именем файла делает то же самое.

В терминале появится ссылка с длинным токеном. Открывайте именно её. Инспектор состоит из веб-страницы и маленького локального сервера, который умеет запускать процессы на вашей машине, поэтому доступ защищён одноразовым токеном. Не отключайте эту защиту и не открывайте инспектор в сеть.

Что на экране. Панель подключения: транспорт, команда, переменные окружения. Нажимаете «подключиться», и появляются вкладки. Какие — зависит от того, что объявил сервер: нет промптов — нет вкладки промптов.

Вкладка «Tools» — список инструментов. Выбираете «прочитать документ», видите описание, схему аргументов в виде формы и аннотации. Вводите имя файла, вызываете, смотрите результат. Введите имя с опечаткой — увидите, как выглядит ответ с флагом ошибки. Это самый быстрый способ проверить, что модель увидит то, что вы задумали.

Вкладка «Protocol» — полный журнал обмена: каждый запрос в паре с ответом. Здесь видно всё, о чём мы говорили в уроке про архитектуру: запрос списка инструментов, вызов с аргументами, содержимое ответа. Когда что-то не работает, эта вкладка отвечает на вопрос «дошёл ли запрос и что вернулось».

Вкладка «Console» — поток ошибок процесса сервера. Сюда попадает всё, что вы пишете через логирование. Если сервер падает при старте — трейсбек тоже здесь.

Типичный цикл: подключились, проверили, что инструменты на месте и описания читаются. Вызвали каждый с правильными и заведомо неправильными аргументами. Посмотрели в журнале, что схема такая, как ожидалось. Поправили код, переподключились, повторили. Три вещи, которые инспектор ловит лучше всего: случайную печать в стандартный вывод — сервер просто не подключится, а в консоли будет видно, почему; параметры без описаний; и исключения, которые вылетают наружу вместо специального «ToolError».

У инспектора есть и режим командной строки. Флаг «си-эл-ай» ставится сразу после имени пакета, дальше команда сервера и метод: список инструментов или вызов инструмента с аргументами. Результат — джейсон в терминал. Это удобно для проверок в CI и для быстрого вопроса «что умеет этот сервер».

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

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

Следующий модуль — про клиент. Напишем программу, которая запускает наш сервер, получает инструменты и отдаёт их Claude.

Отметка хранится только в вашем браузере