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

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

/mcp

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

يتيح MCP لـClaude Code التعامل مع أدوات وبيانات خارجية. وعند فشل الاتصال، قد يظهر في السجل سطر واحد هو MCP error -32000: Connection closed. يمكن حصر السبب بالجمع بين ثلاثة أمور: الحالة وطريقة الاتصال وتفاصيل الخطأ. يعزل هذا المقال بالترتيب التشغيل المحلي، ثم الاتصال والمصادقة عن بُعد، ثم الإعدادات والموافقة.

الخلاصة أولًا: (1) اقرأ الحالة والتفاصيل باستخدام /mcp وclaude mcp get <name>. (2) قد تظهر failed للخوادم المحلية والبعيدة على السواء. مع stdio افحص الأمر ومتغيرات البيئة؛ ومع HTTP افحص الرابط والشبكة واستجابة الخادم والمصادقة. (3) إذا لم يتضح السبب، اجمع سجلات الاتصال باستخدام claude --debug=mcp. لا تعدّل إلا ما يطابق الخطأ الفعلي، ثم أعد الاتصال للتحقق من النتيجة.

CLAUDE CODE · MCP STATUS

حدّد السبب من الحالة والتفاصيل

— مع failed احصر السبب بطريقة الاتصال وتفاصيل الخطأ

$ /mcp
✓ filesystem connected · 12 tools
✗ github failed ← اقرأ Issue:
△ notion needs auth ← أكمل المصادقة
⏸ my-server pending approval ← وافق عليه

✗ failed = فشل الاتصال، △ needs auth = تلزم المصادقة، ⏸ pending approval = بانتظار الموافقة.
احصر سبب failed بطريقة الاتصال وتفاصيل Issue:.

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

عندما يُغلق الاتصال، يظهر في السجل السطر التالي.

MCP error -32000: Connection closed

يشير MCP error -32000: Connection closed إلى أن اتصال MCP أُغلق. يخصص SDK الخاص بـMCP بلغة TypeScript الرمز -32000 لـConnectionClosed، ويعرض هذا النص عند إغلاق الاتصال (المرجع: معالجة إغلاق الاتصال في SDK). لا يخبرك هذا السطر إلا بالنتيجة، أي أن الاتصال أُغلق؛ أما سبب الإغلاق فتجده في السجلات التي تسبقه. هناك تميّز هل انتهت عملية الخادم قبل التهيئة أم انقطع التواصل بعد الاتصال.

قد ينقطع الاتصال حتى مع صحة الإعدادات. Issue #20713 بلاغ من مستخدم انقطع اتصاله أثناء التهيئة في Claude Code 2.1.19 على macOS. أما «حالة التسابق» بوصفها سببًا فهي تقدير صاحب البلاغ، وقد أُغلقت هذه المسألة في أبريل 2026 بحالة not planned. وعند الإبلاغ بنفسك، أرفق نظام التشغيل والإصدار وطريقة الاتصال وسجلات حُذفت منها المعلومات السرية.

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

مع الخوادم المحلية عبر stdio، تحدث أعطال مثل غياب الأمر أو المتغيرات اللازمة، أو انتهاء الخادم فورًا، أو اختلاط السجلات بـstdout. ومع الخوادم البعيدة عبر HTTP، تكون الأسباب الرابط الخاطئ والشبكة واستجابات 5xx والمهلات والمصادقة. أما أخطاء مكان ملف الإعدادات وصيغته ونطاقه فتحدث في النوعين.

ابدأ بـتسجيل الحالة وتفاصيل الخطأ وتحديد ما إذا كان الاتصال stdio أم HTTP. تغيير عدة إعدادات دفعة واحدة يصعّب معرفة التغيير المؤثر. استخدم الجدول التالي نقطة بداية وافحص كل سبب مناسب على حدة.

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

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

