# Вирішення проблем 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? (без кінцевих ком, без коментарів)
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. Перевірте корпоративний фаєрвол — може блокувати вихідний HTTPS
3. Спробуйте альтернативний URL:
   - Production: 
   - MCP-сервер: 
4. Для самостійно розгорнутих: переконайтеся, що ваш екземпляр Synapse працює та доступний
Проблема: MCP-сервер аварійно завершується
Симптоми
- MCP-сервер завершується одразу після запуску
- Логи клієнта показують «MCP server disconnected»
Рішення
1. Запустіть вручну, щоб побачити помилку:
   [CODE BLOCK]
2. Перевірте конфлікти портів — MCP-сервер використовує порт 13100 за замовчуванням
3. Очистіть кеш npx:
   [CODE BLOCK]
4. Оновіть до останньої версії:
   [CODE BLOCK]
Проблема: виклики інструментів повертають 429
Симптоми
- Помилка: «Rate limit exceeded»
Рішення
Цього не повинно траплятися з MCP (використовується автентифікація через заголовок, без обмеження частоти). Якщо все ж трапилось:
1. Перевірте, чи використовуєте  десь — перейдіть на автентифікацію через заголовок
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