{"title":"Устранение проблем MCP","slug":"troubleshooting","category":"mcp","summary":"Решение типовых проблем интеграции MCP — сервер не запускается, инструменты не появляются, ошибки аутентификации.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":529,"read_minutes":3,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"ru","translated":true,"requested_lang":"ru","content_markdown":"\n# Устранение проблем MCP\n\nТиповые проблемы и решения при интеграции Synapse MCP с вашим LLM-клиентом.\n\n## Быстрый диагностический чек-лист\n\n1. ✅ Установлен Node.js 18+? (`node --version`)\n2. ✅ Mind Key начинается с `mk_`? (а не с JWT `eyJ...`)\n3. ✅ Synapse API доступен? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key работает? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Файл конфигурации — валидный JSON? (без trailing-запятых, без комментариев)\n6. ✅ Клиент перезапущен после изменения конфигурации?\n7. ✅ MCP-сервер запускается вручную? (`npx -y synapse-mcp-api@latest`)\n\n## Проблема: в клиенте не появляются инструменты\n\n### Симптомы\n\n- Claude Desktop / Cursor / Continue показывает 0 инструментов\n- Нет иконки 🔌 или записи «synapse» в списке MCP-серверов\n\n### Решения\n\n1. **Полностью перезапустите клиент** — Cmd+Q на macOS (не просто закрыть окно)\n2. **Проверьте расположение файла конфигурации**:\n - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor: `~/.cursor/config.json`\n - Continue: `~/.continue/config.json`\n3. **Валидируйте JSON** — вставьте конфиг в \n4. **Проверьте логи клиента** на ошибки MCP:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Запустите MCP-сервер вручную**, чтобы увидеть ошибки запуска:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Проблема: ошибка «Mind Key invalid»\n\n### Симптомы\n\n- Инструменты появляются, но вызовы падают с «401 Unauthorized»\n- Ошибка: «Mind Key fehlt oder ungültig»\n\n### Решения\n\n1. **Проверьте формат Mind Key** — начинается с `mk_`, ~40 символов\n2. **Протестируйте напрямую**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **Убедитесь, что переменная окружения установлена** — для транспорта stdio\n переменная должна быть в конфигурации MCP-сервера, а не в вашей оболочке\n4. **Получите новый Mind Key**:\n ```bash\n # Login to get JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Create new mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Проблема: npx не найден\n\n### Симптомы\n\n- Ошибка: «npx: command not found»\n- MCP-сервер не запускается\n\n### Решения\n\n1. **Установите Node.js 18+**:\n - macOS: `brew install node` или скачайте с \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: скачайте с \n2. **Перезапустите терминал** после установки\n3. **Проверьте**: `node --version && npx --version`\n\n## Проблема: SYNAPSE_URL недоступен\n\n### Симптомы\n\n- MCP-сервер запускается, но вызовы инструментов тайм-аутятся\n- Ошибка: «fetch failed» или «ECONNREFUSED»\n\n### Решения\n\n1. **Проверьте подключение**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Проверьте корпоративный firewall** — может блокировать исходящий HTTPS\n3. **Попробуйте альтернативный URL**:\n - Продакшен: `https://synapse.schaefer.zone`\n - MCP-сервер: `https://synapse-mcp.schaefer.zone`\n4. **Для self-hosted**: убедитесь, что ваш экземпляр Synapse запущен и доступен\n\n## Проблема: MCP-сервер падает\n\n### Симптомы\n\n- MCP-сервер завершается сразу после запуска\n- Логи клиента показывают «MCP server disconnected»\n\n### Решения\n\n1. **Запустите вручную, чтобы увидеть ошибку**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Проверьте конфликты портов** — MCP-сервер использует порт 13100 по умолчанию\n3. **Очистите кэш npx**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Обновите до последней версии**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Проблема: вызовы инструментов возвращают 429\n\n### Симптомы\n\n- Ошибка: «Rate limit exceeded»\n\n### Решения\n\nС MCP этого не должно происходить (используется header-auth, без лимита). Если происходит:\n\n1. **Проверьте, не используете ли вы где-то `?key=`** — перейдите на header-auth\n2. **Убедитесь, что `SYNAPSE_URL`** указывает на нужный экземпляр\n3. **Обратитесь в поддержку**, если проблема сохраняется\n\n## Проблема: инструменты видны, но не работают\n\n### Симптомы\n\n- Инструменты перечислены в клиенте\n- Вызов инструмента возвращает ошибку или пустой результат\n\n### Решения\n\n1. **Проверьте имя инструмента** — должно быть точным (например, `memory_recall`, а не `memory.recall`)\n2. **Проверьте аргументы** — сверьтесь со входной схемой инструмента\n3. **Протестируйте через прямой API**:\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **Проверьте здоровье Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Получение помощи\n\nЕсли ничего из вышеперечисленного не помогло:\n\n1. **Проверьте существующие issues**: \n2. **Создайте новый issue**, указав:\n - Версию MCP-сервера (`npx -y synapse-mcp-api@latest --version`)\n - Имя и версию клиента\n - Операционную систему\n - Соответствующие выдержки из логов\n - Шаги для воспроизведения\n\n## Следующие шаги\n\n- [Настройка Claude Desktop](/docs/mcp/claude-desktop)\n- [Настройка Claude Code](/docs/mcp/claude-code)\n- [Ошибки API](/docs/api/errors)\n","content_html":"

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

\n

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

\n

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

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

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

\n

Симптомы

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

Решения

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

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

\n

Симптомы

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

Решения

\n
    \n
  1. Проверьте формат Mind Key — начинается с mk_, ~40 символов
    2. \n
  2. Протестируйте напрямую:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. Убедитесь, что переменная окружения установлена — для транспорта stdio\nпеременная должна быть в конфигурации MCP-сервера, а не в вашей оболочке
    4. \n
  4. Получите новый Mind Key:
    # Login to get JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Create new mind\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

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

\n

Симптомы

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

Решения

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

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

\n

Симптомы

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

Решения

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

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

\n

Симптомы

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

Решения

\n
    \n
  1. Запустите вручную, чтобы увидеть ошибку:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Проверьте конфликты портов — MCP-сервер использует порт 13100 по умолчанию
    3. \n
  3. Очистите кэш npx:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. Обновите до последней версии:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

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

\n

Симптомы

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

Решения

\n

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

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

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

\n

Симптомы

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

Решения

\n
    \n
  1. Проверьте имя инструмента — должно быть точным (например, memory_recall, а не memory.recall)
    2. \n
  2. Проверьте аргументы — сверьтесь со входной схемой инструмента
    3. \n
  3. Протестируйте через прямой API:
    curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer mk_..." \\\n  -H "Content-Type: application/json" \\\n  -d '{"category":"fact","key":"test","content":"hello"}'
    4. \n
  4. Проверьте здоровье Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

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

\n

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

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

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

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}