الحالةالمعنىأين تنظر أولاً
✓ connectedتم الاتصال. يظهر عدد الأدوات بجانبهإذا كانت الأدوات متوقعة لكن عددها 0، افحص الوظائف المتاحة والصلاحيات والسجلات
✗ failedفشل الاتصال بخادم محلي أو بعيدتفاصيل Issue: وطريقة الاتصال. مع HTTP انظر أيضًا في التواصل واستجابة الخادم وترويسات المصادقة الثابتة
△ needs authenticationيلزم تسجيل الدخول أو صلاحيات إضافيةمع OAuth، صادق عبر /mcp. مع headersHelper افحص مصدر بيانات الاعتماد، ومع الموصلات التي توفرها Anthropic افحص إعدادات الموصل في claude.ai
⏸ pending approvalخادم المشروع في .mcp.json بانتظار الموافقة. ويظهر في claude mcp list / get بصيغة ⏸ Pending approvalشغّل claude في الوضع التفاعلي ووافق عليه. إذا رفضته بالخطأ: claude mcp reset-project-choices
✗ rejectedخادم .mcp.json مُدرج في disabledMcpjsonServers في أحد ملفات الإعدادات. يظهر في claude mcp get <name> فقط بصيغة ✘ Rejected (see disabledMcpjsonServers in settings) (ولا يظهر في /mcp أو claude mcp list)الرفض في مربع حوار الموافقة يكتب هذا العنصر في .claude/settings.local.json. لإلغاء اختيارك استخدم reset-project-choices، وإذا كان العنصر في ملف إعدادات آخر فاحذفه منه

تظهر failed سواء فشل التشغيل المحلي أو فشل الاتصال البعيد. والدليل للتمييز هو التفاصيل: في claude mcp list تظهر في نهاية سطر ✘ Failed to connect، وفي claude mcp get <name> وشاشة تفاصيل /mcp تظهر في سطر Issue:، وتشمل رمز حالة HTTP أو رمز الخطأ ونص الخطأ الذي أعاده الخادم. وإذا رُفضت ترويسة Authorization ثابتة برمز 401/403 أثناء الاتصال، فالحالة أيضًا failed.

إذا انقطع خادم بعيد في منتصف الجلسة، يحاول Claude Code إعادة الاتصال تلقائيًا، ويعرض /mcp الحالة pending طوال ذلك (وهو معنى مختلف عن انتظار الموافقة). وإذا فشلت المحاولات الخمس وصارت الحالة failed، يظهر الإشعار MCP server "<name>" disconnected · open /mcp to reconnect (وإذا لزمت إعادة المصادقة فتصبح الحالة needs authentication). أما خوادم stdio فلا يُعاد اتصالها تلقائيًا، فأعد توصيلها يدويًا من /mcp. كذلك يضع /mcp علامة على الخوادم التي تعلن قدرة الأدوات ولا تعرض أي أداة. أما الخوادم التي تقدم resources أو prompts فقط، فعدد أدواتها 0 وهي سليمة. راجع تفاصيل الحالة الرسمية.

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

تساعد هذه الفحوص في تشخيص فشل الاتصال وعدم تطابق الإعدادات. ابدأ بما يناسب طريقة اتصالك.

ROOT CAUSES

فحوص بحسب طريقة الاتصال

1) المسار / PATH
تُحلّ المسارات النسبية بالنسبة لدليل الإطلاق فتنحرف. استخدم مسارات مطلقة للنصوص البرمجية المحلية. وغياب الملف التنفيذي يُعطي spawn ... ENOENT.
2) عدم تمرير متغيرات البيئة
اضبط المتغيرات الخاصة بخادم stdio في env الخاص بذلك الخادم. ينطبق env في settings.json أيضًا على الجلسة والعمليات الفرعية، لذا تسري قيمه كذلك.
3) مهلة بدء التشغيل
إذا أكدت السجلات انتهاء مهلة البدء، عدّل MCP_TIMEOUT بالمللي ثانية. في Bash: MCP_TIMEOUT=10000 claude. في PowerShell اضبط $env:MCP_TIMEOUT='10000' ثم شغّل claude.
4) موقع الإعداد / JSON
يوضع .mcp.json الخاص بالمشروع في جذر المشروع، لا داخل .claude/ أو settings.json. المتغير ${VAR} غير المعرّف ومن دون قيمة افتراضية يولد تحذيرًا ويبقى نصًا حرفيًا.
5) تلويث stdout
إذا كان خادم stdio يكتب السجلات إلى stdout فإنه يفسد البروتوكول. وجّه السجلات إلى stderr.
6) المصادقة عن بُعد
إذا لزم تسجيل الدخول عبر OAuth، صادق من /mcp. انتبه إلى أن رفض ترويسة مصادقة ثابتة يظهر بحالة failed.

محليًا افحص الأمر ومتغيرات البيئة والسجلات.
وعن بُعد افحص الرابط والتواصل واستجابة الخادم والمصادقة واتبع الخطأ الفعلي.

