أمر claude mcp add: النطاقات، والمستخدم مقابل المشروع، وخوادم HTTP

تلصق عنوان URL لخادم في claude mcp add، وتضغط Enter، فيظهر الخادم في مشروع ثم يختفي في المشروع التالي. أو يصل إلى نسخة زميلك في العمل ويطلب موافقة لم يتوقعها أحد. تقريبًا كل نتيجة مربكة لهذا الأمر ترجع إلى قرارين: النطاق الذي اخترته ونوع النقل الذي استخدمته. يستعرض هذا المقال الأمر خيارًا خيارًا، ويوضح المكان الذي يخزّن فيه كل نطاق بياناته، ويشرح كيف يتفاعل نطاق المستخدم مع نطاق المشروع، ويقدّم أمثلة عملية لخوادم HTTP وstdio، بما في ذلك خاصية Windows التي تربك كثيرين.

ماذا يفعل أمر الإضافة

يسجّل claude mcp add خادم Model Context Protocol لدى Claude Code حتى يتمكن المساعد من استدعاء أدواته، وقراءة موارده، وتشغيل أوامره النصية. لا يثبّت الأمر أي شيء بمفرده. بل يكتب مدخل إعداد صغيرًا، ويقرؤه Claude Code عند بدء الجلسة التالية أو عند إعادة الاتصال من قائمة /mcp.

ثلاثة قرارات تحدد كل استدعاء:

• النقل: طريقة تواصل Claude Code مع الخادم (http أو sse أو stdio).
• النطاق: المكان الذي يُخزَّن فيه المدخل ومن يستطيع رؤيته (local أو project أو user).
• الاسم: التسمية التي ستكتبها لاحقًا في claude mcp get وclaude mcp remove وقائمة /mcp.

الصيغة الأساسية

تغطي صيغتان تقريبًا كل ما ستشغّله:

# Remote server reached over a URL
claude mcp add [options] <name> <url>

# Local process started by Claude Code
claude mcp add [options] <name> -- <command> [args...]

نسخ الأمر النصي

ضع --transport و--scope و--env قبل اسم الخادم. بالنسبة للعمليات المحلية، تخبر الشرطتان المزدوجتان المحلّل بأن كل ما يليهما يتبع الخادم وليس Claude Code.

💡 نصيحة: مرّر --transport في كل مرة، حتى عندما تعمل القيمة الافتراضية. يجعل الخيار الصريح الأمر يبدو متطابقًا في سجل الأوامر وملفات README ومحادثات الفريق، مهما كان الإصدار الذي يستخدمه كل شخص.

النطاقات الثلاثة في لمحة

يخزّن Claude Code كل خادم في أحد ثلاثة أماكن، ويحدد الخيار --scope (واختصاره -s) المكان. إذا حذفت الخيار حصلت على local.

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

النطاق المحلي: الافتراضي

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

نسخ الأمر النصي

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

نطاق المشروع: مشترك عبر Git

claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp

نسخ الأمر النصي

يُنشئ هذا الأمر أو يحدّث .mcp.json في جذر المشروع. ثبّته في الإصدارات، وسيحصل كل زميل على قائمة الخوادم نفسها بعد السحب. ولأن الملف داخل المستودع قادر على تشغيل عمليات على جهازك، يطلب Claude Code من كل شخص الموافقة على خوادم المشروع عند ظهورها لأول مرة. وإذا رفض أحدهم بالخطأ، يمسح claude mcp reset-project-choices الإجابات السابقة فتعود الرسالة.

نطاق المستخدم: في كل مكان تعمل فيه

claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp

نسخ الأمر النصي

يناسب نطاق المستخدم الأدوات الشخصية التي تريدها في كل مستودع: تطبيق ملاحظات، أو خادم بحث في التوثيق، أو مساعد للمتصفح. يعيش المدخل في ~/.claude.json، ويرافق حسابك على ذلك الجهاز، ولا يلمس أي مستودع أبدًا.

المستخدم مقابل المشروع: أيهما يفوز؟

