# Вирішення проблем 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-сервер вручну**, щоб побачити помилки запуску:
   ```bash
   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. **Протестуйте безпосередньо**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **Перевірте, що змінну середовища встановлено** — для транспорту stdio змінна середовища має бути в конфігурації MCP-сервера, а не у вашій оболонці
4. **Отримайте свіжий Mind Key**:
   ```bash
   # 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. **Перевірте з'єднання**:
   ```bash
   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. **Запустіть вручну, щоб побачити помилку**:
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **Перевірте конфлікти портів** — MCP-сервер використовує порт 13100 за замовчуванням
3. **Очистіть кеш npx**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Оновіть до останньої версії**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Налаштування Claude Code](/docs/mcp/claude-code)
- [Помилки API](/docs/api/errors)