جدول المحتويات

أعددتَ خادم MCP (Model Context Protocol)، لكن عند فتح /mcp وجدته عالقاً في حالة كهذه — هل يبدو هذا مألوفاً؟

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

يمنح MCP لـ Claude Code "أيدي" — أدوات خارجية (عمليات الملفات وGitHub وقواعد البيانات وواجهات API المتنوعة) — لكن اتصالاته تتعثر أكثر مما قد تتوقع. تنقسم الأسباب إلى ثلاث عائلات: "فشل إطلاق العملية الفرعية المحلية" و"المصادقة عن بُعد" و"أخطاء ملف الإعدادات"، وحالة /mcp تخبرك أيّها هو. يعرض هذا المقال كيفية قراءة الحالة، والحلول بحسب كل سبب، وأبرز فخاخ Windows، وسير عمل التشخيص — استناداً إلى المعلومات الرسمية.

النقاط الأساسية أولاً. (1) انظر إلى الحالة بـ /mcp (وclaude mcp list) أولاً — فحالات failed (فشل الإطلاق) وneeds authentication (المصادقة) وpending approval (انتظار الموافقة) تحتاج جميعها حلولاً مختلفة تماماً. (2) في المحلي (stdio) الجناة المعتادون هم المسارات ومتغيرات البيئة، إضافة إلى مشكلة npx على Windows. (3) في البعيد (HTTP) الجاني المعتاد هو OAuth. (4) عند التعثر، شغّل claude --debug mcp لرؤية مخرجات الخطأ من الخادم (stderr). تتغير السلوكيات والقيم الافتراضية حسب الإصدار، لذا تحقق من الوثائق الرسمية الأحدث.

CLAUDE CODE · MCP STATUS

الحالة تدلّك على الحل

— failed / needs auth / pending لكلٍّ منها علاج مختلف

$ /mcp
✓ filesystem connected · 12 tools
✗ github failed → الإطلاق · المسار · npx
△ notion needs auth → /mcp OAuth
⏸ my-server pending → وافق عليه

✗ failed = مشكلة إطلاق محلي، △ needs auth = مصادقة عن بُعد، ⏸ pending = انتظار الموافقة.
لا تَجمع "لا يتصل" في سلّة واحدة — صنّف حسب الحالة أولاً؛ فهذا أقصر طريق.

1. ما الذي يخبرك به هذا الخطأ

تأتي خوادم MCP في نوعَي اتصال رئيسيين. (1) stdio (محلي) — يُطلق Claude Code أمر الخادم كعملية فرعية على جهازك ويتحدث عبر الإدخال/الإخراج القياسي. (2) HTTP (بعيد) — يتصل بخادم سحابي عبر عنوان URL (أما SSE الأقدم فأصبح مهملاً). معنى "لا يتصل" يعتمد بشدة على النوع.

إن فشل المحلي (stdio) يكون دائماً تقريباً "فشل الأمر نفسه في الإطلاق" — مسار خاطئ، أو عدم قدرة npx على التحلّل (خاصة على Windows)، أو تعطّل الخادم فوراً بسبب غياب متغير بيئة مطلوب. أما فشل البعيد (HTTP) فيكون عادةً "عدم إتمام OAuth" — يُرجع الخادم 401/403 ويُظهر needs authentication. وحين لا يكون أياً منهما، لكن الإعداد بلا أثر، اشتبه في موقع ملف الإعدادات، أو خطأ مطبعي في JSON، أو موافقة المشروع.

لذا فإن الخطوة الأولى هي "افتح /mcp، واقرأ الحالة، وحدّد أيّ العائلات الثلاث هي." أما معاملة كل خطأ كـ "لا يتصل" عام والعبث عشوائياً فهو الطريق الأطول. يتناول القسم التالي كيفية قراءة الحالة.

2. اقرأ الحالة بـ /mcp أولاً

