خوادم MCP في Codex CLI: الإضافة والتكوين والمصادقة
خوادم MCP تمنح Codex أدوات جديدة: وثائق محدثة، قاعدة بياناتك، مستودعاتك على GitHub. تجري هذه الجولة codex mcp add لخادم stdio محلي، وتنتقل إلى خادم بعيد عبر --url وOAuth، وتفحص مدخلات config.toml وراء كليهما، وتُظهر الفحوص التي تثبت أن الخادم يعمل فعلًا.
TL;DR
- يقرأ Codex خوادم MCP من ~/.codex/config.toml (عام) أو .codex/config.toml (مشروع). كل مدخل جدول [mcp_servers.<name>] بـcommand/args لخوادم stdio المحلية أو url للبعيدة.
- codex mcp add context7 -- npx -y @upstash/context7-mcp يثبّت خادم stdio دون لمس الملف؛ وcodex mcp add <name> --url https://mcp.example.com/mcp يسجّل خادمًا بعيدًا.
- تُصادق الخوادم البعيدة في المتصفح عند أول اتصال (يطبع Codex Detected OAuth support ويفتح شاشة الموافقة)، أو لاحقًا عبر codex mcp login <name>.
- تحقق عبر /mcp داخل الواجهة النصية أو codex mcp list في الصدفة. كما يحافظ Codex 0.160.1 على SYSTEMROOT وTEMP وTMP عند إطلاق خوادم stdio بعيدة بمتغيرات بيئة بعيدة.
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
القناة: Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
القناة: Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
القناة: Snyk9:14
Connect Codex to an MCP server — official documentation
الوثائق الرسمية: developers.openai.com/codex
كل أمر وكل مسار ملف وكل مفتاح تكوين في هذه الصفحة مدقّق مقابل وثائق Codex MCP الرسمية؛ والفيديوهات أعلاه هي المصدر البصري والمعرفي، بما فيها شاشات موافقة OAuth وقائمة MCP في تطبيق سطح المكتب.
تُنسب لقطات الشاشة إلى صانعيها بروابط مباشرة إلى الطوابع الزمنية الدقيقة. لا تُستخدم لقطات للوجوه.
إضافة خوادم MCP إلى Codex خطوة بخطوة
الجزء 1 — خادم stdio الأول
- 1
اختر خادمًا من وثائق MCP الرسمية
افتح developers.openai.com/codex/mcp — وثائق Codex نفسها تحفظ صيغة الأوامر محدثة، وتتشارك الواجهة النصية وإضافة البيئة المتكاملة هذا التكوين. تسرد الوثائق خوادم جاهزة لتجربتها أولًا: Context7 لوثائق المكتبات الحية، وFigma، وGitHub وغيرها. هناك مئات خوادم MCP؛ لاختبار أول اختر شيئًا للقراءة فقط مثل Context7.
صفحة Connect Codex to an MCP server الرسمية، بصيغة codex mcp add ومثال Context7 جاهز للنسخ.شاهد عند 0:20 - 2
ثبّته بـcodex mcp add
انسخ المثال وشغّله في طرفيتك: codex mcp add context7 -- npx -y @upstash/context7-mcp. كل ما بعد الشرطة المزدوجة هو الأمر الذي يطلق عملية الخادم. يرد Codex بـ"Added global MCP server 'context7'" — أي أنه دخل تكوين مستخدمك وصار متاحًا في كل مشروع.
أمر واحد دون تحرير ملفات: تؤكد الواجهة إضافة الخادم إلى التكوين العام.شاهد عند 0:45 - 3
انظر ماذا كتبت الواجهة في config.toml
codex mcp add مجرد مولّد لملف ~/.codex/config.toml. افتح الملف وستجد [mcp_servers.context7] بـcommand = "npx" وargs = ["-y", "@upstash/context7-mcp"]. يمكن كتابة المدخلات يدويًا أيضًا: أضف جدول env لمفاتيح API، أو اضبط startup_timeout_sec (الافتراضي 10) وtool_timeout_sec (الافتراضي 60) للخوادم البطيئة. والتحرير اليدوي هو بالضبط المسار الذي تسلكه فيديوهات Snyk وNet Ninja في بطاقة المصادر.
- 4
أطلق Codex وتحقق عبر /mcp
شغّل codex في مشروعك واكتب /mcp. تسرد لوحة MCP Tools كل خادم مُكوَّن بحالته وبأمر إطلاقه الدقيق وبالأدوات التي يعرضها — يعرض Context7 query_docs وresolve-library-id. أي شيء غائب هنا يعني أن المدخل وقع في الملف الخطأ أو فشل في الإقلاع.
لوحة /mcp داخل واجهة Codex النصية: context7 مفعّل وأداتاه مدرجتان بالاسم.شاهد عند 1:05
الجزء 2 — استخدمه ثم انتقل إلى البعيد
- 5
اصنع مطالبة تستخدم الخادم فعلًا
تُستدعى أدوات MCP عند الحاجة، فاطلب شيئًا يحتاجها: "استخدم Context7 للتحقق من وثائق إعداد Tailwind CSS الحالية". يحلّ Codex المكتبة ويجلب الوثائق عبر خادم MCP ويستشهد بالمصادر في جوابه. مشاهدة نداءات الأدوات تمرّ أمامك هي دليلك على عمل الخادم من طرف إلى طرف.
جواب Codex يستشهد بعناوين وثائق Context7 الدقيقة التي جلبها عبر خادم MCP.شاهد عند 1:30 - 6
أضف خادمًا بعيدًا عبر --url
كثير من المزودين يستضيفون خادم MCP عن بُعد أيضًا — بلا عملية محلية وبلا npx. سجّل واحدًا بـcodex mcp add context7 --url https://mcp.context7.com/mcp. يكتشف Codex دعم OAuth تلقائيًا ويطبع "Detected OAuth support. Starting OAuth flow..." ويفتح متصفحك للتفويض. وفي config.toml المدخل مجرد url = "https://mcp.context7.com/mcp" تحت [mcp_servers.context7].
التدفق البعيد كاملًا في طرفية واحدة: إضافة --url، واكتشاف OAuth، ورابط التفويض، ثم Successfully logged in.شاهد عند 2:22 - 7
وافق على شاشة موافقة OAuth
يسأل المتصفح إن كان يحق لـCodex الوصول إلى حسابك بالنيابة عن المزود. راجع النطاقات المطلوبة وانقر Allow، وتؤكد الطرفية "Successfully logged in". وللخوادم بلا تدفق OAuth، صادق منفصلًا بـcodex mcp login <name>؛ وخوادم التوكنات تأخذ بدلًا منها bearer_token_env_var يشير إلى متغير بيئة.
شاشة موافقة Context7: راجع النطاقات التي يطلبها Codex ثم Allow.شاهد عند 2:02 - 8
احصر خادمًا في مشروع واحد بـ.codex/config.toml
الخوادم التي لا معنى لها إلا في مستودع واحد — مثل DBHub، خادم stdio يتكلم مع قاعدة بياناتك — مكانها تكوين المشروع. أنشئ مجلد .codex في المستودع وأضف config.toml بمدخل [mcp_servers.dbhub] ومرّر سلسلة اتصالك عبر الوسيطة --dsn (عدّلها من مثال Postgres في الوثائق إلى MySQL أو ما تشغّل). اعمل commit ليحصل زملاؤك على الخادم نفسه؛ ويجب أن يكون المجلد مشروعًا موثوقًا ليُحمَّل.
.codex/config.toml لمشروع: يشغَّل DBHub عبر stdio بـDSN قاعدة بيانات المستودع في الوسائط.شاهد عند 3:30
الجزء 3 — خوادم حقيقية وتحكم ما بعد اليوم الأول
- 9
استعلم قاعدة بياناتك عبر أدوات MCP
مع DBHub مُكوَّنًا، اسأل Codex عن قاعدة البيانات: "اعثر على قاعدة بيانات Petco واشرح الجداول"، ثم "ما المنتج الأكثر مبيعًا؟". يستدعي Codex أدوات describe_table وexecute_sql للخادم، ويطلب الإذن قبل تنفيذ SQL، ويجيب بأرقام حقيقية من بياناتك. هذه أسرع طريقة لتنقيح المخططات والتحقق من البيانات أثناء العمل على الخلفية.
شغّل Codex أداة execute_sql في dbhub وأجاب بأكثر المنتجات مبيعًا وإيراداتها.شاهد عند 4:40 - 10
اربط GitHub بخادمه البعيد لـMCP
يوثّق ملف README لمشروع github/github-mcp-server إعداد Codex: أضف مدخل [mcp_servers.github] بقيمة url = "https://api.githubcopilot.com/mcp/"، ثم صادق إما عبر OAuth أو بتصدير رمز وصول شخصي كمتغير بيئة (أنشئ PAT دقيق الصلاحيات من GitHub Settings ثم Developer settings، بمنح Administration وContents). والخوادم البعيدة أولًا مثل هذا وخادم Figma MCP يسيران بالنمط نفسه كالخطوة 6.
دليل تثبيت خادم MCP لـGitHub: مدخل Codex CLI مع ملاحظة مصادقة OAuth/PAT.شاهد عند 5:22 - 11
أعد الإطلاق وشغّل الأدوات في العمل
أعد تشغيل codex وراقب اللافتة: "Starting servers (0/3): context7, dbhub, github". الآن تكفي تعليمة واحدة مثل "اعمل Fork لمستودع openai/codex إلى حسابي" — يختار Codex أداة fork من GitHub ويطلب الموافقة وينفذ. بلا إعداد لكل مهمة: الأدوات ببساطة جزء من كل جلسة من الآن.
- 12
أدر الخوادم بـcodex mcp list وتطبيق سطح المكتب
يطبع codex mcp list كل خادم مُكوَّن من الصدفة؛ وإزالة واحد تعني حذف كتلته من config.toml وإعادة تشغيل الأمر للتأكد. يقرأ تطبيق سطح المكتب وإضافة البيئة المتكاملة الملف ~/.codex/config.toml نفسه، فتظهر الخوادم المثبتة هنا في صفحة Settings ثم MCP servers في تطبيق سطح المكتب بمفاتيح تشغيل وإيقاف.
إعدادات خوادم MCP في تطبيق Codex لسطح المكتب: context7 وdbhub وgithub بمفاتيح تبديل، مع خوادم موصى بها.شاهد عند 7:30
stdio محلي مقابل خوادم MCP بعيدة في Codex
كلا النوعين يسكن جداول [mcp_servers.*] نفسها ويظهر في لوحة /mcp نفسها — والفرق في مكان تشغيل الخادم وكيفية مصادقته. اختر لكل خادم، لا لكل مشروع.
- 1stdio محلي: يطلق Codex عملية بنفسه بـcommand وargs — عادة npx أو ملف تنفيذي. يعمل على جهازك فيصل إلى خدمات localhost مثل قاعدة تطوير (وهكذا استعلم DBHub عن MySQL في الجولة)، لكنك تزوّد بيئة التشغيل والتحديثات.
- 2بعيد: يتكلم Codex مع url مستضاف عبر HTTP قابل للبث. لا عملية للاحتفاظ بها حية والمصادقة مركزية — OAuth افتراضيًا، أو bearer_token_env_var وhttp_headers لإعداد التوكنات. ومثال الوثائق ذاته هو [mcp_servers.figma] بقيمة url = "https://mcp.figma.com/mcp".
- 3stdio منفَّذ بعيدًا: حل وسط تجريبي. ضبط experimental_environment = "remote" على مدخل stdio ينقل تنفيذه إلى منفّذ بعيد، وenv_vars يقرر أي المتغيرات تسافر — بما فيها المدخلات الموسومة source = "remote". وهذا هو المسار الذي قرّبه Codex 0.160.1.
- 4النطاق: يكتب codex mcp add دائمًا في ~/.codex/config.toml العام؛ وخوادم المشروع تذهب إلى .codex/config.toml داخل المستودع (للمشاريع الموثوقة فقط). عام للأدوات المرغوبة في كل مكان، ومشروع لكل ما يحمل بيانات اعتماد خاصة بالبيئة.
- 5أدوات تحكم تنطبق على كليهما: startup_timeout_sec (الافتراضي 10) وtool_timeout_sec (الافتراضي 60) للخوادم البطيئة، وenabled/disabled_tools للسماح بقائمة بيضاء بما يستدعيه Codex، وrequired = true إن كان على الخادم القيام وإلا رفض Codex الإقلاع.
افتراض عملي: خوادم الوثائق للقراءة فقط مثل Context7 يمكن أن تكون عامة؛ وكل ما يمس بيانات اعتماد أو بيانات — DBHub وGitHub بـPAT — مكانها تكوين المشروع حيث يُراجَع ويُلغى مع المستودع.
مُكوَّن لكنه لا يعمل: المشتبه بهم المعتادون
معظم إخفاقات MCP في Codex مشاكل نطاق أو مهلة أو مصادقة — بهذا الترتيب. امش هذه القائمة قبل لمس الخادم نفسه.
- 1الخادم غائب عن /mcp: تحقق من أي ملف عدّلت. المدخلات العامة في ~/.codex/config.toml؛ ومدخلات المشروع في .codex/config.toml وللمشاريع الموثوقة فقط. تشغيل codex mcp list من الصدفة يُظهر ما يراه Codex فعلًا.
- 2الخادم يتجاوز المهلة عند الإقلاع: startup_timeout_sec الافتراضي 10 ثوانٍ، وتنزيل npx بارد لحزمة كبيرة قد يتجاوزها بسهولة. ثبّت الحزمة مسبقًا أو ارفع startup_timeout_sec للمدخل.
- 3نداءات الأدوات تفشل بـ401/403: بيانات الاعتماد غائبة أو منتهية. شغّل codex mcp login <name> لخوادم OAuth، أو اضبط bearer_token_env_var وصدّر المتغير. بعد الإصلاح ينبغي أن تُظهر /mcp الخادم مفعّلًا من جديد.
- 4خادم stdio بعيد ينهار بأخطاء Windows غريبة: قبل 0.160.1 كان إطلاق خادم MCP stdio بعيد بمتغيرات بيئة بعيدة مضبوطة صراحة قد يفقده SYSTEMROOT وTEMP وTMP فيكسر بيئة إقلاع منفّذ Windows. حدّث إلى 0.160.1 أو أحدث.
- 5الخادم يقوم لكن الأجوبة خاطئة أو فارغة: كثير من الخوادم المستضافة يحتاج مفتاح API خاصًا به حتى عبر OAuth — Context7 مثلًا يريد مفتاح API يُمرَّر عبر env. راجع وثائق المزود لاسم env الدقيق وأضفه إلى جدول env للمدخل.
رافعتان نافعتان أثناء التنقيح: اضبط required = true لخادم تعتمد عليه فلا يقوم Codex أبدًا بصمت بدونه، وenabled = false لإطفاء واحد دون حذف تكوينه.