Тестирование и отладка MCP-серверов с помощью MCP Inspector

MCP Inspector — это мощный инструмент для валидации, тестирования и отладки MCP-серверов. Это практическое руководство проведёт вас через использование Inspector, чтобы убедиться, что ваш MCP-сервер работает корректно, и устранить типичные проблемы.

Что такое MCP Inspector?

MCP Inspector — это инструмент отладки, который позволяет:

Подключаться напрямую к MCP-серверу
Получать список доступных инструментов и ресурсов
Выполнять тестовые вызовы инструментов
Просматривать полезную нагрузку запросов/ответов
Отлаживать проблемы аутентификации
Проверять ответы сервера

Как получить MCP Inspector

MCP Inspector обычно доступен в виде:

Инструмента командной строки
Веб-интерфейса
Части инструментов разработки MCP

Актуальные версии инструмента Inspector и инструкции по установке смотрите в официальной документации MCP.

Шаг 1: Подключитесь к вашему MCP-серверу

Начните с подключения Inspector к вашему MCP-серверу. Для Workify:

Параметры подключения

URL эндпоинта: https://app.workify.ru/mcp
Транспорт: HTTP/SSE (удалённый сервер)
Аутентификация: Bearer-токен (API-ключ)

Использование Inspector CLI

Если вы используете Inspector в командной строке:

mcp-inspector \
  --url https://app.workify.ru/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

⚠️ Замечание по безопасности

Никогда не коммитьте свой API-ключ в систему контроля версий. Используйте переменные окружения или безопасное хранилище ключей. В примерах мы используем YOUR_API_KEY в качестве заполнителя.

Шаг 2: Получите список доступных инструментов

После подключения первое, что нужно проверить, — доступны ли инструменты. Inspector должен показать список инструментов, предоставляемых сервером.

Ожидаемый вывод для Workify

Вы должны увидеть инструменты вроде:

list_tasks
get_task
create_task
update_task
delete_task
list_projects
get_project
list_boards
get_board
list_task_comments
add_task_comment
start_time_tracking
stop_time_tracking
get_tracking_status

Если инструменты не отображаются

Если список инструментов пуст, проверьте:

Действителен и активен ли API-ключ?
Правильный ли URL эндпоинта?
Нет ли проблем с сетью/файрволом?
Запущен ли сервер и доступен ли он?

Дополнительную помощь смотрите в нашем руководстве по устранению неполадок.

Шаг 3: Выполните простой вызов инструмента

Проверьте подключение, выполнив простой вызов инструмента только для чтения. Начните с list_tasks:

Пример: list_tasks

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

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 5
  }
}

Ожидаемый ответ:

{
  "tasks": [
    {
      "id": 123,
      "title": "Example Task",
      "status": "open",
      ...
    }
  ],
  "total": 10
}

Интерпретация ответа

Успешный ответ означает:

✅ Подключение работает
✅ Аутентификация действительна
✅ Сервер обрабатывает запросы
✅ Инструмент функционирует корректно

Шаг 4: Протестируйте аутентификацию

Убедитесь, что аутентификация работает корректно:

Тест с действительным ключом

С действительным API-ключом вы должны:

Успешно подключиться
Увидеть список инструментов
Иметь возможность выполнять вызовы инструментов

Тест с недействительным ключом

С недействительным/отозванным ключом вы должны увидеть:

Ошибку 401 Unauthorized
Отказ в подключении
Отсутствие списка инструментов

Читать руководство по устранению ошибки 401 →

Пример рабочего процесса Workify

Вот полный процесс валидации на примере Workify:

Чек-лист валидации

Подключитесь к серверу

mcp-inspector --url https://app.workify.ru/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Получите список инструментов
Убедитесь, что видите инструменты Workify (list_tasks, create_task и т. д.)
Протестируйте list_tasks
```
{
  "tool": "list_tasks",
  "arguments": {
    "limit": 5
  }
}
```
Должен вернуться список задач (или пустой массив, если задач нет)
Протестируйте get_task
```
{
  "tool": "get_task",
  "arguments": {
    "task_id": 123
  }
}
```
Должны вернуться сведения о задаче (или ошибка, если задача не существует)
Протестируйте create_task (опционально — операция записи)
```
{
  "tool": "create_task",
  "arguments": {
    "title": "Test Task from Inspector",
    "description": "Testing MCP connection",
    "project_id": YOUR_PROJECT_ID
  }
}
```
Должна создаться задача и вернуться объект новой задачи
⚠️ Это создаст реальную задачу — используйте осторожно!