شغّل /mcp داخل الجلسة (أو claude mcp list / claude mcp get <name> من الصدفة) لرؤية حالة كل خادم. أبرز الحالات ومعانيها:

الحالةالمعنىأين تنظر أولاً
✓ connectedمتصل. يظهر عدد الأدوات بجانبهإن كان عدد الأدوات 0: "متصل لكن بلا أدوات" → أعد الاتصال / صحّح الأخطاء
✗ failedفشل في الإطلاق، أو استنفد المحاولاتإطلاق محلي = الأمر، المسار، npx، متغيرات البيئة (§3، §4)
△ needs authenticationأرجع البعيد 401/403. لم يُنجَز OAuthنفّذ المصادقة من /mcp (وافق في المتصفح)
⏸ pending approvalانتظار موافقة على خادم .mcp.json خاص بالمشروعوافق في /mcp. إن رفضته خطأً: claude mcp reset-project-choices
✗ rejectedخادم مشروع رفضته سابقاًالمثل (reset-project-choices لإعادة الموافقة)

الفكرة: "failed = مشكلة إطلاق، needs authentication = مصادقة، pending = موافقة" — فالحالة تحدّد خطوتك على نحو فريد. ومن الحالات التي تُغفَل كثيراً "متصل لكن 0 أدوات" — أي أن الخادم بدأ لكنه لا يُرجع قائمة أدوات؛ انتقل إلى إعادة الاتصال أو افحص السجلات بـ claude --debug mcp.

3. الأسباب الرئيسية للفشل وحلولها

إليك الأسباب التمثيلية لـ failed (فشل الإطلاق المحلي) ومشكلات الإعداد، مقرونةً بحلولها.

ROOT CAUSES

أبرز محرّكات مشكلات failed / الإعداد

1) المسار / PATH
تُحلّ المسارات النسبية بالنسبة لدليل الإطلاق فتنحرف. استخدم مسارات مطلقة للنصوص البرمجية المحلية. وغياب الملف التنفيذي يُعطي spawn ... ENOENT.
2) عدم تمرير متغيرات البيئة
توضع مفاتيح API الخاصة بالخادم في env لكل خادم (في .mcp.json أو --env). env في settings.json لا يصل إلى MCP.
3) مهلة بدء التشغيل
خادم ثقيل يفشل في البدء في الوقت المتاح. ارفع MCP_TIMEOUT (بالمللي ثانية) عند الإطلاق، مثل MCP_TIMEOUT=10000 claude.
4) موقع الإعداد / JSON
يوضع .mcp.json الخاص بالمشروع في جذر المستودع (لا تحت .claude/، ولا داخل settings.json). و${VAR} غير المعرّف يجعل تحليل الإعداد يفشل.
5) تلويث stdout
خادم stdio يكتب السجلات إلى stdout يُفسد البروتوكول (متصل لكن 0 أدوات، إلخ). أرسِل السجلات إلى stderr.
6) المصادقة عن بُعد
401/403 = needs authentication. OAuth من /mcp. ملاحظة: رفض ترويسة مصادقة ثابتة يُبلَّغ عنه كـ failed.

للمحلي، افحص بالترتيب: 1) المسار → 2) متغيرات البيئة → 4) موقع الإعداد.
للبعيد، 6) المصادقة هي كل شيء تقريباً. كما أن فخ Windows في القسم التالي شائع جداً أيضاً.

يمكن مشاركة .mcp.json الخاص بالمشروع عبر git، وهو يطلب الموافقة في المرة الأولى. فإن أغلقتَ ذلك الطلب سهواً، يبقى الخادم معطلاً (pending/rejected). شغّل claude mcp reset-project-choices لإعادة الموافقة. اقرن هذا بـ أساسيات MCP والتواصل بين الوكلاء A2A للحصول على الصورة الكاملة للاتصال.

4. حين يفشل على Windows (أبرز الفخاخ)

