{"title":"استكشاف أخطاء MCP","slug":"troubleshooting","category":"mcp","summary":"حل مشكلات تكامل MCP الشائعة — الخادم لا يبدأ، الأدوات لا تظهر، أخطاء المصادقة.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":571,"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":"ar","translated":true,"requested_lang":"ar","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** — الصق الإعداد في \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، لا في shell الخاص بك\n4. **احصل على Mind Key جديد**:\n ```bash\n # سجل الدخول للحصول على JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # أنشئ عقلًا جديدًا\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. **أعد تشغيل الـ terminal** بعد التثبيت\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 - الإنتاج: `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 # أو\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. **تحقق من المشكلات الموجودة**: \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 صالح؟ (بلا فواصل لاحقة، بلا تعليقات)
    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، لا في shell الخاص بك
    4. \n
  4. احصل على Mind Key جديد:
    # سجل الدخول للحصول على JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# أنشئ عقلًا جديدًا\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. أعد تشغيل الـ terminal بعد التثبيت
    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. تحقق من جدار حماية الشركة — قد يحظر HTTPS الصادر
    3. \n
  3. جرّب عنوان URL بديلًا:
      \n
    • الإنتاج: https://synapse.schaefer.zone
      • \n
    • خادم MCP: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  4. للاستضافة الذاتية: تأكد أن نسخة 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# أو\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 (يستخدم مصادقة الترويسة، بلا حد معدل). إذا حدث:

\n
    \n
  1. تحقق إذا كنت تستخدم ?key= في مكان ما — بدّل إلى مصادقة الترويسة
    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. تحقق من المشكلات الموجودة: 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"]}