Устранение проблем MCP

Типовые проблемы и решения при интеграции Synapse MCP с вашим LLM-клиентом.

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

1. ✅ Установлен Node.js 18+? (node --version)
2. ✅ Mind Key начинается с mk_? (а не с JWT eyJ...)
3. ✅ Synapse API доступен? (curl https://synapse.schaefer.zone/health)
4. ✅ Mind Key работает? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
5. ✅ Файл конфигурации — валидный JSON? (без trailing-запятых, без комментариев)
6. ✅ Клиент перезапущен после изменения конфигурации?
7. ✅ MCP-сервер запускается вручную? (npx -y synapse-mcp-api@latest)

Проблема: в клиенте не появляются инструменты

Симптомы

• Claude Desktop / Cursor / Continue показывает 0 инструментов
• Нет иконки 🔌 или записи «synapse» в списке MCP-серверов

Решения

1. Полностью перезапустите клиент — Cmd+Q на macOS (не просто закрыть окно)
2. Проверьте расположение файла конфигурации:
   • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Cursor: ~/.cursor/config.json
   • Continue: ~/.continue/config.json
3. Валидируйте JSON — вставьте конфиг в https://jsonlint.com
4. Проверьте логи клиента на ошибки MCP:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. Запустите MCP-сервер вручную, чтобы увидеть ошибки запуска:

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

Проблема: ошибка «Mind Key invalid»

Симптомы

• Инструменты появляются, но вызовы падают с «401 Unauthorized»
• Ошибка: «Mind Key fehlt oder ungültig»

Решения

1. Проверьте формат Mind Key — начинается с mk_, ~40 символов
2. Протестируйте напрямую:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

3. Убедитесь, что переменная окружения установлена — для транспорта stdio переменная должна быть в конфигурации MCP-сервера, а не в вашей оболочке
4. Получите новый Mind Key:

   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

Проблема: npx не найден

Симптомы

• Ошибка: «npx: command not found»
• MCP-сервер не запускается

Решения

1. Установите Node.js 18+:
   • macOS: brew install node или скачайте с https://nodejs.org
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: скачайте с https://nodejs.org
2. Перезапустите терминал после установки
3. Проверьте: node --version && npx --version

Проблема: SYNAPSE_URL недоступен

Симптомы

• MCP-сервер запускается, но вызовы инструментов тайм-аутятся
• Ошибка: «fetch failed» или «ECONNREFUSED»

Решения

1. Проверьте подключение:

   curl https://synapse.schaefer.zone/health

2. Проверьте корпоративный firewall — может блокировать исходящий HTTPS
3. Попробуйте альтернативный URL:
   • Продакшен: https://synapse.schaefer.zone
   • MCP-сервер: https://synapse-mcp.schaefer.zone
4. Для self-hosted: убедитесь, что ваш экземпляр Synapse запущен и доступен

Проблема: MCP-сервер падает

Симптомы

• MCP-сервер завершается сразу после запуска
• Логи клиента показывают «MCP server disconnected»

Решения

1. Запустите вручную, чтобы увидеть ошибку:

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. Проверьте конфликты портов — MCP-сервер использует порт 13100 по умолчанию
3. Очистите кэш npx:

   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx

4. Обновите до последней версии:

   npx -y synapse-mcp-api@latest --version

Проблема: вызовы инструментов возвращают 429

Симптомы

• Ошибка: «Rate limit exceeded»

Решения

С MCP этого не должно происходить (используется header-auth, без лимита). Если происходит:

1. Проверьте, не используете ли вы где-то ?key= — перейдите на header-auth
2. Убедитесь, что SYNAPSE_URL указывает на нужный экземпляр
3. Обратитесь в поддержку, если проблема сохраняется

Проблема: инструменты видны, но не работают

Симптомы

• Инструменты перечислены в клиенте
• Вызов инструмента возвращает ошибку или пустой результат

Решения

1. Проверьте имя инструмента — должно быть точным (например, memory_recall, а не memory.recall)
2. Проверьте аргументы — сверьтесь со входной схемой инструмента
3. Протестируйте через прямой API:

   curl -X POST https://synapse.schaefer.zone/memory \
     -H "Authorization: Bearer mk_..." \
     -H "Content-Type: application/json" \
     -d '{"category":"fact","key":"test","content":"hello"}'

4. Проверьте здоровье Synapse:

   curl https://synapse.schaefer.zone/health

Получение помощи

Если ничего из вышеперечисленного не помогло:

1. Проверьте существующие issues: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. Создайте новый issue, указав:
   • Версию MCP-сервера (npx -y synapse-mcp-api@latest --version)
   • Имя и версию клиента
   • Операционную систему
   • Соответствующие выдержки из логов
   • Шаги для воспроизведения

Следующие шаги

• Настройка Claude Desktop
• Настройка Claude Code
• Ошибки API