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

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

/mcp

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

يتيح MCP لـClaude Code التعامل مع أدوات وبيانات خارجية. إذا فشل الاتصال، لا تحدد السبب من الحالة وحدها: افحص طريقة الاتصال وتفاصيل الخطأ معًا. يشرح هذا المقال تشخيص التشغيل المحلي والاتصال والمصادقة عن بُعد والإعدادات والموافقة.

الخلاصة أولًا: (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 → /mcp OAuth
⏸ my-server pending → وافق عليه

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

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

مثلًا، قد يظهر الخطأ التالي في السجل. لا تستنتج من نصه وحده أن الخادم فشل في التشغيل؛ راجع أيضًا السجلات السابقة له.

MCP error -32000: Connection closed

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

لا تفترض أن الرسائل المتشابهة لها السبب نفسه. تختلف الأخطاء باختلاف العميل والإصدار والخادم. عند الاستعانة بشرح لأداة أخرى، تأكد من انطباقه على طريقة اتصالك وسجلاتك.

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

تستخدم خوادم 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يلزم تسجيل الدخول أو صلاحيات إضافية. افحص طريقة المصادقة المضبوطة أيضًامن /mcp نفّذ المصادقة ووافق في المتصفح
⏸ pending approvalخادم المشروع في .mcp.json بانتظار الموافقةوافق من /mcp. إذا رفضته بالخطأ: claude mcp reset-project-choices
✗ rejectedخادم مشروع ترفضه الإعداداتافحص disabledMcpjsonServers والسياسات الإدارية. استخدم reset-project-choices لإعادة ضبط اختيارات موافقتك

لا تميّز failed وحدها بين مشكلة تشغيل محلي ومشكلة اتصال بعيد. اقرأ رمز HTTP أو نص الخطأ في Issue: ضمن claude mcp get <name> أو تفاصيل /mcp. رفض ترويسة Authorization ثابتة برمز 401/403 أثناء الاتصال ينتج أيضًا failed. كذلك، وجود صفر أدوات ليس بالضرورة خطأ إذا كان الخادم يقدم resources أو prompts فقط. تأكد أولًا من أنه مصمم لتقديم أدوات. راجع تفاصيل الحالة الرسمية.

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

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

ROOT CAUSES

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

1) المسار / PATH
تُحلّ المسارات النسبية بالنسبة لدليل الإطلاق فتنحرف. استخدم مسارات مطلقة للنصوص البرمجية المحلية. وغياب الملف التنفيذي يُعطي spawn ... ENOENT.
2) عدم تمرير متغيرات البيئة
اضبط المتغيرات الخاصة بخادم stdio في env الخاص بذلك الخادم. ينطبق env في settings.json أيضًا على الجلسة والعمليات الفرعية، لذا افحص قيمه كذلك.
3) مهلة بدء التشغيل
خادم ثقيل يفشل في البدء في الوقت المتاح. ارفع MCP_TIMEOUT (بالمللي ثانية) عند الإطلاق، مثل 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 عادةً من دون ذلك الطلب. راجع التوثيق الرسمي لنطاق المشروع لشروط الرفض وغيرها. وترتبط بالموضوع أيضًا أساسيات MCP وA2A.

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

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

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

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

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

يتطلب WSL أيضًا Node والحزم ومتغيرات البيئة داخل Linux. الانتقال إلى WSL لا يضمن الحل. افحص البيئات التي يدعمها الخادم وإصدار Claude Code لديك أيضًا.

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 والعملية المطلوبة.
قد تبقى مشاكل توافق البروتوكول والصلاحيات وجلب قائمة الأدوات وأعطال العميل حتى بعد التشغيل.

ملاحظة: إضافة خوادم MCP كثيرة تجعل تعريفات الأدوات تستهلك السياق، خصوصًا مع التحميل الدائم. يقوم Claude Code افتراضيًا بـتأجيل تحميل التعريفات باستخدام البحث عن الأدوات، ما يقلل التأثير، لكن يُستحسن تعطيل الخوادم غير المستخدمة. وقد يؤدي امتلاء السياق إلى 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 الشائعة.

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

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

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

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

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

س. أعددت الخادم لكن لا أستطيع استخدامه.
ج. تأكد من أن ملف المشروع المشترك .mcp.json موجود في جذر المشروع، ثم افحص الصيغة والنطاق وحالة الموافقة. المتغير ${VAR} غير المعرّف ومن دون قيمة افتراضية يولد تحذيرًا ويبقى نصًا حرفيًا عند تحميل الإعدادات، ما قد يفشل التشغيل أو المصادقة. حدّد type أيضًا لإعدادات HTTP. إعادة الموافقة وحدها لا تحل إعدادات الرفض أو السياسات الإدارية.

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