يتلخص الاختيار بين نطاق المستخدم ونطاق المشروع في سؤال واحد: من غيرك يحتاج هذا الخادم؟ إذا كانت الإجابة "كل من يستنسخ هذا المستودع"، فاستخدم المشروع. وإذا كانت "أنا وحدي، لكن في كل مستودع"، فاستخدم المستخدم. وإذا كانت "أنا وحدي، وهنا فقط"، فابقَ على النطاق المحلي.

أيّ نطاق له الأولوية

عندما يوجد الاسم نفسه لخادم في أكثر من نطاق، يستخدم Claude Code التعريف الأكثر تحديدًا: المحلي يتفوق على المشروع، والمشروع يتفوق على المستخدم. هذا الترتيب يتيح لك تجاوز مدخل مشترك على جهازك دون تعديل ملف يستخدمه الآخرون.

لنفترض أن .mcp.json في الفريق يعرّف خادمًا باسم docs يشير إلى بيئة الإنتاج. يمكنك تشغيل هذا في نسختك المحلية من المستودع:

claude mcp add --transport http docs https://staging.example.com/mcp

نسخ الأمر النصي

يفوز المدخل المحلي، فتتصل جلستك بخادم staging بينما يواصل زملاؤك الاتصال بالإنتاج. احذف المدخل المحلي وستعود إلى المدخل المشترك.

المشاركة عبر .mcp.json

مدخل نطاق المشروع ملف JSON بسيط، ويمكنك كتابته يدويًا أيضًا:

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DOCS_TOKEN}"
      }
    }
  }
}

نسخ الأمر النصي

يوسّع Claude Code ${VAR} و${VAR:-default} داخل command وargs وurl وheaders وenv. هذا هو النمط الآمن للملفات المشتركة: ثبّت البنية، ودع كل شخص يوفر سره الخاص عبر متغير بيئة. الرمز الحقيقي الملصوق في .mcp.json ينتهي في سجل git، وتدويره هو الحل الوحيد الموثوق.

إضافة خوادم HTTP

HTTP هو نوع النقل الموصى به للخوادم البعيدة: لا عملية محلية، ولا بيئة تشغيل تحتاج إلى تثبيت، والمزوّد يتولى التحديثات. معظم خوادم MCP المستضافة تنشر عنوان URL ينتهي بالمقطع /mcp، وهذا هو العنوان الذي تمرّره للأمر.

خيار النقل

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

نسخ الأمر النصي

إذا كانت وثائق المزوّد ما زالت تعرض عنوان /sse، فتحقّق مما إذا كانت الخدمة نفسها توفر نقطة نهاية /mcp قبل تسجيل العنوان القديم. تستمر الخوادم على النقل المُهمَل في العمل حاليًا، لكن الإعدادات الجديدة يجب ألا تبدأ منه.

الترويسات والرموز الحاملة

تقرأ الخوادم التي تقبل بيانات اعتماد ثابتة هذه البيانات من ترويسة الطلب. مرّرها عبر --header (واختصاره -H)، وكرر الخيار عندما تحتاج أكثر من واحدة:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_TOKEN"

claude mcp add --transport http api https://example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-Team: platform"

نسخ الأمر النصي

💡 انتبه للصدفة: إذا كتبت $GITHUB_TOKEN داخل علامات اقتباس مزدوجة، فإن الصدفة (shell) توسّعه قبل أن يرى Claude Code الأمر، فيحتوي المدخل المخزّن على الرمز الحقيقي. وفي أي شيء مشترك، اكتب صيغة ${VAR} داخل .mcp.json بدلًا من ذلك.

المصادقة عبر OAuth

لا تعتمد كثير من الخوادم المستضافة على الرموز الثابتة وتستخدم OAuth. أضف الخادم دون ترويسات، وشغّل Claude Code، ونفّذ /mcp. اختر الخادم من القائمة، واتبع تسجيل الدخول في المتصفح. يخزّن Claude Code بيانات الاعتماد الناتجة ويجدّدها لك، فلا يوجد شيء تلصقه في ملف إعداد ولا شيء قد ترفعه بالخطأ.