Интерпретация ошибок

Inspector помогает понять, что пошло не так:

401 Unauthorized

Значение: Аутентификация не удалась

Частые причины:

Недействительный API-ключ
Отозванный API-ключ
Отсутствует заголовок Authorization
Неверный формат Bearer

Исправить ошибки 401 →

403 Forbidden

Значение: Аутентифицирован, но не авторизован

Частые причины:

У ключа нет доступа к запрашиваемому ресурсу
Несоответствие прав рабочего пространства/команды
Ресурс не существует или является приватным

Исправить ошибки 403 →

400 Bad Request

Значение: Недопустимые параметры запроса

Частые причины:

Отсутствуют обязательные параметры
Недопустимые типы параметров
Недопустимые идентификаторы (task_id, project_id и т. д.)
Ошибки валидации

Исправить ошибки валидации →

Отказ в подключении / таймаут

Значение: Не удаётся достичь сервера

Частые причины:

Проблемы с сетевым подключением
Файрвол блокирует подключение
Помехи корпоративного прокси
Сервер недоступен

Исправить проблемы с подключением →

Чек-лист отладки

Быстрый чек-лист отладки

✅ Убедитесь, что API-ключ активен в Workify: Настройки → Интеграции
✅ Проверьте правильность URL эндпоинта: https://app.workify.ru/mcp
✅ Подтвердите формат заголовка Authorization: Bearer YOUR_API_KEY (с пробелом)
✅ Проверьте доступность эндпоинта (попробуйте в браузере или через curl)
✅ Проверьте корректность синтаксиса JSON (нет висячих запятых, правильные кавычки)
✅ Убедитесь, что сеть/файрвол не блокирует подключение
✅ Просмотрите логи сервера на предмет сообщений об ошибках
✅ Сначала попробуйте простой вызов инструмента только для чтения (list_tasks)
✅ Убедитесь, что параметры инструмента соответствуют ожидаемой схеме
✅ Проверьте наличие ограничения частоты запросов (ошибки 429)

Продвинутая отладка

Просмотр полезной нагрузки запросов/ответов

Inspector показывает вам точный запрос и ответ:

Полезная нагрузка запроса

POST https://app.workify.ru/mcp
Headers:
  Authorization: Bearer sk_...
  Content-Type: application/json

Body:
{
  "tool": "list_tasks",
  "arguments": {
    "limit": 10,
    "project_id": 456
  }
}

Полезная нагрузка ответа

Status: 200 OK

Body:
{
  "tasks": [...],
  "total": 25,
  "has_more": true
}

Тестирование сценариев ошибок

Используйте Inspector для тестирования обработки ошибок:

Вызовите инструмент с недопустимыми параметрами
Попробуйте обратиться к несуществующему ресурсу
Протестируйте с отозванным API-ключом
Убедитесь, что сообщения об ошибках полезны

Устранение типичных проблем

Проблема: «Список инструментов пуст»

Возможные причины:

Аутентификация незаметно завершается неудачей
Сервер не возвращает инструменты
Проблема с кэшированием на стороне клиента

Решение: Сначала проверьте аутентификацию, затем убедитесь, что сервер отвечает. См. устранение неполадок со списком инструментов.

Проблема: «Вызов инструмента завершается ошибкой валидации»

Возможные причины:

Отсутствуют обязательные параметры
Неверные типы параметров
Недопустимые идентификаторы

Решение: Проверьте схему инструмента, убедитесь, что типы параметров совпадают. См. справочник по инструментам для правильных параметров.

Проблема: «Истекает время ожидания подключения»

Возможные причины:

Проблемы с сетевым подключением
Файрвол блокирует HTTPS
Проблемы с корпоративным прокси
Сервер перегружен

Решение: Проверьте доступность эндпоинта, проверьте сетевые настройки. См. устранение неполадок с подключением.

Использование результатов Inspector

Как только Inspector подтвердит, что ваш сервер работает:

Поделитесь результатами с командой: Задокументируйте рабочую конфигурацию
Отлаживайте проблемы клиента: Сравните результаты Inspector с поведением клиента
Проверяйте изменения: Тестируйте после обновлений сервера или изменений конфигурации
Онбордите новых пользователей: Используйте Inspector для проверки их настройки

Нужна дополнительная помощь?

Ознакомьтесь с нашими подробными руководствами по устранению неполадок

Указатель по устранению неполадок →Чек-лист отладки