Решение проблем с MCP-серверами
Типовые проблемы при подключении MCP в Cursor / Claude / Cline / Continue: spawn ENOENT, JSON parse errors, env-vars, лимиты провайдера.
Обновлено:
MCP не появляется в IDE
1. JSON невалидный
Самая частая причина. Один пропущенный , или лишняя , после последнего элемента — и Cursor /
Claude молча игнорируют конфиг.
Решение: проверить через jsonlint.com или python -m json.tool < ~/.cursor/mcp.json.
2. IDE не перезапущен полностью
Reload Window / закрытие окна недостаточно. Нужно полностью завершить процесс:
- macOS:
Cmd+QилиQuit Cursorиз меню. - Windows: правый клик по иконке в трее → Quit.
- Linux:
pkill cursorили иконку из системного трея.
3. Команда не найдена (spawn uvx ENOENT)
В логах: Error: spawn uvx ENOENT. Это значит, что процесс IDE не нашёл uvx в PATH.
Причины:
uvне установлен (uvx --versionв терминале — что говорит?).- IDE запущена раньше, чем
uvпоявился в PATH. - На macOS: GUI-приложения не подхватывают PATH из
.zshrc/.bashrc.
Решения:
-
Указать полный путь к
uvx:"command": "/Users/<you>/.local/bin/uvx"Узнать путь:
which uvxилиwhere uvx(Windows). -
На macOS — установить переменную глобально через
launchctl:launchctl setenv PATH "$HOME/.local/bin:$PATH"Логин-шелл для GUI-процессов.
-
Перезагрузить компьютер после установки
uv— иногда помогает.
Сервер запустился, но тулы не работают
401 / 403 от провайдера
Проверьте имя переменной ключа в конфигурации конкретного клиента и права на нужный пакет.
Для проверки авторизации нужен защищённый метод: ответ health без авторизации не проверяет ключ.
В шаблоне ATOMNO_METHOD_URL — полный URL защищённого метода из инструкции подключения;
ATOMNO_API_KEY — ваш ключ. Заголовок авторизации и параметры запроса тоже берите из инструкции метода.
curl -H "Authorization: Bearer $ATOMNO_API_KEY" "$ATOMNO_METHOD_URL"
401 означает проблему с авторизацией; 403 может означать отсутствие права на этот метод или пакет.
429 Too Many Requests
Провайдер достиг rate-limit’а. Например, ФНС лимитирует 10 запросов/минуту для public API.
Решения:
- Проверить лимиты вашего тарифа и подключённого сервиса: см. тарифы.
- Закэшировать результаты в сценарии работы агента.
Timeout (медленные ответы)
Государственные API РФ нередко тормозят. Если по умолчанию таймаут 30s — настройте через env-var (поддерживаются всеми MCP):
"env": {
"MCP_FNS_CHECK_TIMEOUT": "60"
}
MCP падает при запуске
Откройте логи:
| IDE | Путь |
|---|---|
| Cursor | Settings → MCP → Logs или Output panel → MCP |
| Claude Desktop (mac) | ~/Library/Logs/Claude/mcp*.log |
| Claude Desktop (win) | %APPDATA%\Claude\logs\mcp*.log |
| Cline | Output panel → Cline |
| Continue | Output panel → Continue |
Типовые ошибки:
ModuleNotFoundError: No module named 'mcp_<name>'
Не должно происходить с uvx (он сам ставит зависимости). Если случилось — очистите кэш uv:
uv cache clean
И перезапустите IDE.
pydantic.ValidationError
Сохраните обезличенный текст ошибки, название и версию пакета и условия вызова. Передайте эти сведения через подходящий канал со страницы контактов. Срок исправления нужно уточнять при разборе конкретного обращения.
Performance проблемы
Cursor стартует медленно после добавления MCP
Сравните первый и повторный запуск в одной среде. По сообщениям запуска выясните, на каком этапе остаётся ожидание: получение пакета, запуск процесса или подключение клиента.
Сохраните версию пакета, клиент и обезличенный журнал с отметками времени. Не очищайте весь кэш только потому, что его размер превысил произвольный порог: сначала установите, связан ли он с наблюдаемой задержкой.
Тулы вызываются слишком медленно
Условный пример журнала, а не результат измерения конкретного сервиса:
[INFO] check_inn started: inn=7707083893
[INFO] http GET https://egrul.nalog.ru/... 200 OK in 1.4s
[INFO] check_inn finished in 1.5s
Разделяйте общее время вызова и время отдельного HTTP-запроса. Одна отметка в журнале не устанавливает причину всей задержки. Сохраните условия вызова и сравните этапы, прежде чем выбирать способ исправления. Условия доступа или выбранный пакет сами по себе не являются обещанием ускорения.
Когда нужно писать в issues / поддержку
Выберите подходящий канал на странице контактов. Для сбоя конкретного MCP подготовьте название и версию пакета, приложение, ОС, инструмент и обезличенный текст ошибки. По вопросу доступа укажите нужный метод и наблюдаемый код ответа без ключа.
Не отправляйте пароли, токены и чужие личные данные. Ссылку на конкретный репозиторий берите из документации выбранного проекта, а не составляйте из шаблона с <name>.
Что дальше
- Безопасность MCP → — чек-лист.
- Контрибьюция → — как помочь open-source MCP.
Частые вопросы
Что означает ошибка spawn uvx ENOENT?
Приложение не нашло программу uvx. Проверьте её установку и PATH именно процесса приложения. При необходимости задайте полный путь в command и полностью перезапустите приложение.
Ответ 401 или 403 означает, что источник не работает?
Не обязательно. Проверьте имя переменной ключа, заголовок авторизации и права на нужный метод или пакет. Общедоступный health-ответ не проверяет ваш ключ; для этого нужен предусмотренный инструкцией защищённый метод.
Что делать, если сервер появился, но инструмент не возвращает данные?
Проверьте аргументы вызова, настройки доступа и сообщение источника в журнале. Состояние подключения MCP и получение данных — разные этапы; успешный запуск процесса не гарантирует ответ внешнего сервиса.
Что приложить к обращению о неполадке?
Название и версию пакета, приложение, ОС, инструмент и обезличенный текст ошибки. Не отправляйте пароли, ключи, токены и личные данные других людей; контакты для обращения указаны на сайте.
Ошибка JSON в файле настроек означает недоступность MCP-сервера?
Нет. Некорректная конфигурация может помешать запуску до любого обращения к источнику. Проверьте синтаксис и формат именно вашего клиента.
Как проверить авторизацию, не раскрывая ключ поддержке?
Сверьте имя переменной или заголовка с инструкцией продукта. В обращении укажите способ передачи и код ошибки, заменив значение секрета на заглушку.
Нужно ли повторять платёж или запись, чтобы сообщить об ошибке?
Нет. Для первичного разбора приложите обезличенную ошибку, время и выполненное действие. Не запускайте изменяющую операцию только ради повторения сообщения.
