# استكشاف أخطاء MCP
SUMMARY: حل مشكلات تكامل MCP الشائعة — الخادم لا يبدأ، الأدوات لا تظهر، أخطاء المصادقة.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

استكشاف أخطاء MCP
مشكلات وحلول شائعة عند دمج Synapse MCP مع عميل LLM الخاص بك.
قائمة تشخيص سريعة
1. ✅ Node.js 18+ مثبت؟ ()
2. ✅ Mind Key يبدأ بـ ؟ (وليس JWT )
3. ✅ Synapse API قابل للوصول؟ ()
4. ✅ Mind Key يعمل؟ ()
5. ✅ ملف الإعداد JSON صالح؟ (بلا فواصل لاحقة، بلا تعليقات)
6. ✅ العميل أُعيد تشغيله بعد تغيير الإعداد؟
7. ✅ خادم MCP يبدأ يدويًا؟ ()
المشكلة: لا تظهر أدوات في العميل
الأعراض
- Claude Desktop / Cursor / Continue يُظهر 0 أدوات
- لا أيقونة 🔌 أو إدخال "synapse" في قائمة خوادم MCP
الحلول
1. أعد تشغيل العميل بالكامل — Cmd+Q على macOS (ليس مجرد إغلاق النافذة)
2. تحقق من موقع ملف الإعداد:
   - Claude Desktop macOS: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. تحقق من صحة JSON — الصق الإعداد في <https://jsonlint.com>
4. تحقق من سجلات العميل لأخطاء MCP:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. شغّل خادم MCP يدويًا لرؤية أخطاء بدء التشغيل:
   [CODE BLOCK]
المشكلة: خطأ "Mind Key invalid"
الأعراض
- الأدوات تظهر لكن الاستدعاءات تفشل بـ "401 Unauthorized"
- الخطأ: "Mind Key fehlt oder ungültig"
الحلول
1. تحقق من تنسيق Mind Key — يبدأ بـ ، 40 حرفًا
2. اختبر مباشرة:
   [CODE BLOCK]
3. تحقق أن متغير البيئة مُعيين — لنقل stdio، يجب أن يكون متغير البيئة في
   إعداد خادم MCP، لا في shell الخاص بك
4. احصل على Mind Key جديد:
   [CODE BLOCK]
المشكلة: npx غير موجود
الأعراض
- الخطأ: "npx: command not found"
- خادم MCP يفشل في البدء
الحلول
1. ثبّت Node.js 18+:
   - macOS:  أو نزّل من <https://nodejs.org>
   - Linux: 
   - Windows: نزّل من <https://nodejs.org>
2. أعد تشغيل الـ terminal بعد التثبيت
3. تحقق: 
المشكلة: SYNAPSEURL غير قابل للوصول
الأعراض
- خادم MCP يبدأ لكن استدعاءات الأدوات تنتهي بالمهلة
- الخطأ: "fetch failed" أو "ECONNREFUSED"
الحلول
1. اختبر الاتصال:
   [CODE BLOCK]
2. تحقق من جدار حماية الشركة — قد يحظر HTTPS الصادر
3. جرّب عنوان URL بديلًا:
   - الإنتاج: 
   - خادم MCP: 
4. للاستضافة الذاتية: تأكد أن نسخة Synapse الخاصة بك تعمل وقابلة للوصول
المشكلة: خادم MCP ينهار
الأعراض
- خادم MCP يخرج فورًا بعد البدء
- سجلات العميل تُظهر "MCP server disconnected"
الحلول
1. شغّل يدويًا لرؤية الخطأ:
   [CODE BLOCK]
2. تحقق من تعارضات المنفذ — خادم MCP يستخدم المنفذ 13100 افتراضيًا
3. امسح ذاكرة npx المؤقتة:
   [CODE BLOCK]
4. حدّث إلى الأحدث:
   [CODE BLOCK]
المشكلة: استدعاءات الأدوات تُرجع 429
الأعراض
- الخطأ: "Rate limit exceeded"
الحلول
هذا لا ينبغي أن يحدث مع MCP (يستخدم مصادقة الترويسة، بلا حد معدل). إذا حدث:
1. تحقق إذا كنت تستخدم  في مكان ما — بدّل إلى مصادقة الترويسة
2. تحقق من  — تأكد أنه يشير إلى النسخة الصحيحة
3. تواصل مع الدعم إذا استمرت المشكلة
المشكلة: الأدوات تظهر لكن لا تعمل
الأعراض
- الأدوات مذكورة في العميل
- استدعاء أداة يُرجع خطأ أو بلا نتيجة
الحلول
1. تحقق من اسم الأداة — يجب أن يكون دقيقًا (مثلًا ، لا )
2. تحقق من المعاملات — تحقق من مخطط إدخال الأداة
3. اختبر عبر API مباشر:
   [CODE BLOCK]
4. تحقق من صحة Synapse:
   [CODE BLOCK]
الحصول على المساعدة
إذا لم يحل أي مما سبح مشكلتك:
1. تحقق من المشكلات الموجودة: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. افتح issue جديدًا مع:
   - إصدار خادم MCP ()
   - اسم العميل وإصداره
   - نظام التشغيل
   - مقتطفات السجلات ذات الصلة
   - خطوات إعادة الإنتاج
الخطوات التالية
- إعداد Claude Desktop
- إعداد Claude Code
- أخطاء الـ API