خوادم stdio ومتغيرات البيئة

مع stdio، يشغّل Claude Code الخادم كعملية فرعية ويتواصل معه عبر المدخل والمخرج القياسيين. اختره للأدوات التي يجب أن تعمل على جهازك: مساعد لقاعدة بيانات محلية، أو أداة لنظام الملفات، أو سكربت كتبته بنفسك. تنتقل متغيرات البيئة مع الخيار --env (واختصاره -e).

فاصل الشرطتين المزدوجتين

claude mcp add --transport stdio --env API_TOKEN=YOUR_TOKEN myserver \
  -- npx -y my-mcp-server

نسخ الأمر النصي

كل ما يسبق -- موجّه إلى Claude Code. وكل ما يليه هو الأمر الدقيق الذي يشغّل الخادم، مع وسائطه. وإغفال الفاصل هو أكثر خطأ شيوعًا مع stdio:

# Wrong: --port is parsed as a Claude Code option
claude mcp add --transport stdio myserver npx server --port 8080

# Right: the server command sits after the double dash
claude mcp add --transport stdio myserver -- npx server --port 8080

نسخ الأمر النصي

Windows يحتاج إلى cmd /c

على Windows الأصلي (وليس WSL)، يكون npx غلافًا لملف دفعي (batch) وليس ملفًا تنفيذيًا حقيقيًا، لذلك لا يستطيع Claude Code تشغيله مباشرة. غلّف الأمر بـ cmd /c:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

نسخ الأمر النصي

بدون الغلاف، ستجد عادةً خطأ "Connection closed" في /mcp، وهو يبدو كخلل في الخادم لكنه مجرد فشل في التشغيل. ينطبق الإصلاح نفسه عندما تكتب المدخل يدويًا: اضبط "command": "cmd" وابدأ args بالأمر "/c"، ثم "npx".

إدارة الخوادم بعد الإضافة

تسجيل الخادم نصف المهمة. ثلاثة أوامر تتولى بقية حياته:

claude mcp list            # every server and its connection status
claude mcp get docs        # details for one server
claude mcp remove docs     # delete it

نسخ الأمر النصي

داخل الجلسة، يعرض /mcp الحالة نفسها لحظيًا، وهو أيضًا المكان الذي تسجّل فيه الدخول إلى خوادم OAuth أو تعيد الاتصال بخادم انقطع.

القائمة والعرض والإزالة

شغّل claude mcp list أولًا كلما شعرت بخلل ما. يعرض ما يعرفه Claude Code فعلًا من كل النطاقات، فتعرف فورًا ما إذا كان الخادم مفقودًا أو يفشل فقط. استخدم claude mcp get <name> لترى مصدر المدخل. وإذا وُجد الاسم نفسه في أكثر من نطاق، فمرّر --scope إلى claude mcp remove لتحذف النسخة الصحيحة.

اختصار add-json

عندما يعطيك مزوّد مقتطف JSON، تجاوز الخيارات وأعطه للأمر مباشرة:

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

نسخ الأمر النصي

يقبل add-json الخيار --scope نفسه، فيمكنك إضافة مقتطف إلى نطاق المستخدم أو المشروع بخطوة واحدة. وإذا كنت قد بنيت مجموعة خوادم في Claude Desktop، فإن claude mcp add-from-claude-desktop يستوردها تفاعليًا على macOS وWSL.

إصلاح الأعطال الشائعة

تندرج معظم الأعطال ضمن قائمة قصيرة. طابق الأعراض أولًا، وابدأ تعديل الملفات بعد ذلك فقط.

إذا لم يحسم الجدول المشكلة، فنفّذ الفحوص الأربعة التالية بالترتيب:

1. claude mcp list للتأكد من أن الخادم مسجّل، ولرؤية حالته.
2. claude mcp get <name> لقراءة الأمر أو عنوان URL الدقيق الذي يستخدمه Claude Code.
3. /mcp داخل الجلسة لرؤية حالة الاتصال المباشرة وإعادة الاتصال.
4. الصق أمر stdio في طرفية عادية. إذا فشل هناك، فالمشكلة في الخادم وليست في Claude Code.

