- كيف يعمل تكوين MCP في Claude
- إضافة خوادم MCP في Claude Code
- تكوين خوادم MCP في Claude Desktop
- أنواع وسائل نقل MCP: stdio مقابل SSE
- كيف يفكر Claude في أدوات MCP
- تشغيل تنفيذ الأداة في بيئة معزولة (Sandbox)
- استخدام Novita LLM API لمنطق استخدام أدوات MCP
- المشكلات الشائعة والحلول
- الأسئلة الشائعة
- المقالات الموصى بها
يُوصِّل تكوين MCP في Claude بين Claude Code أو Claude Desktop والأدوات الخارجية مثل قواعد البيانات، ومنفّذي الأكواد، وواجهات APIs، والخوادم المخصصة. استخدم claude mcp add لـ Claude Code أو حرّر ملف تكوين JSON لـ Claude Desktop، ثم تحقق من وسيلة النقل والنطاق وقائمة الأدوات. يغطي هذا الدليل كلا مساري الإعداد، والأعطال الشائعة، ومنطق استخدام الأدوات، والتنفيذ في بيئة معزولة.
كيف يعمل تكوين MCP في Claude
MCP هو معيار مفتوح من Anthropic يمنح نماذج اللغة طريقة موحدة لاستدعاء الأدوات الخارجية. قبل MCP، كان كل تطبيق ذكاء اصطناعي يحتاج إلى كود ربط مخصص لكل أداة يريد استخدامها. مع MCP، أي خادم متوافق يكشف عن قدراته من خلال بروتوكول اكتشاف واستدعاء قياسي، وأي مضيف متوافق — بما في ذلك Claude — يمكنه استخدامها دون الحاجة إلى عمل تكامل لكل أداة على حدة.
من الناحية العملية: عندما تضيف خادم MCP إلى Claude، فأنت تخبر مضيف Claude بمكان العثور على مجموعة من الأدوات. يمكن لـ Claude بعد ذلك سرد هذه الأدوات أثناء الجلسة واستدعاؤها بالاسم عندما تتطلب المهمة ذلك. الخادم يتولى التنفيذ؛ Claude يتولى التفكير في متى وكيف يستدعي.
ثلاثة مفاهيم أساسية تدعم MCP:
| المفهوم | ما هو | مثال |
|---|---|---|
| أداة (Tool) | دالة قابلة للاستدعاء يقدمها الخادم | run_python، query_db، list_models |
| مورد (Resource) | بيانات للقراءة فقط يجعلها الخادم متاحة كسياق | ملف، صف في قاعدة بيانات، مجموعة بيانات |
| موجه (Prompt) | قوالب تعليمات مبنية مسبقًا ومضمنة مع الخادم | وصف مهمة على مستوى النظام |
بالنسبة لمعظم المطورين، الأدوات هي الأكثر أهمية. تصبح الموارد والموجهات ذات صلة عندما تبني خط أنابيب وكيل أكثر تنظيماً.
إضافة خوادم MCP في Claude Code
يتيح Claude Code إدارة MCP من خلال مجموعة الأوامر الفرعية claude mcp. يمكنك إضافة الخوادم وإزالتها وسردها دون لمس أي ملف تكوين يدويًا.
claude mcp add — الصيغة الأساسية
claude mcp add <name> <command> [args...]
على سبيل المثال، لإضافة خادم MCP محلي بلغة Python:
claude mcp add my-tools python /path/to/mcp_server.py
هذا يسجّل خادمًا باسم my-tools يقوم بتشغيل python /path/to/mcp_server.py باستخدام وسيلة نقل stdio. يطلق Claude Code العملية عند بدء جلسة ويبقيها قيد التشغيل طوال المدة.
تمرير متغيرات البيئة
العديد من خوادم MCP تحتاج إلى مفاتيح API أو روابط endpoints. استخدم --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 Desktop
يخزّن Claude Desktop تكوين خادم 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 Desktop بتحميلها جميعًا عند بدء التشغيل.
بعد تحرير الملف، أعد تشغيل Claude Desktop لتفعيل التغييرات. ستظهر أيقونة مطرقة في منطقة إدخال الدردشة عند تحميل أدوات MCP بنجاح.
إضافة خادم MCP عن بُعد عبر SSE
بالنسبة للخوادم البعيدة التي تستخدم وسيلة نقل Server-Sent Events (SSE) بدلاً من stdio، يكون شكل التكوين مختلفًا قليلاً:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse"
}
}
}
بعض الخوادم البعيدة تتطلب مصادقة. مرر رمز bearer في حقل الرؤوس إذا كان الخادم يتوقعه:
{
"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 (Server-Sent Events) — يعمل الخادم عن بُعد ويكشف عن نقطة HTTP endpoint. يتصل المضيف بعنوان URL ويتلقى استجابات الأدوات كتدفق. هذا يعمل عبر الأجهزة وهو الخيار المناسب للبنية التحتية المشتركة للفريق أو خدمات الأدوات المستضافة.
بالنسبة لمعظم المطورين الأفراد المبتدئين، فإن stdio أسهل — لا حاجة للشبكات، ويتم إدارة عملية الخادم لك. يصبح SSE ذا قيمة عندما تريد أن يشارك فريق واحد خادم MCP واحد، أو عندما تحتاج الأداة نفسها إلى العمل في بيئة شبكية محددة.
كيف يفكر Claude في أدوات MCP
عند بدء جلسة وتكون خوادم MCP مسجلة، يستعلم Claude كل خادم عن أدواته المتاحة. ينتج عن ذلك قائمة بأسماء الأدوات وأوصاف JSON Schema. لا يستدعي Claude الأدوات بشكل تخميني — فهو يستدعي الأداة فقط عندما تتطلب المحادثة أو المهمة ذلك، بناءً على ما يصفه وصف الأداة بأنها تفعله.
تسير عملية استدعاء الأداة على النحو التالي:
- يرسل المستخدم رسالة أو مهمة.
- يقيّم Claude ما إذا كانت أي أداة مسجلة يمكنها المساعدة.
- إذا كانت الإجابة بنعم، يقوم Claude ببناء استدعاء أداة بالوسائط المناسبة.
- يرسل مضيف MCP الاستدعاء إلى الخادم الصحيح.
- ينفّذ الخادم ويعيد النتيجة.
- يدمج Claude النتيجة في تفكيره ويواصل.
يمكن أن تتكرر هذه الحلقة عدة مرات في جولة واحدة — يمكن لـ Claude ربط استدعاءات الأدوات، واستخدام نتائج أداة واحدة لإعلام وسائط أداة أخرى، والتجميع عبر عدة خوادم في نفس الجلسة.
جودة أوصاف الأدوات مهمة جدًا هنا. الأوصاف الغامضة تؤدي إلى استدعاءات مفقودة أو غير صحيحة. الأوصاف الدقيقة التي تتضمن ما تفعله الأداة، وما تعنيه وسائطها، وما ترجعه، تسمح لـ Claude بتوجيه الاستدعاءات بدقة دون تخمين.
تشغيل تنفيذ الأداة في بيئة معزولة (Sandbox)
عندما تنفّذ أدوات MCP أكوادًا — نصوص Python، أوامر shell، عمليات ملفات — فإن تشغيلها على جهازك المحلي يثير أسئلة حول العزل. الأداة التي لديها وصول إلى نظام الملفات، أو إنشاء عمليات، أو استدعاءات شبكية لها نطاق واسع إذا أساءت التصرف أو تم توجيهها إلى مسار غير متوقع.
بيئة Novita AI Agent Sandbox تعالج هذا من خلال توفير بيئات سحابية معزولة لتنفيذ الأدوات. بدلاً من تشغيل خادم MCP الخاص بك محليًا، تقوم بنشره داخل مثيل sandbox. يحصل sandbox على نظام ملفات خاص به، ونطاق شبكي خاص به، وحدود موارده الخاصة. يمكن للوكيل كتابة الملفات، وتشغيل الأكواد، واستدعاء APIs داخلية داخل تلك الحدود دون لمس الجهاز المضيف.
خادم MCP الذي يعمل داخل sandbox يكشف عن أدواته من خلال نقل SSE، ويتصل به Claude عن بُعد — لذا من منظور Claude، التكامل متطابق. الفرق بالكامل في ما تعمل عليه الأداة فعليًا.
الخصائص الرئيسية لـ Novita Sandbox لنشر MCP:
- بدء تشغيل سريع: يتم إطلاق المثيلات في أقل من 200 مللي ثانية، مما يحافظ على انخفاض زمن الاستجابة ذهابًا وإيابًا للأداة
- فوترة بالثانية: تدفع فقط مقابل وقت التنفيذ النشط، وليس الحجز الخامل
- نظام ملفات معزول: كل مثيل sandbox لديه مساحة عمل منفصلة، مما يمنع تسرب البيانات عبر الجلسات
- سياسة شبكية قابلة للتكوين: تحكم في الخدمات الخارجية التي يمكن للأداة الوصول إليها
للحصول على دليل خطوة بخطوة لبناء خادم MCP مدعوم بـ Novita Sandbox، راجع Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library.
استخدام Novita LLM API لمنطق استخدام أدوات MCP
بينما تتعامل نماذج Claude الخاصة مع استخدام الأدوات بشكل أصلي، قد ترغب في توجيه بعض منطق استخدام أدوات MCP عبر نموذج مختلف — لأسباب تتعلق بالتكلفة، أو زمن الاستجابة، أو التخصص. Novita LLM API يوفر نقطة endpoint متوافقة مع OpenAI مع إمكانية الوصول إلى نماذج تدعم استدعاء الدوال واستدعاء الأدوات المنظم.
يندرج هذا في بنى MCP بطريقتين:
1. كنموذج التفكير خلف مضيف MCP مخصص: إذا كنت تبني مضيف MCP الخاص بك (بدلاً من استخدام Claude Code أو Claude Desktop)، يمكنك استخدام Novita LLM API لتشغيل طبقة النموذج. يستدعي المضيف 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": "List the available tools and run a quick test"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "List all available models from the API.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. كنموذج LLM داخل أداة MCP نفسها: يمكن لأداة MCP استخدام Novita LLM API داخليًا — على سبيل المثال، أداة تلخيص، أداة تصنيف، أو أداة لتوليد الأكواد. تستقبل الأداة المدخلات من الوكيل، وتستدعي Novita API، وتعطي النتيجة. هذا يبقي تكاليف استدلال النموذج منفصلة عن تكاليف نموذج الوكيل الرئيسي ويتيح لك اختيار النموذج المناسب لكل مهمة فرعية.
للحصول على مثال عملي لبناء خادم MCP يستدعي Novita API، راجع How to Build Your First MCP Server with Novita AI.
المشكلات الشائعة والحلول
الخادم لا يظهر في Claude Desktop
السبب الأكثر شيوعًا هو خطأ في بناء جملة JSON في ملف claude_desktop_config.json. استخدم أداة التحقق من JSON قبل الحفظ. حتى الفاصلة الزائدة ستمنع تحميل الملف. أعد تشغيل Claude Desktop بعد كل تعديل.
أمر 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 Desktop؟
نعم. الخادم نفسه لا يهتم بأي مضيف يتصل به. بالنسبة لخوادم stdio، يمكن لكل من Claude Code (عبر claude mcp add) وClaude Desktop (عبر claude_desktop_config.json) تشغيل نفس الأمر. بالنسبة لخوادم SSE، يمكن لأي مضيف يمكنه الوصول إلى عنوان URL الاتصال.
كيف يعرف Claude أي أداة MCP يستدعي؟
في بداية الجلسة، يستعلم Claude جميع الخوادم المسجلة عن قوائم أدواتها. كل أداة لها اسم ووصف. عند معالجة مهمة، يختار Claude الأدوات بناءً على ما إذا كانت أوصافها تتطابق مع ما هو مطلوب. الأوصاف المكتوبة جيدًا مع حالات استخدام واضحة تؤدي إلى اختيار دقيق للأداة؛ الأوصاف الغامضة تؤدي إلى استدعاءات مفقودة أو غير صحيحة.
هل هناك حد لعدد خوادم MCP التي يمكنني تسجيلها؟
مواصفات MCP لا تفرض حدًا صارمًا، وكذلك Claude Code وClaude Desktop. من الناحية العملية، وجود عشرات الخوادم مع مئات الأدوات يمكن أن يبطئ بدء تشغيل الجلسة (اكتشاف الأداة يعمل عند الإطلاق) وقد يضيف ضوضاء إلى اختيار Claude للأداة. حافظ على مجموعة الأدوات مركزة على ما يحتاجه مشروع أو جلسة معينة فعليًا.
ما الفرق بين وسيلة نقل stdio وSSE؟
Stdio يشغّل الخادم كعملية فرعية محلية؛ يتواصل المضيف عبر stdin/stdout. SSE يتصل بنقطة HTTP endpoint عن بُعد ويتلقى الاستجابات كتدفق. Stdio أبسط للتطوير المحلي؛ SSE أفضل للنشر عن بُعد والمشترك والإنتاجي.
