{"title":"Вирішення проблем MCP","slug":"troubleshooting","category":"mcp","summary":"Вирішення типових проблем інтеграції MCP — сервер не запускається, інструменти не з'являються, помилки автентифікації.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":545,"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":"uk","translated":true,"requested_lang":"uk","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? (без кінцевих ком, без коментарів)\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** — вставте конфігурацію у <https://jsonlint.com>\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 змінна середовища має бути в конфігурації 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` або завантажте з <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>\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. **Перевірте корпоративний фаєрвол** — може блокувати вихідний HTTPS\n3. **Спробуйте альтернативний URL**:\n   - Production: `https://synapse.schaefer.zone`\n   - MCP-сервер: `https://synapse-mcp.schaefer.zone`\n4. **Для самостійно розгорнутих**: переконайтеся, що ваш екземпляр 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 (використовується автентифікація через заголовок, без обмеження частоти). Якщо все ж трапилось:\n\n1. **Перевірте, чи використовуєте `?key=` десь** — перейдіть на автентифікацію через заголовок\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**: <https://gitlab.com/schaefer-services/synapse-mcp/-/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":"<h1>Вирішення проблем MCP</h1>\n<p>Типові проблеми та рішення під час інтеграції Synapse MCP із вашим LLM-клієнтом.</p>\n<h2>Швидкий діагностичний чек-лист</h2>\n<ol>\n<li>✅ Node.js 18+ встановлено? (<code>node --version</code>)</li>\n<li>✅ Mind Key починається з <code>mk_</code>? (не JWT <code>eyJ...</code>)</li>\n<li>✅ Synapse API доступний? (<code>curl https://synapse.schaefer.zone/health</code>)</li>\n<li>✅ Mind Key працює? (<code>curl -H &quot;Authorization: Bearer mk_...&quot; .../memory/recall</code>)</li>\n<li>✅ Конфігураційний файл є коректним JSON? (без кінцевих ком, без коментарів)</li>\n<li>✅ Клієнт перезапущено після зміни конфігурації?</li>\n<li>✅ MCP-сервер запускається вручну? (<code>npx -y synapse-mcp-api@latest</code>)</li>\n</ol>\n<h2>Проблема: інструменти не з&#39;являються в клієнті</h2>\n<h3>Симптоми</h3>\n<ul>\n<li>Claude Desktop / Cursor / Continue показує 0 інструментів</li>\n<li>Немає значка 🔌 або запису «synapse» у списку MCP-серверів</li>\n</ul>\n<h3>Рішення</h3>\n<ol>\n<li><strong>Повністю перезапустіть клієнт</strong> — Cmd+Q на macOS (не просто закрийте вікно)</li>\n<li><strong>Перевірте розташування конфігураційного файлу</strong>:<ul>\n<li>Claude Desktop macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></li>\n<li>Claude Desktop Windows: <code>%APPDATA%\\Claude\\claude_desktop_config.json</code></li>\n<li>Cursor: <code>~/.cursor/config.json</code></li>\n<li>Continue: <code>~/.continue/config.json</code></li>\n</ul>\n</li>\n<li><strong>Валідуйте JSON</strong> — вставте конфігурацію у <a href=\"https://jsonlint.com\">https://jsonlint.com</a></li>\n<li><strong>Перевірте логи клієнта</strong> на помилки MCP:<ul>\n<li>Claude Desktop: <code>~/Library/Logs/Claude/mcp.log</code> (macOS)</li>\n<li>Cursor: View → Output → MCP</li>\n</ul>\n</li>\n<li><strong>Запустіть MCP-сервер вручну</strong>, щоб побачити помилки запуску:<pre><code class=\"hljs language-bash\">SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest</code></pre></li>\n</ol>\n<h2>Проблема: помилка «Mind Key invalid»</h2>\n<h3>Симптоми</h3>\n<ul>\n<li>Інструменти з&#39;являються, але виклики зазнають невдачі з «401 Unauthorized»</li>\n<li>Помилка: «Mind Key fehlt oder ungültig»</li>\n</ul>\n<h3>Рішення</h3>\n<ol>\n<li><strong>Перевірте формат Mind Key</strong> — починається з <code>mk_</code>, ~40 символів</li>\n<li><strong>Протестуйте безпосередньо</strong>:<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer mk_YOUR_KEY&quot;</span> \\\n     https://synapse.schaefer.zone/memory/recall</code></pre></li>\n<li><strong>Перевірте, що змінну середовища встановлено</strong> — для транспорту stdio змінна середовища має бути в конфігурації MCP-сервера, а не у вашій оболонці</li>\n<li><strong>Отримайте свіжий Mind Key</strong>:<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># Login to get JWT</span>\ncurl -X POST .../login -d <span class=\"hljs-string\">&#x27;{&quot;email&quot;:&quot;...&quot;,&quot;password&quot;:&quot;...&quot;}&#x27;</span>\n<span class=\"hljs-comment\"># Create new mind</span>\ncurl -X POST .../minds -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> -d <span class=\"hljs-string\">&#x27;{&quot;name&quot;:&quot;new mind&quot;}&#x27;</span></code></pre></li>\n</ol>\n<h2>Проблема: npx не знайдено</h2>\n<h3>Симптоми</h3>\n<ul>\n<li>Помилка: «npx: command not found»</li>\n<li>MCP-сервер не запускається</li>\n</ul>\n<h3>Рішення</h3>\n<ol>\n<li><strong>Встановіть Node.js 18+</strong>:<ul>\n<li>macOS: <code>brew install node</code> або завантажте з <a href=\"https://nodejs.org\">https://nodejs.org</a></li>\n<li>Linux: <code>curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - &amp;&amp; sudo apt install -y nodejs</code></li>\n<li>Windows: завантажте з <a href=\"https://nodejs.org\">https://nodejs.org</a></li>\n</ul>\n</li>\n<li><strong>Перезапустіть термінал</strong> після встановлення</li>\n<li><strong>Перевірте</strong>: <code>node --version &amp;&amp; npx --version</code></li>\n</ol>\n<h2>Проблема: SYNAPSE_URL недоступний</h2>\n<h3>Симптоми</h3>\n<ul>\n<li>MCP-сервер запускається, але виклики інструментів завершуються на тайм-ауті</li>\n<li>Помилка: «fetch failed» або «ECONNREFUSED»</li>\n</ul>\n<h3>Рішення</h3>\n<ol>\n<li><strong>Перевірте з&#39;єднання</strong>:<pre><code class=\"hljs language-bash\">curl https://synapse.schaefer.zone/health</code></pre></li>\n<li><strong>Перевірте корпоративний фаєрвол</strong> — може блокувати вихідний HTTPS</li>\n<li><strong>Спробуйте альтернативний URL</strong>:<ul>\n<li>Production: <code>https://synapse.schaefer.zone</code></li>\n<li>MCP-сервер: <code>https://synapse-mcp.schaefer.zone</code></li>\n</ul>\n</li>\n<li><strong>Для самостійно розгорнутих</strong>: переконайтеся, що ваш екземпляр Synapse працює та доступний</li>\n</ol>\n<h2>Проблема: MCP-сервер аварійно завершується</h2>\n<h3>Симптоми</h3>\n<ul>\n<li>MCP-сервер завершується одразу після запуску</li>\n<li>Логи клієнта показують «MCP server disconnected»</li>\n</ul>\n<h3>Рішення</h3>\n<ol>\n<li><strong>Запустіть вручну, щоб побачити помилку</strong>:<pre><code class=\"hljs language-bash\">SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest</code></pre></li>\n<li><strong>Перевірте конфлікти портів</strong> — MCP-сервер використовує порт 13100 за замовчуванням</li>\n<li><strong>Очистіть кеш npx</strong>:<pre><code class=\"hljs language-bash\">npx clear-npx-cache\n<span class=\"hljs-comment\"># or</span>\n<span class=\"hljs-built_in\">rm</span> -rf ~/.npm/_npx</code></pre></li>\n<li><strong>Оновіть до останньої версії</strong>:<pre><code class=\"hljs language-bash\">npx -y synapse-mcp-api@latest --version</code></pre></li>\n</ol>\n<h2>Проблема: виклики інструментів повертають 429</h2>\n<h3>Симптоми</h3>\n<ul>\n<li>Помилка: «Rate limit exceeded»</li>\n</ul>\n<h3>Рішення</h3>\n<p>Цього не повинно траплятися з MCP (використовується автентифікація через заголовок, без обмеження частоти). Якщо все ж трапилось:</p>\n<ol>\n<li><strong>Перевірте, чи використовуєте <code>?key=</code> десь</strong> — перейдіть на автентифікацію через заголовок</li>\n<li><strong>Перевірте <code>SYNAPSE_URL</code></strong> — упевніться, що він вказує на правильний екземпляр</li>\n<li><strong>Зверніться до підтримки</strong>, якщо проблема не зникає</li>\n</ol>\n<h2>Проблема: інструменти з&#39;являються, але не працюють</h2>\n<h3>Симптоми</h3>\n<ul>\n<li>Інструменти в списку клієнта</li>\n<li>Виклик інструменту повертає помилку або без результату</li>\n</ul>\n<h3>Рішення</h3>\n<ol>\n<li><strong>Перевірте назву інструменту</strong> — має бути точною (наприклад, <code>memory_recall</code>, а не <code>memory.recall</code>)</li>\n<li><strong>Перевірте аргументи</strong> — звірьте зі схемою вводу інструменту</li>\n<li><strong>Протестуйте через прямий API</strong>:<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/memory \\\n  -H <span class=\"hljs-string\">&quot;Authorization: Bearer mk_...&quot;</span> \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;category&quot;:&quot;fact&quot;,&quot;key&quot;:&quot;test&quot;,&quot;content&quot;:&quot;hello&quot;}&#x27;</span></code></pre></li>\n<li><strong>Перевірте стан Synapse</strong>:<pre><code class=\"hljs language-bash\">curl https://synapse.schaefer.zone/health</code></pre></li>\n</ol>\n<h2>Отримання допомоги</h2>\n<p>Якщо жодне з вищезазначеного не вирішило вашу проблему:</p>\n<ol>\n<li><strong>Перевірте наявні issues</strong>: <a href=\"https://gitlab.com/schaefer-services/synapse-mcp/-/issues\">https://gitlab.com/schaefer-services/synapse-mcp/-/issues</a></li>\n<li><strong>Відкрийте нове issue</strong> із:<ul>\n<li>Версією MCP-сервера (<code>npx -y synapse-mcp-api@latest --version</code>)</li>\n<li>Назвою та версією клієнта</li>\n<li>Операційною системою</li>\n<li>Відповідними уривками логів</li>\n<li>Кроками для відтворення</li>\n</ul>\n</li>\n</ol>\n<h2>Наступні кроки</h2>\n<ul>\n<li><a href=\"/docs/mcp/claude-desktop\">Налаштування Claude Desktop</a></li>\n<li><a href=\"/docs/mcp/claude-code\">Налаштування Claude Code</a></li>\n<li><a href=\"/docs/api/errors\">Помилки API</a></li>\n</ul>\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"]}