استكشاف مشكلات خوادم MCP في Cursor وإصلاحها

توسّع خوادم MCP نطاق Cursor بأدوات خارجية، لكنها عمليات مستقلة لها تبعياتها الخاصة، وعندما تسيء التصرف قد تكون الأعراض مربكة: خادم يظهر بالأحمر، أو قائمة أدوات لا تُحدَّث، أو زر قطع اتصال يبدو أنه لا يفعل شيئًا. يمنحك هذا الدليل طريقة منهجية لتشخيص مشكلات MCP في Cursor، من قائمة الفرز السريع عبر الإصلاحات المحددة لكل نمط فشل شائع، ويوضح لك كيفية التحقق من أي خادم خارج IDE حتى تعرف ما إذا كانت المشكلة في الخادم أم في اتصال Cursor به.

قائمة الفرز السريع

عندما يسيء خادم MCP التصرف، اعمل عبر هذا الجدول من الأعلى إلى الأسفل. تُحل معظم المشكلات في الصفوف الثلاثة الأولى.

العرَض	أول ما يجب فحصه	الإصلاح المعتاد
يظهر الخادم بالأحمر أو يفشل في البدء	شغّل أمر الخادم يدويًا في الطرفية	أصلح مسار الأمر أو وقت التشغيل المفقود أو متغيرات البيئة
أدوات مفقودة أو قديمة	هل حرّرت mcp.json دون إعادة التشغيل؟	أعد تشغيل Cursor أو أعد تحميل النافذة
زر قطع الاتصال لا يفعل شيئًا	هل العملية ميتة فعلاً؟	اقتل العملية يدويًا، ثم أعد الاتصال
أخطاء الخادم دون إعادة محاولة	Cursor لا يعيد المحاولة تلقائيًا بعد بعض الإخفاقات	بدّل الخادم إيقافًا وتشغيلاً، أو أعد التشغيل
تعلّق الطلبات ثم انتهاء المهلة	بدء الخادم أو وقت تشغيل الأداة بطيء جدًا	جهّز التبعيات مسبقًا، وارفع المهلة
أخطاء المصادقة	انتهت صلاحية الرمز أو متغير البيئة مفقود	حدّث الرمز، وأصلح البيئة

الخادم لا يبدأ

أكثر إخفاق MCP شيوعًا هو أبسطها: أمر Cursor الذي يستخدمه لبدء الخادم لا يعمل فعلاً. يُنشئ Cursor بالضبط الأمر الموجود في mcp.json، بالبيئة التي منحتها إياه، وإذا فشل ذلك لا يظهر الخادم أبدًا.

مسار أمر خاطئ

افحص الأمر تمامًا كما سيشغله Cursor. إذا كان mcp.json يقول command": "npx" لكن PATH داخل عملية Cursor لا يتضمن npx، فسيفشل الإنشاء. في Windows يكون هذا شائعًا بشكل خاص لأن تطبيقات واجهة المستخدم الرسومية ترث PATH مختلفًا عن طرفيتك.

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\projects"]
    }
  }
}

استخدام المسار المطلق للملف التنفيذي هو الإصلاح الموثوق في Windows. في macOS و Linux، يخبرك which npx بالمسار المطلق إذا لم يُعثَر على الأمر المجرد.

npx أو uvx مفقود

يأتي كثير من خوادم MCP كحزم npm أو Python وتُشغَّل عبر npx أو uvx. إذا لم يكن وقت التشغيل مثبتًا، فلا يستطيع الخادم البدء:

# Verify the runtimes exist
node --version    # Node 18+ for npx-based servers
npx --version
python --version
uvx --version     # install with: pip install uv

إذا كان uvx مفقودًا، ثبّته وأعد تشغيل طرفيتك و Cursor حتى يُلتقط PATH المحدّث.

متغيرات بيئة خاطئة

الخادم الذي يحتاج مفتاح API غالبًا ما يبدأ ثم يخرج فورًا، أو يبدأ ويعيد أخطاء في كل نداء أداة، عندما تكون بيئته خاطئة. اقرأ توثيق الخادم لمعرفة أسماء المتغيرات الدقيقة، وتذكر أن Cursor يمرّر فقط ما تسرده في كتلة env:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }
  }
}

الأدوات لا تُعاد تحميلها بعد تحرير mcp.json

