يدعم Claude بروتوكول سياق النموذج (MCP) بشكل أصلي، مما يتيح لك ربط الأدوات الخارجية — قواعد البيانات، مشغِّلات الأكواد، واجهات برمجة التطبيقات (API)، والخوادم المخصصة — مباشرة بسير عملك. سواء كنت تستخدم Claude Code في الطرفية أو سطح مكتب Claude على جهازك، فإن تكوين MCP يعمل بنفس الطريقة على مستوى البروتوكول، مع بعض الاختلافات في كيفية تسجيل الخوادم. يغطي هذا الدليل كلا المسارين: أوامر سطر الأوامر claude mcp add لـ Claude Code، وملف تكوين JSON لسطح مكتب Claude، بالإضافة إلى كيفية انسجام تفكير استخدام الأدوات وتنفيذ الحماية مع الصورة الكلية.
ما يفعله MCP في Claude
MCP هو معيار مفتوح من Anthropic يمنح نماذج اللغة طريقة موحدة لاستدعاء الأدوات الخارجية. قبل MCP، كان كل تطبيق ذكاء اصطناعي يحتاج إلى كود ربط خاص لكل أداة يريد استخدامها. مع MCP، يكشف أي خادم متوافق عن قدراته من خلال بروتوكول اكتشاف واستدعاء موحد، ويمكن لأي مضيف متوافق — بما في ذلك Claude — استخدامها دون عمل تكامل خاص بكل أداة.
من الناحية العملية: عندما تضيف خادم MCP إلى Claude، فأنت تخبر مضيف Claude أين يجد مجموعة من الأدوات. يمكن لـ Claude بعد ذلك سرد تلك الأدوات أثناء الجلسة واستدعاءها بالاسم عندما تستدعي المهمة ذلك. يتولى الخادم التنفيذ؛ ويتولى Claude التفكير في متى وكيف يستدعي.
هناك ثلاثة مفاهيم أساسية تدعم MCP:
| المفهوم | ما هو | مثال |
|---|---|---|
| أداة | دالة قابلة للاستدعاء يكشف عنها الخادم | run_python، query_db، list_models |
| مورد | بيانات للقراءة فقط يجعلها الخادم متاحة كسياق | ملف، صف في قاعدة بيانات، مجموعة بيانات |
| موجه | قوالب تعليمات مبنية مسبقًا مرفقة مع الخادم | وصف مهمة على مستوى النظام |
بالنسبة لمعظم المطورين، الأدوات هي الأكثر أهمية. تصبح الموارد والموجهات ذات صلة عندما تقوم ببناء خط أنابيب وكيل أكثر هيكلة.
إضافة خوادم MCP في Claude Code
يكشف Claude Code عن إدارة MCP من خلال مجموعة أوامر claude mcp الفرعية. يمكنك إضافة الخوادم وإزالتها وسردها دون لمس أي ملف تكوين يدويًا.
claude mcp add — الصيغة الأساسية
claude mcp add <name> <command> [args...]
على سبيل المثال، لإضافة خادم Python MCP محلي:
claude mcp add my-tools python /path/to/mcp_server.py
هذا يسجل خادمًا باسم my-tools يقوم بتشغيل python /path/to/mcp_server.py باستخدام نقل stdio. يقوم Claude Code بتشغيل العملية عند بدء الجلسة ويبقيها نشطة طوال المدة.
تمرير متغيرات البيئة
تحتاج العديد من خوادم MCP إلى مفاتيح API أو عناوين URL للنقاط الطرفية. استخدم --env لتمريرها وقت التسجيل:
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=your_key_here \
--env BASE_URL=https://api.example.com
تُخزَّن القيم في تكوين Claude Code وتُحقن في عملية الخادم عند بدء التشغيل. لا تقم بتضمين الأسرار مباشرة في أمر الخادم نفسه.
claude mcp add json — التسجيل من مواصفات JSON
إذا كانت لديك مواصفات خادم مكتوبة بالفعل بصيغة JSON (شائعة عند مشاركة التكوينات عبر فريق)، يمكنك توجيهها مباشرة:
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key"
}
}' | claude mcp add my-tools --json
أو تمرير ملف:
claude mcp add my-tools --json < server-spec.json
هذا يعادل الصيغة الموضعية ولكنه يمنحك قطعة تكوين واحدة يمكنك التحكم في نسخها ومشاركتها.
سرد الخوادم وإزالتها
# عرض جميع الخوادم المسجلة
claude mcp list
# إزالة خادم
claude mcp remove my-tools
النطاق: المشروع مقابل المستخدم
افتراضيًا، يسجل claude mcp add الخادم في تكوين المستخدم الخاص بك، مما يجعله متاحًا في كل جلسة Claude Code. لتسجيله للمشروع الحالي فقط (مخزن في .claude/settings.json)، أضف --scope project:
claude mcp add my-tools python /path/to/mcp_server.py --scope project
تُعد الخوادم ذات النطاق المشروعي مفيدة عندما تحتاج مشاريع مختلفة إلى أدوات مختلفة وتريد إبقاء التكوينات معزولة.
claude mcp serve — عرض Claude Code كخادم MCP
الاتجاه يعمل أيضًا بالعكس. claude mcp serve يشغل Claude Code نفسه كخادم MCP، مما يتيح لمضيف MCP آخر الاتصال به واستخدام أدواته:
claude mcp serve
هذا مفيد إذا كنت ترغب في دمج قدرات Claude Code في خط أنابيب وكيل أكبر حيث يقوم مضيف مختلف بتنسيق استدعاءات الأدوات.
تكوين خوادم MCP في سطح مكتب Claude
يخزن سطح مكتب Claude تكوين خادم MCP في ملف JSON. يعتمد الموقع على نظام التشغيل لديك:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
إذا كان الملف غير موجود، قم بإنشائه. يبدو الهيكل كما يلي:
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key_here"
}
}
}
}
كل مفتاح تحت mcpServers هو اسم الخادم الذي سيستخدمه Claude لتحديده. يمكنك تسجيل أي عدد تريده من الخوادم — يقوم سطح مكتب Claude بتحميلها جميعًا عند بدء التشغيل.
بعد تحرير الملف، أعد تشغيل سطح مكتب Claude حتى تدخل التغييرات حيز التنفيذ. سترى أيقونة مطرقة في منطقة إدخال الدردشة عندما يتم تحميل أدوات MCP بنجاح.
إضافة خادم MCP عن بُعد عبر SSE
بالنسبة للخوادم البعيدة التي تستخدم نقل أحداث الخادم (SSE) بدلاً من stdio، يكون شكل التكوين مختلفًا قليلاً:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse"
}
}
}
تتطلب بعض الخوادم البعيدة المصادقة. قم بتمرير رمز الحامل في حقل الرؤوس إذا كان الخادم يتوقعه:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse",
"headers": {
"Authorization": "Bearer your_token_here"
}
}
}
}
أنواع نقل MCP: stdio مقابل SSE
تتواصل خوادم MCP مع مضيف Claude عبر إحدى آليتي النقل:
stdio — يعمل الخادم كعملية فرعية على نفس الجهاز. يقوم المضيف بتشغيل العملية ويقرأ/يكتب رسائل JSON-RPC عبر الإدخال/الإخراج القياسي. هذا هو الإعداد الافتراضي للخوادم المحلية وهو الأسهل في الإعداد.
SSE (أحداث الخادم) — يعمل الخادم عن بُعد ويكشف عن نقطة نهاية HTTP. يتصل المضيف بعنوان URL ويتلقى استجابات الأداة كتيار. يعمل هذا عبر الأجهزة وهو الخيار المناسب للبنية التحتية المشتركة للفريق أو خدمات الأدوات المستضافة.
بالنسبة لمعظم المطورين الأفراد الذين بدأوا للتو، فإن stdio أسهل — لا حاجة للشبكات، ويتم إدارة عملية الخادم لك. يصبح SSE ذا قيمة عندما تريد أن يشارك فريق في خادم MCP واحد، أو عندما تحتاج الأداة نفسها إلى العمل في بيئة شبكة محددة.
كيف يفكر Claude في أدوات MCP
عندما تبدأ جلسة ويتم تسجيل خوادم MCP، يستعلم Claude كل خادم عن أدواته المتاحة. ينتج عن ذلك قائمة بأسماء الأدوات وأوصاف JSON Schema. لا يستدعي Claude الأدوات بشكل تخميني — إنه يستدعي الأداة فقط عندما تتطلبها المحادثة أو المهمة، بناءً على ما يقوله وصف الأداة أنها تفعله.
تسير عملية استدعاء الأداة على النحو التالي:
- يرسل المستخدم رسالة أو مهمة.
- يقيّم Claude ما إذا كانت أي أداة مسجلة يمكن أن تساعد.
- إذا كانت الإجابة بنعم، يقوم Claude ببناء استدعاء أداة مع الوسائط المناسبة.
- يرسل مضيف MCP الاستدعاء إلى الخادم الصحيح.
- ينفذ الخادم ويعيد النتيجة.
- يدمج Claude النتيجة في تفكيره ويواصل.
يمكن أن تحدث هذه الحلقة عدة مرات في جلسة واحدة — يمكن لـ Claude سلسلة استدعاءات الأدوات، واستخدام نتائج من أداة لتوجيه وسائط لأخرى، والتجميع عبر خوادم متعددة في نفس الجلسة.
جودة أوصاف الأدوات مهمة جدًا هنا. الأوصاف الغامضة تؤدي إلى استدعاءات مفقودة أو غير صحيحة. الأوصاف الدقيقة التي تتضمن ما تفعله الأداة، وما تعنيه وسائطها، وما ترجعه، تسمح لـ Claude بتوجيه الاستدعاءات بدقة دون تخمين.
تشغيل تنفيذ الأداة في صندوق حماية
عندما تنفذ أدوات MTP كودًا — نصوص Python، أوامر شل، عمليات ملفات — فإن تشغيلها على جهازك المحلي يثير تساؤلات حول العزل. الأداة التي لديها وصول إلى نظام الملفات، أو إنشاء عمليات، أو استدعاءات شبكة لها نطاق واسع إذا أساءت التصرف أو تم توجيهها إلى مسار غير متوقع.
يعالج صندوق حماية وكيل Novita AI هذه المشكلة من خلال توفير بيئات سحابية معزولة لتنفيذ الأدوات. بدلاً من تشغيل خادم MCP محليًا، تقوم بنشره داخل مثيل صندوق حماية. يحصل الصندوق على نظام ملفات خاص به، ونطاق شبكة، وحدود موارد. يمكن للوكيل كتابة الملفات وتشغيل الكود واستدعاء واجهات برمجة التطبيقات الداخلية داخل تلك الحدود دون لمس الجهاز المضيف.
يكشف خادم MCP الذي يعمل داخل صندوق الحماية عن أدواته من خلال نقل SSE، ويتصل Claude به عن بُعد — لذا من منظور Claude، التكامل متطابق. الفرق كله يكمن في ما تعمل عليه الأداة فعليًا.
الخصائص الرئيسية لـ Novita Sandbox لنشر MCP:
- بدء تشغيل سريع: يتم تشغيل المثيلات في أقل من ~200 مللي ثانية، مما يحافظ على انخفاض زمن استجابة الجولة للأداة
- فوترة بالثانية: تدفع فقط مقابل وقت التنفيذ النشط، وليس الحجز الخامل
- نظام ملفات معزول: كل مثيل صندوق حماية لديه مساحة عمل منفصلة، مما يمنع تسرب البيانات عبر الجلسات
- سياسة شبكة قابلة للتكوين: التحكم في الخدمات الخارجية التي يمكن للأداة الوصول إليها
للحصول على دليل خطوة بخطوة لبناء خادم MCP مدعوم بـ Novita Sandbox، راجع بناء خادم MCP لتنفيذ الأكواد عن بُعد باستخدام Novita Sandbox ومكتبة mcp-use.
استخدام واجهة برمجة تطبيقات Novita LLM لتفكير استخدام أدوات MCP
بينما تتعامل نماذج Claude نفسها مع استخدام الأدوات بشكل أصلي، قد ترغب في توجيه بعض تفكير استخدام أدوات MCP عبر نموذج مختلف — لأسباب تتعلق بالتكلفة أو زمن الاستجابة أو التخصص. توفر واجهة برمجة تطبيقات Novita LLM نقطة نهاية متوافقة مع OpenAI مع إمكانية الوصول إلى نماذج تدعم استدعاء الدوال واستدعاء الأدوات المنظم.
يندرج هذا في بنيات MCP بطريقتين:
1. كنموذج التفكير وراء مضيف MCP مخصص: إذا كنت تبني مضيف MCP الخاص بك (بدلاً من استخدام Claude Code أو سطح مكتب Claude)، يمكنك استخدام واجهة برمجة تطبيقات Novita LLM لتشغيل طبقة النموذج. يستدعي المضيف واجهة Novita API مع قائمة الأدوات والمحادثة؛ يعيد النموذج تعليمات استدعاء الأداة؛ يوزعها المضيف على خادم MCP.
import openai
client = openai.OpenAI(
base_url="https://api.novita.ai/v3/openai",
api_key="your_novita_api_key",
)
response = client.chat.completions.create(
model="meta-llama/llama-3.3-70b-instruct",
messages=[{"role": "user", "content": "اسرد الأدوات المتاحة وقم بتشغيل اختبار سريع"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "سرد جميع النماذج المتاحة من واجهة برمجة التطبيقات.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. كنموذج LLM داخل أداة MCP نفسها: يمكن لأداة MCP استخدام واجهة برمجة تطبيقات Novita LLM داخليًا — على سبيل المثال، أداة تلخيص، أداة تصنيف، أو أداة توليد كود. تستقبل الأداة مدخلات من الوكيل، تستدعي واجهة Novita API، وتعيد النتيجة. هذا يبقي تكاليف استدلال النموذج منفصلة عن تكاليف نموذج الوكيل الرئيسي ويتيح لك اختيار النموذج المناسب لكل مهمة فرعية.
للحصول على مثال عملي لبناء خادم MCP يستدعي واجهة Novita API، راجع كيفية بناء أول خادم MCP لك مع Novita AI.
المشكلات الشائعة والحلول
الخادم لا يظهر في سطح مكتب Claude
السبب الأكثر شيوعًا هو خطأ في بناء جملة JSON في claude_desktop_config.json. استخدم مدقق JSON قبل الحفظ. حتى الفاصلة الزائدة ستمنع تحميل الملف. أعد تشغيل سطح مكتب Claude بعد كل تعديل.
أمر claude mcp add غير موجود
هذا يعني أن Claude Code إما غير مثبت أو غير موجود في متغير PATH. قم بتثبيت Claude Code عبر npm install -g @anthropic-ai/claude-code وتحقق باستخدام claude --version.
الأدوات مدرجة ولكن لا يتم استدعاؤها أبدًا
يستدعي Claude الأداة فقط عندما يعتقد أنها ذات صلة بالمهمة الحالية. إذا كانت أوصاف أدواتك غامضة جدًا، فلن يختارها Claude. أضف تفاصيل: ما تفعله الأداة، ومتى تستخدمها، وكيف تبدو مدخلاتها ومخرجاتها.
الخادم يخرج فورًا بعد الإطلاق
تحقق من أن أمر الخادم صحيح وأن جميع متغيرات البيئة المطلوبة معينة. قم بتشغيل الأمر مباشرة في طرفية لرؤية مخرجات الخطأ الفعلية — قد يقوم Claude Code بقمع stderr للعملية الفرعية في بعض التهيئات.
رفض اتصال SSE
تحقق من أن عنوان URL للخادم يمكن الوصول إليه من الجهاز الذي يعمل عليه Claude، وأن الخادم يستمع فعليًا على المنفذ المتوقع، وأن أي رؤوس مصادقة مطلوبة تم تكوينها بشكل صحيح.
فشل استدعاءات الأداة مع أخطاء التحقق من الصحة
يجب أن تتطابق الوسائط التي يمررها Claude مع JSON Schema التي يعلنها الخادم. راجع تعريف inputSchema لأداتك — إذا كانت الحقول المطلوبة مفقودة أو الأنواع غير متطابقة، سيرفض الخادم الاستدعاء. يبني Claude الوسائط بناءً على المخطط، لذا يؤدي المخطط غير المكتمل إلى استدعاءات غير مكتملة.
الأسئلة الشائعة
هل يدعم Claude Code MCP؟
نعم. Claude Code لديه دعم MCP أصلي عبر الأمر الفرعي claude mcp. استخدم claude mcp add لتسجيل الخوادم، و claude mcp list لرؤية المسجل، و claude mcp remove لإلغاء التسجيل. قم بتشغيل claude mcp --help للحصول على مرجع الأوامر الكامل.
كيف أضيف خادم MCP إلى Claude Code؟
قم بتشغيل claude mcp add <name> <command> [args...] لخادم stdio، أو استخدم --json لتمرير مواصفات JSON. للتسجيل بنطاق المشروع، أضف --scope project. بعد الإضافة، ابدأ جلسة Claude Code جديدة — ستكون الأدوات متاحة فورًا.
ما هو claude mcp serve؟
claude mcp serve يشغل Claude Code نفسه كخادم MCP، مما يكشف عن قدراته من خلال بروتوكول MCP. يمكن لمضيف MCP آخر بعد ذلك الاتصال بـ Claude Code واستخدامه كمصدر أداة. هذا مفيد عند بناء أنظمة متعددة الوكلاء حيث يكون Claude مكونًا من بين عدة مكونات.
هل يمكنني استخدام نفس خادم MCP في كل من Claude Code وسطح مكتب Claude؟
نعم. الخادم نفسه لا يهتم بأي مضيف يتصل به. بالنسبة لخوادم stdio، يمكن لكل من Claude Code (عبر claude mcp add) وسطح مكتب Claude (عبر claude_desktop_config.json) تشغيل نفس الأمر. بالنسبة لخوادم SSE، يمكن لأي مضيف يمكنه الوصول إلى URL الاتصال.
كيف يعرف Claude أي أداة MCP يستدعيها؟
في بداية الجلسة، يستعلم Claude جميع الخوادم المسجلة عن قوائم أدواتها. لكل أداة اسم ووصف. عند معالجة مهمة، يختار Claude الأدوات بناءً على ما إذا كانت أوصافها تتطابق مع ما هو مطلوب. الأوصاف المكتوبة جيدًا مع حالات استخدام واضحة تؤدي إلى اختيار دقيق للأداة؛ الأوصاف الغامضة تؤدي إلى استدعاءات مفقودة أو غير صحيحة.
هل هناك حد لعدد خوادم MCP التي يمكنني تسجيلها؟
لا يفرض مواصفات MCP حدًا صارمًا، ولا يفعله Claude Code أو سطح مكتب Claude. من الناحية العملية، وجود عشرات الخوادم مع مئات الأدوات يمكن أن يبطئ بدء الجلسة (اكتشاف الأداة يعمل عند الإطلاق) وقد يضيف تشويشًا لاختيار Claude للأداة. حافظ على مجموعة الأدوات مركزة على ما يحتاجه مشروع أو جلسة معينة بالفعل.
ما الفرق بين نقل stdio وSSE؟
يقوم Stdio بتشغيل الخادم كعملية فرعية محلية؛ يتواصل المضيف عبر stdin/stdout. يتصل SSE بنقطة نهاية HTTP عن بُعد ويتلقى الاستجابات كتيار. stdio أبسط للتطوير المحلي؛ SSE أفضل للنشر عن بُعد أو المشترك أو الإنتاجي.