يمكن مشاركة .mcp.json الخاص بالمشروع، لكن لا تُدرج القيم السرية مباشرة في الالتزامات. مثلًا، أشر إلى ${API_KEY} واضبط القيمة المطلوبة في كل بيئة. تتحول بعض أسماء المتغيرات المحمية، ومنها بيانات اعتماد Claude Code نفسه، إلى نصوص فارغة في الروابط والترويسات البعيدة (قواعد توسيع المتغيرات الرسمية). تطلب الجلسات التفاعلية الموافقة على خوادم المشروع، أما claude -p وSDK فيحملانها من دون ذلك الطلب. وإذا أردت ألا يُحمَّل خادم رغم ذلك، فأدرجه في disabledMcpjsonServers (التوثيق الرسمي لنطاق المشروع). ذو صلة: أساسيات MCP وA2A.

4. فحص تشغيل npx على Windows

إذا ظهر spawn npx ENOENT على Windows، فافحص الملف التنفيذي وPATH أولًا باستخدام where.exe npx. ثم جرّب هل يعمل Node/npm، وهل يمكن تشغيل الحزمة المحددة بمفردها. ووفق توثيق Node الرسمي، لا تعمل ملفات .cmd على Windows بمفردها، بل تُشغَّل عبر صدفة أو cmd.exe.

إذا كانت طريقة التشغيل هي السبب: جرّب cmd.exe /c

إذا كان الخلل في طريقة تشغيل ملف .cmd، يمكنك تجربة الصيغة التالية. استبدل اسم الحزمة بما تحدده تعليمات الخادم الرسمية:

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

إذا شغّلته عبر WSL، فجهّز Node والحزم ومتغيرات البيئة داخل Linux.

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

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

DIAGNOSE

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

1
استخدم /mcp وclaude mcp list / get لـفحص الحالة، واقرأ Issue: وطريقة الاتصال أيضًا.
2
استخدم claude --debug=mcp لفحص سجلات تهيئة MCP والاتصال. ومع stdio افحص stderr أيضًا.
3
مع stdio، جرّب التشغيل المستقل بالأمر والمتغيرات نفسها الموجودة في الإعدادات. ومع HTTP افحص الرابط ومسار الشبكة ورمز الاستجابة.
4
تحقّق من الخادم وحده بـ MCP Inspector (npx @modelcontextprotocol/inspector) — جرّب جلب قائمة الأدوات واستدعاءها في واجهة مستخدم.
5
أعد الاتصال بعد التغييرات وجرّب العملية المطلوبة. إذا استمر الفشل، أبلغ عن الإصدار وطريقة الاتصال وأرفق سجلات خالية من المعلومات السرية.

نجاح التشغيل المستقل يختلف عن نجاح اتصال MCP والعملية المطلوبة.
قد تبقى مشاكل توافق البروتوكول والصلاحيات وجلب قائمة الأدوات وأعطال العميل حتى بعد التشغيل.

ملاحظة: يقوم Claude Code افتراضيًا بـتحميل التعريفات عند الحاجة باستخدام البحث عن الأدوات، لذا يبقى أثر إضافة الخوادم على السياق محدودًا. لكن الخوادم التي حُدد لها alwaysLoad، والإعدادات التي يتعطل فيها البحث عن الأدوات، تحمّل التعريفات منذ البداية، لذا من الأسلم تعطيل الخوادم غير المستخدمة بالأمر /mcp disable <name>. وامتلاء السياق يؤدي إلى Prompt is too long.

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

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

(1) اكتب المسارات الفعلية لملفات stdio التنفيذية وسكربتاته. (2) ميّز متغيرات stdio عن ترويسات مصادقة HTTP، ولا تكتب الأسرار في الملفات المشتركة. (3) على Windows افحص where.exe npx وNode/npm؛ جرّب cmd.exe /c فقط إذا كانت طريقة التشغيل هي المشكلة. (4) ضع .mcp.json في جذر المشروع وافحص صيغة JSON والمتغيرات والموافقة. (5) أرسل سجلات stdio إلى stderr بدل stdout. (6) غيّر عنصرًا واحدًا كل مرة، ثم أعد الاتصال واختبر العملية المطلوبة.

الخلاصة

شخّص أخطاء اتصال MCP في Claude Code باستخدام الحالة وطريقة الاتصال وتفاصيل الخطأ معًا. لا تقتصر failed على فشل التشغيل المحلي؛ فقد تنتج عن فشل اتصال HTTP أو رفض ترويسة مصادقة ثابتة. تشير needs authentication إلى فحص المصادقة، وتشير pending approval إلى مراجعة الموافقة على خادم المشروع.