تحرّر mcp.json وتحفظه وتفتح قائمة الأدوات فلا تجد الأدوات الجديدة. يُقرأ تكوين MCP عند بدء عملية الخادم، لذا لا تُعاد التعديلات تحميلها فورًا في كل الحالات.

1. احفظ الملف وتأكد من أنه JSON صالح. الفاصلة الزائدة في النهاية تجعل الملف كله غير قابل للتحليل وقد يفشل كل خادم.
2. أعد تشغيل Cursor بالكامل، أو أعد تحميل النافذة إذا كان إصدارك يوفر خيار إعادة التحميل في لوحة الأوامر.
3. افتح لوحة إعدادات MCP وتأكد من ظهور الخادم كمتصل.
4. ابدأ محادثة جديدة. قد تكون المحادثة القائمة قد خزّنت قائمة الأدوات القديمة مؤقتًا، لذا لا تظهر الأدوات الجديدة إلا في الجلسات الجديدة.

إعادة التشغيل تغلب التحديث

إذا لم يلتقط تبديل الخادم إيقافًا وتشغيلاً في لوحة MCP تغييراتك، فأعد تحميل النافذة بالكامل أو أعد تشغيل Cursor. يُقرأ mcp.json عند وقت الاتصال، وتستمر عملية قديمة في تقديم قائمة أدواتها الأصلية مهما قال الملف الآن.

مشكلات الاتصال وإعادة المحاولة

زر قطع الاتصال لا يفعل شيئًا

يوقف إجراء قطع الاتصال الجانب العميل لـ Cursor من الاتصال، لكن مع خوادم stdio قد تنجو العملية الفرعية الفعلية إذا لم تُغلق بشكل نظيف. النتيجة خادم لا يزال يبدو نصف حيّ ويرفض إعادة اتصال نظيفة. عندما يبدو الزر متجاهلاً:

# Find and kill a stubborn stdio MCP server process
# macOS / Linux:
ps aux | grep mcp
kill <PID>

# Windows PowerShell:
Get-Process | Where-Object { $_.ProcessName -like "*npx*" -or $_.ProcessName -like "*uvx*" }
Stop-Process -Id <PID> -Force

بعد اختفاء العملية، أعد الاتصال من لوحة MCP. يبدأ الاتصال التالي عملية جديدة بتكوينك الحالي.

لا إعادة محاولة بعد خطأ الخادم

إذا أعاد الخادم خطأً عند البدء أو أثناء التهيئة، فلا يواصل Cursor عمومًا إعادة المحاولة في الخلفية. يبقى الخادم في حالة فاشلة حتى تتدخل. خيارات إعادة التشغيل اليدوي، بترتيب تصاعدي للقوة:

1. بدّل الخادم إيقافًا وتشغيلاً في لوحة إعدادات MCP.
2. أعد تحميل نافذة Cursor حتى تُعاد اتصال جميع خوادم MCP.
3. أغلق Cursor بالكامل وأعد تشغيله.
4. إذا كانت العملية معلّقة، اقتلها كما هو موضح أعلاه ثم أعد الاتصال.

المهلات الزمنية على الخوادم البطيئة

الخوادم التي تنزّل تبعيات عند التشغيل الأول، أو الأدوات التي تستدعي واجهات API خارجية بطيئة، قد تتجاوز المهلة الافتراضية وتبلّغ عن فشل يبدو كخادم معطوب. الحالة الكلاسيكية هي خادم قائم على npx عند أول استدعاء، عندما يجلب npm الحزمة قبل أن يبدأ أي شيء:

# Pre-warm an npx-based server so the first real connection is fast
npx -y @modelcontextprotocol/server-github --help

بالنسبة للمهلات على مستوى المضيف، تحترم كثير من مضيفات MCP، بما في ذلك Cursor، متغيرات البيئة التقليدية للمهلة. تعيينها قبل تشغيل Cursor يمنح الخوادم البطيئة مساحة أكبر:

# macOS / Linux (add to your shell profile)
export MCP_TIMEOUT=30000        # server startup timeout in ms
export MCP_TOOL_TIMEOUT=120000  # individual tool call timeout in ms

إذا كان الخادم لا يزال بطيئًا جدًا، فاستضفه بشكل مختلف: شغّله كعملية محلية دائمة واتصل عبر SSE أو HTTP بدلاً من إنشائه في كل جلسة.