عندما لا يتصل الخادم: بالنسبة للخادم البعيد، افتح عنوان URL في المتصفح أو استدعه باستخدام curl. يعني الخطأ 401 أو 403 أن الترويسة أو تسجيل الدخول غير صحيح، ويشير الخطأ 404 عادةً إلى أن المسار خاطئ (/mcp مقابل /sse)، أما انتهاء المهلة فيشير إلى الشبكة. بالنسبة لخادم stdio، يجب أن يعمل الأمر الذي سجّلته وحده، مع ضبط متغيرات البيئة نفسها.

وظّف Claude و PicassoIA

بعد ضبط النطاقات، يصبح MCP وسيلة لمنح Claude قدرات حقيقية، والصور مثال جيد على ذلك. توفّر PicassoIA نماذج التوليد لديها عبر API للمطورين على https://api.picassoia.com/v1 وعبر اتصالات MCP. النماذج الأربعة المتاحة في هذه الواجهة هي PicassoIA Image وPicassoIA Image Editor Pro ونموذجان للفيديو. تعمل المهام بشكل غير متزامن: يرسل Claude طلب تنبؤ، ثم يستعلم عن حالته، ثم يقرأ النتيجة النهائية. تسمح المنصة بتشغيل 5 تنبؤات متزامنة لكل حساب، وتُشارَك بين كل الاتصالات المفتوحة لديك، لذا ستنتظر دفعة الطلبات من جلسة واحدة في قائمة الانتظار بدلًا من أن تعمل كلها دفعة واحدة.

💡 نصيحة النطاق: تسرد صفحة الأسعار اتصالات MCP ضمن خطط Pro+ وElite وInfinite، فتأكد من خطتك قبل الإعداد. سجّل الاتصال على نطاق المستخدم إذا أردت توليد الصور في كل مستودع، أو على النطاق المحلي إذا كان مشروع واحد فقط يحتاجه. انسخ عنوان اتصال MCP من حسابك في PicassoIA بدلًا من تخمين العنوان.

كيف تُصحّح مع Claude على PicassoIA

لا تحتاج إلى طرفية لتحصل على مساعدة في أمر claude mcp add يفشل. يعمل Claude Sonnet 5 على PicassoIA، ويتعامل مع هذا النوع من التصحيح بكفاءة:

1. افتح صفحة النموذج من الرابط أعلاه.
2. الصق الأمر الدقيق الذي شغّلته، مع نص الخطأ من /mcp أو من الطرفية.
3. اذكر نظام التشغيل الذي تستخدمه، وهل الخادم HTTP أم stdio.
4. اطلب الأمر المصحَّح وشرحًا من سطر واحد لما كان خاطئًا.
5. شغّل الإصلاح، ثم تحقق منه باستخدام claude mcp list.

للاستدلال الأثقل حول .mcp.json كبير، يتوفر Claude Opus 4.7 على المنصة نفسها، ويجيب Claude 4.5 Haiku عن أسئلة الصياغة البرمجية الخفيفة بسرعة.

أنشئ صورك بنفسك

قراءة النطاقات مفيدة، لكن المكسب الحقيقي يأتي من جعل Claude يعمل مع المرئيات أثناء البرمجة. افتح PicassoIA، واختر نموذجًا مثل PicassoIA Image، ووَلّد عدة صور من أوامرك النصية. جرّب صورة رأس لملف README القادم، أو نموذجًا لمنتج، أو مشهدًا بأسلوب الصور الفوتوغرافية لمقال مدونة. عندما تعجبك النتائج، وصّل القدرة نفسها إلى Claude Code عبر MCP، ودع المساعد ينتج الصور داخل سير عملك. جرّب بحرية، وقارن النماذج جنبًا إلى جنب، واحتفظ بالأوامر النصية التي تنجح.