# Устранение проблем MCP
SUMMARY: Решение типовых проблем интеграции MCP — сервер не запускается, инструменты не появляются, ошибки аутентификации.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

Устранение проблем MCP
Типовые проблемы и решения при интеграции Synapse MCP с вашим LLM-клиентом.
Быстрый диагностический чек-лист
1. ✅ Установлен Node.js 18+? ()
2. ✅ Mind Key начинается с ? (а не с JWT )
3. ✅ Synapse API доступен? ()
4. ✅ Mind Key работает? ()
5. ✅ Файл конфигурации — валидный JSON? (без trailing-запятых, без комментариев)
6. ✅ Клиент перезапущен после изменения конфигурации?
7. ✅ MCP-сервер запускается вручную? ()
Проблема: в клиенте не появляются инструменты
Симптомы
- Claude Desktop / Cursor / Continue показывает 0 инструментов
- Нет иконки 🔌 или записи «synapse» в списке MCP-серверов
Решения
1. Полностью перезапустите клиент — Cmd+Q на macOS (не просто закрыть окно)
2. Проверьте расположение файла конфигурации:
   - Claude Desktop macOS: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. Валидируйте JSON — вставьте конфиг в <https://jsonlint.com>
4. Проверьте логи клиента на ошибки MCP:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. Запустите MCP-сервер вручную, чтобы увидеть ошибки запуска:
   [CODE BLOCK]
Проблема: ошибка «Mind Key invalid»
Симптомы
- Инструменты появляются, но вызовы падают с «401 Unauthorized»
- Ошибка: «Mind Key fehlt oder ungültig»
Решения
1. Проверьте формат Mind Key — начинается с , 40 символов
2. Протестируйте напрямую:
   [CODE BLOCK]
3. Убедитесь, что переменная окружения установлена — для транспорта stdio
   переменная должна быть в конфигурации MCP-сервера, а не в вашей оболочке
4. Получите новый Mind Key:
   [CODE BLOCK]
Проблема: npx не найден
Симптомы
- Ошибка: «npx: command not found»
- MCP-сервер не запускается
Решения
1. Установите Node.js 18+:
   - macOS:  или скачайте с <https://nodejs.org>
   - Linux: 
   - Windows: скачайте с <https://nodejs.org>
2. Перезапустите терминал после установки
3. Проверьте: 
Проблема: SYNAPSEURL недоступен
Симптомы
- MCP-сервер запускается, но вызовы инструментов тайм-аутятся
- Ошибка: «fetch failed» или «ECONNREFUSED»
Решения
1. Проверьте подключение:
   [CODE BLOCK]
2. Проверьте корпоративный firewall — может блокировать исходящий HTTPS
3. Попробуйте альтернативный URL:
   - Продакшен: 
   - MCP-сервер: 
4. Для self-hosted: убедитесь, что ваш экземпляр Synapse запущен и доступен
Проблема: MCP-сервер падает
Симптомы
- MCP-сервер завершается сразу после запуска
- Логи клиента показывают «MCP server disconnected»
Решения
1. Запустите вручную, чтобы увидеть ошибку:
   [CODE BLOCK]
2. Проверьте конфликты портов — MCP-сервер использует порт 13100 по умолчанию
3. Очистите кэш npx:
   [CODE BLOCK]
4. Обновите до последней версии:
   [CODE BLOCK]
Проблема: вызовы инструментов возвращают 429
Симптомы
- Ошибка: «Rate limit exceeded»
Решения
С MCP этого не должно происходить (используется header-auth, без лимита). Если происходит:
1. Проверьте, не используете ли вы где-то  — перейдите на header-auth
2. Убедитесь, что  указывает на нужный экземпляр
3. Обратитесь в поддержку, если проблема сохраняется
Проблема: инструменты видны, но не работают
Симптомы
- Инструменты перечислены в клиенте
- Вызов инструмента возвращает ошибку или пустой результат
Решения
1. Проверьте имя инструмента — должно быть точным (например, , а не )
2. Проверьте аргументы — сверьтесь со входной схемой инструмента
3. Протестируйте через прямой API:
   [CODE BLOCK]
4. Проверьте здоровье Synapse:
   [CODE BLOCK]
Получение помощи
Если ничего из вышеперечисленного не помогло:
1. Проверьте существующие issues: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. Создайте новый issue, указав:
   - Версию MCP-сервера ()
   - Имя и версию клиента
   - Операционную систему
   - Соответствующие выдержки из логов
   - Шаги для воспроизведения
Следующие шаги
- Настройка Claude Desktop
- Настройка Claude Code
- Ошибки API