أنواع النقل: stdio مقابل SSE/HTTP

يدعم Cursor نمطي نقل MCP، وتختلف بينهما عدة خطوات استكشاف.

الجانب	stdio	SSE / HTTP
كيف يعمل	Cursor ينشئ العملية	يعمل الخادم بشكل منفصل، ويتصل Cursor بعنوان URL
مفاتيح التكوين	command، args، env	url (والترويسات حيث تُدعم)
الإخفاقات الشائعة	مسار أمر خاطئ، وقت تشغيل مفقود	عنوان URL خاطئ، ترويسات مصادقة، مشكلات CORS أو الشبكة
سلوك إعادة التشغيل	التبديل يعيد اتصال العملية	إعادة الاتصال تصل إلى نقطة نهاية بعيدة
تصحيح الأخطاء	شغّل الأمر يدويًا	استدعِ نقطة النهاية بـ curl، وافحص سجلات الخادم

{
  "mcpServers": {
    "local-stdio-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-http-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

بالنسبة لخوادم SSE و HTTP، تحقق من إمكانية الوصول إلى نقطة النهاية قبل المساس بـ Cursor إطلاقًا:

# A plain GET should return something, even if it is an auth error
curl -i https://mcp.example.com/sse

يعني 401 أو 403 أن النقل سليم ومشكلتك في المصادقة. ويعني انتهاء المهلة أو رفض الاتصال أن الخادم معطّل أو أن عنوان URL خاطئ.

متغيرات البيئة والأسرار

mcp.json الخاص بالمشروع مقابل العام

يقرأ Cursor تكوين MCP من مكانين:

• عام: ~/.cursor/mcp.json (في Windows: %USERPROFILE%\.cursor\mcp.json). ينطبق على كل مشروع. ضع الخوادم الشخصية هنا: رمز GitHub الخاص بك، ومتصفح قاعدة البيانات، وأدوات الكشط.
• المشروع: .cursor/mcp.json داخل المستودع. ينطبق فقط على ذلك المشروع ويُشارَك مع الزملاء عند الالتزام به. ضع الخوادم الخاصة بالمشروع هنا: MCP مخطط لقاعدة بيانات هذا المستودع، وتكامل أداة تصميم يستخدمه هذا الكود.

عندما يُعرَّف خادم في المكانين، توقّع أن يحكم تكوين المشروع ذلك المشروع. إذا تكررت الأدوات أو اختفت، فافحص الملفين بحثًا عن إدخال بالاسم نفسه.

تمرير الأسرار بأمان

يوسّع Cursor العناصر النائبة ${VAR_NAME} في كتلة env من بيئتك، لذا يمكن أن تبقى الأسرار خارج mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${MY_DATABASE_URL}"
      }
    }
  }
}

# Set the real value in your shell profile, not in the JSON file
export MY_DATABASE_URL="postgresql://user:password@localhost:5432/appdb"

لا تلتزم بالأسرار في المستودع

ملف .cursor/mcp.json على مستوى المشروع ملف عادي في مستودعك. إذا احتوى على مفتاح API حرفي، فكل شخص وكل وكيل يستنسخ المستودع يحصل على المفتاح. استخدم توسيع ${VAR} لأي شيء حساس، وأضف mcp.json الخاص بالمشروع إلى .gitignore إذا كان لا بد أن يحتوي على قيم محلية.

قراءة سجلات MCP

عندما يكون العرَض غير واضح، تسمّي السجلات عادةً المشكلة الحقيقية. يعرض Cursor نشاط MCP عبر بنيته التحتية للإخراج:

1. افتح لوحة الأوامر وشغّل الأمر لإظهار لوحة الإخراج، أو استخدم قائمة View.
2. في قائمة القنوات المنسدلة في لوحة الإخراج، اختر قناة سجلات MCP أو Cursor MCP.
3. شغّل الإجراء الفاشل، ثم اقرأ أحدث الإدخالات. ابحث عن أخطاء الإنشاء، ورموز الخروج غير الصفرية، وتتبعات المكدس من stderr الخادم.

أسطر سجل نموذجية وما تعنيه:

