إعداد خادم MCP في GitHub Copilot: السجل وقائمة السماح والإعدادات

يتصل أول خادم MCP لك في GitHub Copilot خلال دقيقتين تقريبًا. أما الحصول على موافقة الفريق الأمني لذلك الخادم نفسه، وإدراجه في سجل، وتثبيته على قائمة سماح، فيستغرق بقية الأسبوع، إلا إذا كنت تعرف أي إعداد يفعل ماذا. يتتبع هذا المقال الطبقات الثلاث بالترتيب: ملف الإعداد الذي يكتبه المطوّر، والسجل الذي يتصفحه الفريق، وقائمة السماح التي يفرضها المسؤول. كل عينة JSON تطابق الوثائق الحالية الخاصة بكل من GitHub و VS Code، وكل قيد يُشار إليه في الموضع الذي يسبب فيه المشكلة بالضبط.

💡 ملخص سريع: يكتب المطورون mcp.json، ويختار الفرق الخوادم من سجل، ويفرض المسؤولون allowedMcpServers في managed-settings.json. ثلاثة ملفات، وثلاثة مالكين، وأي خلل في أيٍّ منها يبدو كأن "Copilot لا يملك أدوات."

ما الذي تفعله MCP داخل Copilot

بروتوكول سياق النموذج (Model Context Protocol أو MCP) هو المعيار المفتوح الذي يسمح بأن يستدعي Copilot أدوات تعيش خارج المحرر: استعلامًا من قاعدة بيانات، وبحثًا عن مشكلة في Sentry، وجلسة متصفح، ومتتبعًا للتذاكر. بدون MCP، لا يرى Copilot سوى ما يعرضه له محررك. ومع MCP، يستطيع وضع الوكيل قراءة المشكلة الفاشلة، ثم الاستعلام عن البيانات الكامنة وراءها، ثم تعديل الشيفرة التي تسببت في المشكلة، كل ذلك في محادثة واحدة.

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

أي العملاء يدعمه

لا يتشابه إعداد MCP عبر أسطح Copilot المختلفة. يتغير الملف وصيغته في كل سطح:

ملفات الإعداد ومكان وجودها

إذا وضعت الملف في المكان الخطأ، يتجاهله Copilot دون خطأ واضح. ابدأ بتحديد من يجب أن يحصل على الخادم.

نطاق مساحة العمل مقابل نطاق المستخدم

.vscode/mcp.json يعيش داخل المستودع، لذلك يحصل كل من يستنسخه على الخوادم نفسها. وهذا ما يجعله المكان المناسب لأدوات المشروع، مثل مستعرض قواعد البيانات أو متصفح Playwright. ينطبق إعداد ملف تعريف المستخدم لديك على كل مساحات العمل على جهازك. افتحه من لوحة الأوامر باستخدام MCP: Open User Configuration، واحتفظ بالأدوات الشخصية هناك.

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

الملفات المحمولة للعملاء الآخرين

يذكر مرجع إعداد MCP في VS Code أيضًا صيغة محمولة: .mcp.json في جذر مساحة العمل، أو ~/.copilot/mcp-config.json لحسابك. يُلجأ إليها عندما يُفتح المستودع نفسه من أكثر من عميل Copilot، وتريد تعريفًا واحدًا بدلًا من ثلاثة.

يُبنى كل إدخال للخادم من مجموعة صغيرة من الحقول نفسها:

توجد إضافتان على macOS و Linux فقط: كائن sandbox على المستوى الأعلى (قواعد نظام الملفات والشبكة)، ومفتاح sandboxEnabled لكل خادم.

اكتب أول ملف mcp.json

يمكنك كتابة الملف يدويًا، أو تشغيل MCP: Add Server من لوحة الأوامر، فيولّد VS Code الإدخال بنفسه. يستحق كتابته يدويًا مرة واحدة، لأن كل مشكلة لاحقة تصبح أسهل في الرصد عندما تعرف شكل الملف السليم.

خادم stdio محلي

يشغّل هذا الإدخال خادم Playwright MCP عبر npx كلما احتاج Copilot إليه:

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

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

احفظ الملف، وسيعرض VS Code إجراءات Start وStop وRestart فوق الإدخال. شغّله، وافتح Copilot Chat في وضع الوكيل، وتحقق من منتقي الأدوات: يجب أن تظهر أدوات الخادم الآن جاهزة للتفعيل.

خادم HTTP بعيد

