Перейти к основному содержанию

Решение проблем с 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.

Решения:

  1. Указать полный путь к uvx:

    "command": "/Users/<you>/.local/bin/uvx"

    Узнать путь: which uvx или where uvx (Windows).

  2. На macOS — установить переменную глобально через launchctl:

    launchctl setenv PATH "$HOME/.local/bin:$PATH"

    Логин-шелл для GUI-процессов.

  3. Перезагрузить компьютер после установки 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Путь
CursorSettings → MCP → Logs или Output panel → MCP
Claude Desktop (mac)~/Library/Logs/Claude/mcp*.log
Claude Desktop (win)%APPDATA%\Claude\logs\mcp*.log
ClineOutput panel → Cline
ContinueOutput 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>.

Что дальше

Частые вопросы

Что означает ошибка spawn uvx ENOENT?

Приложение не нашло программу uvx. Проверьте её установку и PATH именно процесса приложения. При необходимости задайте полный путь в command и полностью перезапустите приложение.

Ответ 401 или 403 означает, что источник не работает?

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

Что делать, если сервер появился, но инструмент не возвращает данные?

Проверьте аргументы вызова, настройки доступа и сообщение источника в журнале. Состояние подключения MCP и получение данных — разные этапы; успешный запуск процесса не гарантирует ответ внешнего сервиса.

Что приложить к обращению о неполадке?

Название и версию пакета, приложение, ОС, инструмент и обезличенный текст ошибки. Не отправляйте пароли, ключи, токены и личные данные других людей; контакты для обращения указаны на сайте.

Ошибка JSON в файле настроек означает недоступность MCP-сервера?

Нет. Некорректная конфигурация может помешать запуску до любого обращения к источнику. Проверьте синтаксис и формат именно вашего клиента.

Как проверить авторизацию, не раскрывая ключ поддержке?

Сверьте имя переменной или заголовка с инструкцией продукта. В обращении укажите способ передачи и код ошибки, заменив значение секрета на заглушку.

Нужно ли повторять платёж или запись, чтобы сообщить об ошибке?

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

Просмотр кода

Копируется исходный текст. Переносы меняют только отображение.

Текст

Поиск по сайту

Введите хотя бы два символа.

Tab — переход по ссылкам · Esc — закрыть