اتبع هذا الترتيب: اقرأ الحالة وIssue: ← افحص السجلات المناسبة لطريقة الاتصال ← اختبر التشغيل المستقل أو التواصل ← أعد الاتصال وتحقق من العملية. اختر فئة التصحيح باستخدام claude --debug=mcp. أضف --debug-file ./claude-mcp-debug.log لحفظ السجلات. احذف المعلومات السرية قبل مشاركتها. ذو صلة: ما هو MCP؟، الربح من خوادم MCP، أخطاء Claude Code الشائعة.

عندما يظهر السجل في تطبيق Codex لكن الإرسال وحده يفشل، فالمشكلة في حالة المحادثة لا في MCP، ونتناولها في خطأ thread not found في Codex: خطوات الفحص وحالة تعافٍ فعلية.

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

س. تظهر failed في /mcp. من أين أبدأ؟
ج. افحص طريقة الاتصال وIssue:. مع stdio افحص الأمر والمسار ومتغيرات البيئة وstderr؛ ومع HTTP فالمرشحون هم الرابط والشبكة واستجابة الخادم والمصادقة. وإذا رُفضت ترويسة Authorization ثابتة برمز 401/403 أثناء الاتصال، فالحالة أيضًا failed، ويظهر رمز حالة HTTP في Issue:.

س. يقول "needs authentication" والأدوات لا تعمل.
ج. يختلف الحل بحسب طريقة المصادقة. إذا كان الخادم يستخدم OAuth، صادق عبر /mcp. ومع headersHelper مخصّص، تظهر هذه الحالة إذا أعاد استدعاء أداة 401/403 ثم فشلت إعادة المحاولة بعد جلب بيانات الاعتماد مجددًا. إذا أعاد المساعد ترويسة Authorization، فلن ينتقل Claude Code إلى OAuth؛ أصلح مصدر بيانات الاعتماد والقيم التي يعيدها، ثم أعد الاتصال. أما الموصلات التي توفرها Anthropic، مثل Microsoft 365 وGmail وGoogle Calendar، فلا تدعم OAuth المحلي من Claude Code. إذا أضفتها عبر claude mcp add أو .mcp.json ثم سجّلت الدخول من /mcp، فسيظهر is Anthropic-hosted and doesn't support local OAuth؛ احذف ذلك التسجيل ثم وصّلها من إعدادات الموصلات في claude.ai. راجع الشرح الرسمي للمصادقة المخصّصة.

س. خادم npx لا يتصل على Windows.
ج. افحص where.exe npx وNode/npm، وجرّب تشغيل الحزمة نفسها بالوسائط نفسها. إذا كانت طريقة تشغيل ملف .cmd هي السبب، يمكنك استخدام cmd.exe /c npx .... وإذا شغّلته عبر WSL، فجهّز Node والحزم داخل Linux.

س. الحالة connected لكن عدد الأدوات 0.
ج. انظر أولًا هل الخادم مصمم لتقديم أدوات. إذا كان يقدم resources أو prompts فقط، فعدد الأدوات 0 وهو سليم. وإذا كان يعلن قدرة الأدوات لكن عددها 0، فسيضع /mcp علامة على ذلك الخادم؛ افحص الوظائف المتاحة والصلاحيات وإعدادات الخادم والسجلات، ثم أعد الاتصال. أرسل سجلات تشخيص stdio إلى stderr ولا تخلطها بتدفق stdout المخصص للبروتوكول.

س. أعددت الخادم لكن لا أستطيع استخدامه.
ج. تأكد من أن ملف المشروع المشترك .mcp.json موجود في جذر المشروع، ثم افحص الصيغة والنطاق وحالة الموافقة. المتغير ${VAR} غير المعرّف ومن دون قيمة افتراضية يولد تحذيرًا ويبقى نصًا حرفيًا عند تحميل الإعدادات، ما يؤدي إلى فشل التشغيل أو المصادقة. اكتب type أيضًا في إعدادات HTTP. وإذا أعاد claude mcp get <name> الحالة ✘ Rejected، فالخادم مُدرج في disabledMcpjsonServers في أحد ملفات الإعدادات، فلا تكتفِ بإعادة الموافقة بل احذف ذلك العنصر.

مراجع الإعدادات والأوامر: إعدادات env، مرجع CLI، مرجع اتصال MCP.