يحتاج الخادم البعيد إلى عنوان URL بدلًا من أمر. يشير هذا المثال إلى خادم GitHub MCP المستضاف:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

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

إذا كان الخادم يدعم OAuth، يفتح VS Code نافذة تسجيل الدخول في أول مرة تُشغَّل فيها أداة. وإذا كان يتوقع رمزًا ثابتًا، فأرسله عبر headers، ولا تلصق الرمز نفسه في ملف مُلتزَم به أبدًا.

أبقِ الأسرار خارج الإعداد

يحل VS Code هذه المشكلة عبر متغيرات الإدخال (input variables). تُعلن عن الإدخال مرة واحدة، وتضع عليه علامة كحقل كلمة مرور، ثم تشير إليه باستخدام ${input:id}:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sentry-token",
      "description": "Sentry auth token",
      "password": true
    }
  ],
  "servers": {
    "sentry": {
      "type": "stdio",
      "command": "npx",
      "args": ["@sentry/mcp-server@latest"],
      "env": { "SENTRY_TOKEN": "${input:sentry-token}" }
    }
  }
}

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

يطلب VS Code القيمة في أول مرة يبدأ فيها الخادم، فلا يحتوي المستودع إلا على العنصر النائب. تأتي المدخلات بثلاثة أنواع: promptString للنص المكتوب، و pickString لقائمة منسدلة، و command لقيمة يُنتجها تشغيل أمر. يحتاج كل إدخال إلى type، و id، و description.

💡 أكثر تسريب شيوعًا في MCP هو ملف .vscode/mcp.json مُلتزَم به ويحتوي على رمز ملصوق. إذا استخدمت envFile، فأضف ذلك الملف إلى .gitignore في الالتزام نفسه.

ابحث عن الخوادم في السجل

كتابة JSON يدويًا لكل خادم تصبح مملّة بسرعة. وجود السجل يعفيك من ذلك.

سجل GitHub MCP

تسرد github.com/mcp خوادم من المجتمع تربط النماذج بالملفات وواجهات API وقواعد البيانات. وقت كتابة هذه السطور تعرض 375 خادمًا، من Markitdown الذي تقدمه Microsoft، إلى Stripe و Figma، ولكل منها زر تثبيت. يضيف التثبيت إدخالًا إلى إعدادك، لذا اقرأه قبل تشغيل الخادم: تحقق من الأمر واسم الحزمة وعنوان URL.

يعرض VS Code أيضًا خوادم MCP داخل المحرر. اكتب @mcp في خانة البحث في عرض Extensions لتصفحها، وثبّت أحدها، وسيضيف VS Code الإدخال إلى إعدادك الشخصي أو إعداد مساحة العمل. اعتبر إدراج السجل نقطة بداية، لا مراجعة أمنية.

شغّل سجلك الخاص

يمكن للمؤسسات استضافة سجل MCP خاص بها وتوجيه Copilot إليه. إذا بنيته على Azure API Center، فأدخل عنوان URL الأساسي بهذا الشكل:

https://SERVICE-NAME.data.REGION.azure-apicenter.ms/workspaces/WORKSPACE-NAME

لا تُضف لاحقة مسار مثل /v0.1/servers. يضيف Copilot مسار MCP v0.1 بنفسه، وتؤدي اللاحقة إلى فشل السجل. يعيّن مالكو Enterprise عنوان URL من AI controls، ثم MCP. ويعيّنه مالكو المنظمة من Copilot، ثم Policies.

قيّد الخوادم بقوائم السماح

لدى المسؤولين طريقتان لتحديد الخوادم التي يُسمح للمطورين بتشغيلها. وهما ليستا متكافئتين، لذا اختر عن قصد.

تصف وثائق GitHub نفسها الإعدادات المُدارة بأنها الطريقة الأكثر أمانًا والمتاحة عمومًا، وتصف سياسة السجل فقط بأنها ليست الطريقة الموصى بها.

طريقة الإعدادات المُدارة

أضف أيًا من allowedMcpServers أو deniedMcpServers، أو كليهما، إلى copilot/managed-settings.json في مستودع .github-private الخاص بمؤسستك، ثم نفّذ الالتزام على الفرع الافتراضي:

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "@playwright/mcp@latest"] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://untrusted.example/*" }
  ]
}

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

هناك ثلاثة أنواع من المطابقة:

• serverUrl يطابق خوادم HTTP و SSE البعيدة، ويدعم أحرف البدل *، ويُطبِّع عناوين URL لمنع التحايل.
• serverCommand يطابق خادم stdio محليًا بأمره ووسائطه بالضبط.
• serverName يطابق التسمية التي كتبها المستخدم في إعداده. وهو للتيسير فقط، وليس حدًا أمنيًا.

كيف تعمل المطابقة

يقيّم Copilot الخادم وفق ترتيب ثابت:

1. الإعدادات الافتراضية المدمجة مسموحة دائمًا.
2. قائمة المنع تحجب كل ما يطابقها.
3. إذا وُجدت قائمة سماح، يجب أن يطابق الخادم أحد إدخالاتها، وإلا يُحجب.
4. أي ${VARIABLE} غير محلول في الإعداد يحجب الخادم.

مع غياب قائمة السماح تمامًا، يعمل الخادم ما لم يكن ممنوعًا أو يحتوي على متغير غير محلول. وعندما تنطبق عدة مصادر managed-settings.json، تُطبَّق كل الإعدادات، ويحجب أي قاعدة منع من أي مصدر الخادم. ويمكنك تعليم الإعدادات بأنها overridable، حتى يستطيع الفريق تخصيص طبقته الخاصة.

💡 مطابقة الأوامر دقيقة تمامًا. إذا سمحت بالأمر ["npx", "@playwright/mcp@latest"]، فلن يطابق المطوّر الذي يشغّل npx -y @playwright/mcp@latest، لأن الوسائط مختلفة. انشر الإدخال الدقيق الذي تريد أن ينسخه الناس.

سياسة السجل فقط

ما زلت على مسار المعاينة؟ فعّل سياسة MCP servers in Copilot، وأدخل عنوان URL لسجلك، ثم اضبط Restrict MCP access to registry servers على Registry only. يُطبَّق التغيير فورًا. وبما أنها تطابق بالاسم أو المعرّف، عاملها كحاجز وقائي ضد الأخطاء غير المقصودة، وانقل البيئات عالية المخاطر إلى الإعدادات المُدارة. الخطوات الكاملة موجودة في وثائق GitHub الخاصة بوصول MCP.

إعداد وكيل السحابة و CLI

يعمل وكيل Copilot السحابي (الذي كان يُسمى سابقًا وكيل البرمجة) على بنية GitHub التحتية، لذا لا يستطيع قراءة .vscode/mcp.json المحلي لديك. له إعداد خاص به، وهنا تقع معظم أخطاء النسخ واللصق.

افتح المستودع، واذهب إلى Settings، واختر Copilot ضمن Code & automation، ثم حرّر مربع MCP configuration:

{
  "mcpServers": {
    "sentry": {
      "type": "local",
      "command": "npx",
      "args": ["@sentry/mcp-server@latest"],
      "tools": ["list_issues"],
      "env": { "SENTRY_TOKEN": "$COPILOT_MCP_SENTRY_TOKEN" }
    }
  }
}

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

خمس قواعد تفصل هذه الصيغة عن صيغة VS Code:

• الحقل الأعلى مستوى هو mcpServers، وليس servers.
• type يقبل local، أو stdio، أو http، أو sse.
• tools مطلوب. استخدم ["*"] لكل شيء، أو اذكر أسماء الأدوات لتقييد الوكيل بإحكام.
• يجب إضافة الأسرار كأسرار أو متغيرات للوكيل تبدأ أسماؤها بالبادئة COPILOT_MCP_، ويجب أن يشير الإعداد إلى هذه الأسماء بالضبط.
• الأدوات وحدها مدعومة، ولا تستطيع الخوادم البعيدة استخدام OAuth.

خوادم GitHub و Playwright MCP مفعّلة أصلًا في كل مستودع، لذا لا تضيف إلا ما ينقص. اقرأ وثائق MCP لوكيل السحابة قبل إضافة أي شيء يكتب بيانات.

Copilot CLI. يقرأ Copilot CLI الملف ~/.copilot/mcp-config.json. داخل جلسة تفاعلية، يرشدك /mcp add خلال إضافة خادم دون تحرير JSON يدويًا. وتُفرض قوائم السماح من الإعدادات المُدارة هنا أيضًا، لذلك فإن الخادم الذي يعمل في VS Code لكنه محجوب في الطرفية يشير غالبًا إلى عدم تطابق في السياسة، لا إلى تثبيت معطّل.