[MCP] spawn npx ENOENT                 -> the runtime was not found on PATH
[MCP] server exited with code 1        -> the server crashed; run it manually for the real error
[MCP] initialize timed out             -> slow startup; pre-warm or raise the timeout
[MCP] tool call rejected: invalid args -> the model sent a bad schema; check the tool input

يُمرَّر stderr من جانب الخادم إلى هذه السجلات، لذا يظهر تتبع Python أو استثناء تبعية مفقودة من الخادم نفسه عادةً هنا حرفيًا.

التحقق من خادم بشكل مستقل

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

شغّل الأمر يدويًا

انسخ command و args من mcp.json وشغّلهما في طرفية عادية:

# Whatever your mcp.json launches, launch it yourself
npx -y @modelcontextprotocol/server-filesystem /tmp

خادم stdio MCP السليم يبدأ وينتظر بصمت إدخال JSON-RPC على stdin. إذا رأيت بدلاً من ذلك خطأ "الأمر غير موجود"، أو انهيارًا، أو فشل تثبيت حزمة، فقد وجدت المشكلة و Cursor بريء. اكتب بضعة أحرف واضغط Enter؛ استجابة خطأ بروتوكول مجردة هي في الواقع علامة جيدة، لأنها تثبت أن العملية تتحدث JSON-RPC.

استخدم MCP inspector

يتصل MCP inspector الرسمي بخادم، ويسرد أدواته، ويتيح لك استدعاءها تفاعليًا:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

يفتح هذا واجهة ويب محلية يمكنك فيها تهيئة الخادم، وسرد الأدوات، واستدعاء واحدة منها بوسائط مكتوبة يدويًا. إذا عملت أداة في inspector لكن ليس في Cursor، فالفارق عادةً هو البيئة: متغيرات موجودة في طرفيتك لكن مفقودة في عملية Cursor، أو دليل عمل مختلف. إذا فشلت الأداة في inspector أيضًا، فأصلح الخادم أولاً؛ لن يفيد أي شيء تغيّره في Cursor.

mcp.json أدنى عامل

استخدم هذا كمرجع عندما ينحرف تكوينك إلى شيء لم يعد يبدأ. يعرض خادم stdio واحدًا وخادمًا بعيدًا واحدًا، مع توسيع env:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "remote-search": {
      "url": "https://mcp.example.com/sse",
      "env": {
        "API_TOKEN": "${MY_MCP_TOKEN}"
      }
    }
  }
}

قائمة تحقق لتكييفه مع خادمك:

1. استبدل اسم الحزمة والوسائط بتلك الموجودة في توثيق الخادم.
2. استخدم مسارات تنفيذية مطلقة في Windows إذا لم يُعثَر على الأمر المجرد.
3. أبقِ الأسرار كعناصر نائبة ${VAR} وعيّن القيم الحقيقية في ملف تعريف shell لديك.
4. تحقق من صحة JSON، ثم أعد تشغيل Cursor وتأكد من ظهور الخادم كمتصل قبل فتح محادثة.

إدخال خاطئ واحد قد يعطّل الملف كله

يُحلَّل mcp.json كمستند JSON واحد. فاصلة زائدة واحدة في النهاية أو قيمة بلا علامات اقتباس تجعل الملف كله غير صالح، وقد يفشل كل خادم فيه معًا في البدء، بما في ذلك التي كانت تعمل جيدًا. إذا تعطلت عدة خوادم دفعة واحدة، فاشتبه في صحة الملف قبل الشك في كل خادم.

مرجع سريع

الهدف	افعل هذا
الخادم بالأحمر بعد البدء	شغّل الأمر يدويًا؛ أصلح المسار أو وقت التشغيل أو env
أدوات جديدة لا تظهر	أعد تحميل النافذة، ثم ابدأ محادثة جديدة
قطع الاتصال لا يستجيب	اقتل العملية الفرعية، ثم أعد الاتصال
إخفاقات متكررة دون إعادة محاولة	بدّل الخادم إيقافًا وتشغيلاً، أو أعد تشغيل Cursor
مهلة التشغيل الأول	جهّز الحزمة مسبقًا، وارفع متغيرات بيئة المهلة
تشتبه في الخادم لا في Cursor	تحقق بتشغيل يدوي أو بـ MCP inspector
تشتبه في Cursor لا في الخادم	قارن بيئتك مع طرفية واقرأ قناة سجلات MCP