Вирішення проблем 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? (без кінцевих ком, без коментарів)
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. Перевірте корпоративний фаєрвол — може блокувати вихідний HTTPS
3. Спробуйте альтернативний URL:
   • Production: https://synapse.schaefer.zone
   • MCP-сервер: https://synapse-mcp.schaefer.zone
4. Для самостійно розгорнутих: переконайтеся, що ваш екземпляр 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 (використовується автентифікація через заголовок, без обмеження частоти). Якщо все ж трапилось:

1. Перевірте, чи використовуєте ?key= десь — перейдіть на автентифікацію через заголовок
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