أصلح الأخطاء الشائعة بسرعة

تعود معظم الإخفاقات إلى خمسة أسباب. طابق عَرَضك مع الجدول قبل إعادة تثبيت أي شيء.

الخادم يبدأ لكن لا توجد أدوات

شغّل MCP: List Servers، واختر الخادم، وافتح مخرجاته. يظهر الانهيار عند التشغيل عادةً في صورة بيئة تشغيل مفقودة (Node أو Python غير موجودين في المسار)، أو اسم حزمة خاطئ. إذا كانت العملية سليمة، فافتح منتقي الأدوات في وضع الوكيل، وتأكد من تفعيل الأدوات.

محجوب بسبب السياسة

الخادم المحجوب يعود تقريبًا دائمًا إلى واحد من ثلاثة أسباب: توجد قائمة سماح ولا يطابقها شيء، أو تنطبق قاعدة منع من مصدر managed-settings.json آخر، أو يحتوي الإعداد على ${VARIABLE} غير محلول. ولأن السياسات تُغلق افتراضيًا، فإن ملف إعدادات معطوب يحجب الخوادم بدلًا من أن يسمح بمرورها. اسأل المسؤول عن المصدر الذي حجبها قبل تعديل إعدادك الخاص.

مقتطفات ملصوقة من عملاء آخرين. المقتطف المنسوخ من وثائق عميل MCP آخر يستخدم غالبًا mcpServers. الصقه في .vscode/mcp.json ولن يُحمّل شيء، ولن يظهر أي تنبيه. أعد تسمية الحقل، وأضف type صراحةً، وانقل الأسرار إلى المدخلات بينما أنت هنا.

استخدم PicassoIA

عين ثانية تلتقط الأخطاء المملّة: اسم حقل خاطئ، أو قائمة tools مفقودة، أو وسيط يكسر المطابقة الدقيقة. يمكنك الحصول عليها في دقيقة.

استخدم Claude Sonnet 5 على PicassoIA

Claude Sonnet 5 يقرأ الإعدادات، ويستدل عبر المشكلات متعددة الخطوات، ويقبل الصور، لذا فهو مناسب جدًا لهذه المهمة. إليك طريقة قابلة للتكرار لاستخدامه:

1. افتح صفحة Claude Sonnet 5 على PicassoIA.
2. في System Prompt، حدد الدور مرة واحدة: "أنت تراجع إعدادات GitHub Copilot MCP. تحقّق من الحقل الأعلى مستوى، ونوع النقل، وقائمة الأدوات، والتعامل مع الأسرار، وإدخالات قائمة السماح المطابقة تمامًا."
3. الصق mcp.json أو managed-settings.json في Prompt. استبدل أولًا أي رمز حقيقي بعنصر نائب.
4. اضبط Effort على high لمنطق قائمة السماح. الإعداد الافتراضي low مناسب لفحص الأخطاء المطبعية، ويعيد النتيجة خلال ثوانٍ.
5. اترك Max Tokens على 8192، وهو كافٍ لمراجعة كاملة.
6. أرفق لقطة شاشة للخطأ في حقل Image إن توفرت، لأن النموذج يقرأ الصور.
7. شغّله، ثم طبّق الإصلاحات واحدًا تلو الآخر، وأعد تشغيل الخادم بعد كل واحد.

للحصول على رأي ثانٍ، أرسل الأمر نفسه إلى GPT 5.6 Sol أو Gemini 3.1 Pro أو Kimi K2.6، وقارن المواضع التي يختلفون فيها. غالبًا ما يشير الخلاف إلى السطر الذي يستحق قراءته بنفسك.

أنشئ صورك الخاصة بعد ذلك

إطلاق هذا على فريق يعني صفحة في الويكي، وشريحة لمراجعة الأمان، وصورة رأسية لا تبدو كصورة مخزون عامة. تولّد Picasso IA كل ذلك من أمر نصي. جرّب Qwen Image 3 للمشاهد الواقعية كالصور الفوتوغرافية، أو Seedream 5 Pro لمخرجات 2K حادة، أو GPT Image 2.5 Flare عندما تحتاج إلى مسودة سريعة. صف المشهد، واختر نسبة العرض إلى الارتفاع 16:9، وكرر حتى يناسب مستندك. افتح Picasso IA، واكتب أمرك النصي الأول، وشاهد كيف يبدو منشور الإطلاق التالي بصورة رأسية حقيقية.