# Устранение проблем 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-сервер вручную**, чтобы увидеть ошибки запуска:
   ```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. **Проверьте корпоративный firewall** — может блокировать исходящий HTTPS
3. **Попробуйте альтернативный URL**:
   - Продакшен: `https://synapse.schaefer.zone`
   - MCP-сервер: `https://synapse-mcp.schaefer.zone`
4. **Для self-hosted**: убедитесь, что ваш экземпляр 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 этого не должно происходить (используется header-auth, без лимита). Если происходит:

1. **Проверьте, не используете ли вы где-то `?key=`** — перейдите на header-auth
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)