على Windows الأصلي، يُعدّ فشل خوادم MCP المبنية على npx في الاتصال مع spawn npx ENOENT / Failed to connect أمراً شائعاً للغاية. السبب: npx على Windows هو في الواقع غلاف دُفعي (npx.cmd)، وآلية إطلاق العملية في Node لا تستطيع تحليل ملف .cmd مباشرة.

الحل: لُفّه بـ cmd /c

اجعل command هو cmd بدلاً من npx مباشرة، ومرّر /c npx ... كوسائط:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

أو شغّله تحت WSL، فهو موثوق. وإن أظهر where npx مساراً ومع ذلك يفشل، فاشتبه في مشكلة .cmd هذه أولاً. وقد تُصلَح بعض الحالات الخاصة بإصدار معين في إصدارات لاحقة، لذا جرّب أيضاً التحديث إلى أحدث إصدار.

5. سير عمل التشخيص

حين يكون السبب غير واضح، اعمل من الأعلى إلى الأسفل. الحيلة هي التأكد من أن الخادم يعمل مستقلاً قبل لوم Claude Code.

DIAGNOSE

اعزله من الأعلى إلى الأسفل

1
/mcp وclaude mcp list / get لـ فحص الحالة (failed مقابل auth مقابل pending).
2
claude --debug mcp لقراءة stderr (مخرجات الخطأ) من الخادم. سبب التعطّل يكون عادةً هنا تماماً.
3
أطلق الخادم مستقلاً (هل يعمل npx ... في الصدفة نفسها؟). إن لم يعمل، فهي مشكلة سابقة لـ Claude Code.
4
تحقّق من الخادم وحده بـ MCP Inspector (npx @modelcontextprotocol/inspector) — افحص قائمة أدواته واستدعِ الأدوات في واجهة مستخدم.
5
على Claude Desktop، أغلق التطبيق كلياً وأعد فتحه بعد تغييرات الإعداد (إغلاق النافذة وحده لا يكفي). توجد السجلات في mcp*.log. كما يفحص /doctor أيضاً.

القاعدة: تأكّد من "هل يعمل الخادم مستقلاً؟" أولاً.
وبمجرد حسم ذلك، يتقلّص الباقي إلى الإعداد (المسار، env، الموقع) أو المصادقة.

ملاحظة: إضافة عدد كبير جداً من خوادم MCP تجعل تعريفات الأدوات تلتهم السياق (خاصة مع إعدادات التحميل الدائم). يؤجّل Claude Code تعريفات الأدوات عبر البحث عن الأدوات افتراضياً، فالأثر صغير، لكن يبقى من الحكمة تعطيل الخوادم التي لا تستخدمها. فإثقال السياق قد يُطلق حتى خطأ Prompt is too long.

6. قائمة التحقق للوقاية

عادات لتجنّب التعثّر في اتصالات MCP.

(1) حدّد النصوص البرمجية المحلية بـ مسارات مطلقة. (2) ضع مفاتيح الخادم في env الخاص بكل خادم (لا في settings.json). (3) على Windows، لُفّه بـ cmd /c npx ... (أو استخدم WSL). (4) أبقِ .mcp.json في جذر المستودع؛ وانتبه لصيغة JSON و${VAR} غير المعرّف. (5) يجب ألا تسجّل الخوادم إلى stdout (استخدم stderr). (6) بعد تغييرات الإعداد، أعد التحميل (أعد تشغيل Desktop كلياً؛ أعد الموافقة على خوادم المشروع). (7) عند التعثّر، اعزل بـ claude --debug mcp وإطلاق الخادم مستقلاً، وحدّث إلى أحدث إصدار عند الحاجة.

الخلاصة

بالنسبة إلى أخطاء اتصال خادم MCP في Claude Code، أقصر طريق هو التصنيف حسب حالة /mcp إلى ثلاث عائلات. ✗ failed مشكلة إطلاق محلي (المسار، متغيرات البيئة، المهلة، موقع الإعداد — وعلى Windows، لُفّ npx بـ cmd /c)، و△ needs authentication هو OAuth عن بُعد (صادِق من /mcp)، و⏸ pending approval خادم مشروع ينتظر الموافقة (وافق في /mcp؛ ويُصلَح الرفض الخاطئ بـ claude mcp reset-project-choices).

