Troubleshooting MCP-серверов

Типовые проблемы при подключении MCP в Cursor / Claude / Cline / Continue: spawn ENOENT, JSON parse errors, env-vars, лимиты провайдера.

Обновлено: 2026-04-28

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 от провайдера

Проверьте env-vars:

# Проверить что токен валидный
curl -H "Authorization: Bearer $MCP_FNS_CHECK_TOKEN" \
     https://api.atomno-labs.ru/fns-check/health

Если 200 — токен ок, дело в чём-то ещё. Если 401/403 — токен истёк / неправильный.

429 Too Many Requests

Провайдер достиг rate-limit’а. Например, ФНС лимитирует 10 запросов/минуту для public API.

Решения:

Перейти на Pro tier (hosted backend без лимитов): см. /pricing.
Закэшировать результаты в самом workflow агента.

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`

MCP получил от провайдера ответ в неожиданном формате (провайдер сменил API). Зарепортите issue в нашем репозитории — обычно фикс выходит в течение дня.

https://github.com/atomno-labs/mcp-<name>/issues

Performance проблемы

Cursor стартует медленно после добавления MCP

Каждый MCP при старте может занять 1-3 секунды (uvx скачивает пакет если его нет в кэше).

Первый запуск: ~3-5 секунд на 5 MCP.
Дальше: ~0.3-0.5 секунды (всё в кэше).

Если кэш не помогает — посмотрите размер ~/.cache/uv/ (du -sh). Если >5GB — uv cache clean.

Тулы вызываются слишком медленно

Логи 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 GET занимает 5+ секунд — это API провайдера, не MCP. Кэш + Pro-tier помогут.

Когда нужно писать в issues / поддержку

Проблема	Куда
Конкретный MCP падает / неправильный ответ	`github.com/atomno-labs/mcp-<name>/issues`
Pro-tier 401 / 403 / rate-limit	`support@atomno.com`
Custom-MCP под заказ / consulting	`sales@atomno.com`
Общий вопрос про экосистему MCP	Telegram-канал @atomno_pulse

Что дальше

Безопасность MCP → — чек-лист.
Контрибьюция → — как помочь open-source MCP.