شخّص بالترتيب: (1) الحالة بـ /mcp ← (2) stderr بـ claude --debug mcp ← (3) الإطلاق المستقل ← (4) MCP Inspector ← (5) إعادة تشغيل Desktop كلياً. تأكّد من أن الخادم يعمل مستقلاً قبل لوم Claude Code، وعندها يتقلّص الباقي إلى الإعداد أو المصادقة. ثلاث عادات فقط — متغيرات البيئة في env الخاص بكل خادم، و.mcp.json في جذر المستودع، والسجلات إلى stderr — تقلّل الحوادث بشكل كبير. ذو صلة: ما هو MCP، تحقيق الدخل من خوادم MCP، مجموعة أخطاء Claude Code.

الأسئلة الشائعة

Q. يُظهر /mcp "failed". من أين أبدأ؟
A. failed غالباً فشل في إطلاق خادم محلي (stdio). افحص بالترتيب: (1) مسار الأمر/النص البرمجي (استخدم مسارات مطلقة)، و(2) متغيرات البيئة المطلوبة (ضعها في env الخاص بكل خادم)، و(3) على Windows، لُفّ بـ cmd /c npx .... إن بقي السبب غير واضح، اقرأ stderr من الخادم بـ claude --debug mcp، واختبر أولاً ما إذا كان الخادم يُطلَق مستقلاً في الصدفة نفسها.

Q. يقول "needs authentication" والأدوات لا تعمل.
A. هذا خادم بعيد (HTTP) يطلب المصادقة (401/403). افتح /mcp ونفّذ المصادقة لذلك الخادم؛ فيتقدّم إلى موافقة OAuth في المتصفح. وبمجرد إتمامها، تُخزَّن الرموز بأمان وتُحدَّث تلقائياً. لاحظ أن بعض الخدمات (Microsoft 365، Gmail، Google Calendar) لا تدعم المصادقة المحلية من Claude Code ويجب توصيلها عبر Settings → Connectors على claude.ai بدلاً من ذلك.

Q. على Windows خادم npx لديّ ببساطة لا يتصل.
A. npx على Windows هو في الواقع غلاف دُفعي (npx.cmd)، وكثيراً ما يفشل في الإطلاق مع spawn npx ENOENT. غيّر command إلى cmd وargs إلى ["/c","npx","-y","package-name"] للفّه. كما أن التشغيل تحت WSL موثوق أيضاً. وإن أظهر where npx مساراً ومع ذلك يفشل، فالأمر شبه مؤكد أنه مشكلة .cmd هذه. وقد يُصلَح في إصدارات أحدث، فجرّب التحديث أيضاً.

Q. الحالة "connected" لكنها تُظهر 0 أدوات.
A. الخادم أُطلق بنجاح لكنه لا يُرجع قائمة أدوات. سبب شائع هو خادم stdio يكتب السجلات إلى stdout فيُفسد البروتوكول — أرسِل السجلات دائماً إلى stderr. أولاً أعد الاتصال من /mcp؛ فإن لم يُصلِح ذلك المشكلة، افحص مخرجات الخادم بـ claude --debug mcp.

Q. أعددتُ خادماً لكنه لا يظهر في /mcp.
A. موقع ملف الإعداد هو السبب المرجّح. يوضع خادم المشروع المشترك في .mcp.json في جذر المستودع (لا يُقرأ تحت .claude/ أو داخل settings.json). كما أن ${VAR} غير المعرّف يجعل تحليل الإعداد يفشل أيضاً. وتحتاج خوادم المشروع إلى موافقة أولية؛ فإن أغلقتَ الطلب يبقى pending — أعِده بـ claude mcp reset-project-choices.