يقرأ Codex خوادم MCP من ملف config.toml، ويمكنك إضافتها بأمر واحد هو codex mcp add. يعرض هذا المقال الإعدادات الدقيقة للخوادم المحلية والبعيدة، وتسجيل الدخول عبر OAuth، ومهلات الانتظار، وفلاتر الأدوات، إضافة إلى حلول الأخطاء التي تضيّع ساعات من وقتك.
Codex وكيل برمجي قوي بمفرده، لكنه لا يرى إلا ما تقدّمه له: ملفاتك، وصدفتك، وما يعرفه النموذج أصلًا. خوادم MCP تغيّر ذلك. أضف خادمًا واحدًا وسيستطيع Codex الاستعلام من قاعدة بيانات، أو قراءة متعقّب مشكلات، أو البحث في توثيق المكتبات، أو توليد صورة من الأمر النصي نفسه الذي تطلب فيه الشيفرة. لكن الإعداد يعيش في ملف TOML وعدد قليل من خيارات سطر الأوامر، وإعداد خاطئ واحد يعني أن الخادم لن يظهر أبدًا دون أي رسالة تنبيه.
يقدّم هذا المقال إعداد Codex MCP الدقيق للخوادم المحلية والبعيدة، والأوامر التي تكتبه عنك، وحلولًا للأخطاء التي يواجهها الناس أكثر من غيرها. الإعدادات والقيم الافتراضية الواردة أدناه تطابق توثيق OpenAI Codex حتى أكتوبر 2026.
بروتوكول MCP، أي Model Context Protocol، معيار مفتوح يتيح لعميل ذكاء اصطناعي استدعاء الأدوات التي يوفّرها برنامج منفصل. ذلك البرنامج هو الخادم، وCodex هو العميل. ينشر كل خادم قائمة بأدواته، مع أسمائها وأوصافها ومخططات مدخلاتها، ويقرر Codex أثناء المهمة متى يستحق استدعاء إحداها.
بدون الخوادم، يحرّر Codex الملفات ويشغّل أوامر الصدفة. ومعها، تستطيع الجلسة نفسها الاستعلام من قاعدة بيانات الاختبار، أو سحب مواصفات تصميم، أو سؤال فهرس توثيق عن طريقة عمل مكتبة في إصدارها الأحدث، بدلًا من التخمين اعتمادًا على بيانات التدريب.
يدعم Codex نوعين من الخوادم، وكل إعداد تكتبه ينتمي إلى أحدهما.
| النوع | مكان التشغيل | الإعداد المطلوب | مثال شائع |
|---|---|---|---|
| stdio | عملية يشغّلها Codex على جهازك | command | خادم يُشغَّل باستخدام npx أو node |
| Streamable HTTP | خدمة بعيدة يُوصل إليها عبر عنوان URL | url | متعقّب مشكلات مستضاف أو مستضيف شيفرة |
تبدأ خوادم stdio المحلية عند بدء تشغيل Codex، وتتوقف عند خروجه. أما الخوادم البعيدة فتعمل مسبقًا في مكان آخر، لذا يحتاج Codex إلى العنوان فقط، وغالبًا إلى بيانات اعتماد.
💡 نصيحة: ابدأ بخادم أو اثنين. كل أداة تعرضها تضيف إلى ما يقرأه النموذج قبل أن يتصرف، وقائمة الأدوات المزدحمة تجعل اختياراته أقل دقة.
يحتفظ Codex بإدخالات MCP في الملف نفسه config.toml الذي يستخدمه لكل إعداد آخر. لا يوجد ملف MCP منفصل تبحث عنه.
الموقع الافتراضي هو ~/.codex/config.toml. على Windows يشير هذا المسار إلى مجلد .codex داخل ملف تعريف المستخدم. الخوادم المعرّفة هنا متاحة في كل مشروع تفتحه. يقرأ تطبيق ChatGPT على سطح المكتب، وواجهة سطر الأوامر في Codex، وإضافة المحرر كلها هذا الملف نفسه، لذا فالخادم الذي تضيفه مرة واحدة يظهر في الأدوات الثلاث.
يمكنك أيضًا وضع ملف .codex/config.toml داخل مستودع لحصر الخوادم في ذلك المشروع. لا يقرأ Codex هذا الملف إلا في المشاريع الموثوقة، وهذا يمنع أي مستودع يُستنسخ حديثًا من تشغيل أوامر على جهازك بصمت. ملفات المشروع مناسبة للخوادم التي لها معنى داخل قاعدة شيفرة واحدة فقط، مثل قاعدة بيانات موجّهة إلى مخطط التطوير الخاص بذلك التطبيق، كما تتيح لزملائك مشاركة الإعداد عبر نظام التحكم بالإصدارات.
💡 نصيحة: لا ترفع الرموز المميزة إلى المستودع أبدًا. استخدم متغيرات البيئة بالاسم كما هو موضح أدناه، واحتفظ بالقيم في ملف إعدادات الصدفة أو في مدير الأسرار.
أسرع طريقة هي codex mcp add. يكتب إدخال TOML عنك، ما يزيل الأخطاء المطبعية في أسماء الجداول والاقتباس. استخدمه أولًا، ثم افتح الملف للتعديل الدقيق.
كل ما يأتي بعد الشرطتين المزدوجتين هو الأمر الذي سيشغّله Codex:
codex mcp add context7 -- npx -y @upstash/context7-mcp
يسجّل ذلك خادمًا اسمه context7، يُشغَّل عبر npx. لتمرير متغيرات البيئة، ضع خيارات --env قبل الشرطتين المزدوجتين:
codex mcp add postgres --env DATABASE_URL=postgresql://localhost:5432/mydb -- node pg-mcp-server.js
اختر أسماءً قصيرة بحروف صغيرة دون مسافات. يصبح الاسم اسم الجدول في TOML، ويحدّد الخادم في كل قائمة.
تستخدم الخوادم البعيدة --url بدلًا من أمر في النهاية:
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN
--bearer-token-env-var يسمّي متغير البيئة الذي يحتوي على الرمز المميز. لا يُكتب الرمز نفسه على القرص أبدًا، بل اسم المتغير فقط، وهذا أفضل من لصق سرّ داخل ترويسة. صدّر المتغير في الصدفة التي تشغّل Codex:
export GITHUB_PAT_TOKEN="paste-your-token-here"
بعض الخوادم المستضافة تتجاوز الرموز الثابتة وتستخدم OAuth. أضف الخادم بعنوان URL الخاص به، ثم وثّق هويتك:
codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear
يبدأ login تدفق OAuth، عادةً في متصفحك، ويخزّن بيانات الاعتماد الناتجة. عندما يوثّق خادم صلاحيات محددة، أضف --scopes متبوعًا بقائمة مفصولة بفواصل. لحذف بيانات الاعتماد المخزّنة، شغّل codex mcp logout linear.
الواجهة السطرية سريعة، لكن مهلات الانتظار وفلاتر الأدوات والمتغيرات المُمرَّرة تعيش في الملف نفسه. كل إدخال جدول اسمه mcp_servers.<name>، مع شرطة سفلية وصيغة جمع.
هذا ما ينتجه الأمر context7 الذي رأيناه سابقًا:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
هذه هي الإعدادات التي يقبلها خادم stdio:
| الإعداد | مطلوب | وظيفته |
|---|---|---|
command | نعم | البرنامج الذي يشغّل الخادم |
args | لا | الوسائط التي تُمرَّر إلى ذلك البرنامج |
env | لا | متغيرات البيئة المضبوطة لعملية الخادم |
env_vars | لا | متغيرات البيئة الموجودة التي يُسمح بتمريرها |
cwd | لا | مجلد العمل المستخدم عند بدء التشغيل |
env يضبط قيمًا حرفية، بينما env_vars يمرّر متغيرات موجودة أصلًا في صدفتك. فضّل env_vars لأي شيء سري، حتى لا تظهر القيمة في الملف أبدًا:
[mcp_servers.postgres]
command = "node"
args = ["pg-mcp-server.js"]
cwd = "/home/dev/db-tools"
env_vars = ["DATABASE_URL"]
[mcp_servers.postgres.env]
LOG_LEVEL = "info"
تستبدل الإدخالات البعيدة command بالإعداد url:
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_TOKEN"
| الإعداد | مطلوب | وظيفته |
|---|---|---|
url | نعم | عنوان الخادم |
bearer_token_env_var | لا | اسم المتغير الذي يحتوي على رمز Bearer المميز |
http_headers | لا | أسماء ترويسات ثابتة مربوطة بقيمها |
env_http_headers | لا | أسماء ترويسات مربوطة بأسماء متغيرات البيئة |
عندما تريد خدمة ترويسة مخصصة بدلًا من رمز Bearer، استخدم جدولي الترويسات. الجدول الثاني يُبقي الأسرار خارج الملف:
[mcp_servers.docs]
url = "https://docs.example.com/mcp"
[mcp_servers.docs.http_headers]
X-Team = "platform"
[mcp_servers.docs.env_http_headers]
X-Api-Token = "DOCS_API_TOKEN"
يقبل النوعان من الخوادم الإعدادات الاختيارية نفسها:
| الإعداد | القيمة الافتراضية | وظيفته |
|---|---|---|
startup_timeout_sec | 10 | المدة التي ينتظرها Codex حتى يبدأ الخادم |
tool_timeout_sec | 60 | أقصى مدة يُسمح بها لاستدعاء أداة واحدة |
enabled | true | اضبطه على false لإيقاف خادم دون حذفه |
enabled_tools | دون فلتر | قائمة سماح بالأدوات التي يُسمح باستدعائها من Codex |
disabled_tools | دون فلتر | قائمة منع بالأدوات التي يجب ألا يستدعيها Codex |
required | false | اضبطه على true لإفشال بدء التشغيل إذا كان الخادم غير متاح |
يبدو الإدخال المضبوط هكذا. استبدل أسماء الأدوات بالأسماء التي يسردها /mcp لخادمك:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled_tools = ["tool_one", "tool_two"]
قائمة السماح هي الخيار الأكثر أمانًا للخوادم التي تستطيع الكتابة إلى البيانات أو حذفها. استخدم disabled_tools عندما تثق بخادم وتريد فقط حجب أداة أو أداتين خطيرتين. واستخدم required = true في التشغيلات الآلية، حيث ينبغي أن يوقف الخادم المفقود المهمة بصوت مسموع بدلًا من أن يواصل Codex العمل دون بياناته.
💡 نصيحة: اضبط
enabled = falseبدلًا من حذف إدخال تحتاجه أحيانًا فقط. تبقى الإعدادات كما هي، ويكفي تغيير سطر واحد لإعادته.
إضافة الخادم لا تثبت شيئًا حتى يعرض Codex أدواته. نفّذ الفحصين في كل مرة.
في جلسة تفاعلية، اكتب /mcp. يعرض Codex الخوادم المتصلة والأدوات التي يوفّرها كل منها. إذا كان خادمك مفقودًا، أو ظهر دون أدوات، فلا شيء آخر يهم قبل إصلاح ذلك. أعد تشغيل الجلسة بعد تعديل الملف حتى يقرأ Codex الإعدادات الجديدة.
مجموعة codex mcp تدير كل شيء دون فتح محرر:
| الأمر | الغرض |
|---|---|
codex mcp list | عرض الخوادم المهيأة مع حالة المصادقة |
codex mcp get <name> | فحص إعداد خادم واحد |
codex mcp add <name> | تسجيل خادم stdio أو HTTP |
codex mcp remove <name> | حذف إدخال خادم |
codex mcp login <name> | بدء مصادقة OAuth |
codex mcp logout <name> | إزالة بيانات اعتماد OAuth المخزّنة |
أضف --json إلى list أو get عندما يحتاج سكربت إلى قراءة المخرجات. وبمجرد ظهور الخادم، أعطِ Codex مهمة لا يستطيع الإجابة عنها إلا ذلك الخادم، مثل طلب التوقيع الحالي لدالة مكتبة يفهرسها خادم التوثيق لديك.
معظم الإخفاقات ترجع إلى عدد محدود من الأسباب. عالجها بهذا الترتيب.
npx -y يحمّل الحزمة، وغالبًا ما تكون مهلة 10 ثوانٍ قصيرة. ارفع startup_timeout_sec إلى 30 أو أكثر.command بنفسه، لذا يجب أن يكون البرنامج في PATH الخاص بالصدفة التي شغّلت Codex. المسار المطلق يزيل الشك.npx سكربت على Windows، وقد يفشل التشغيل المباشر له. مرّره عبر cmd:[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp"]
required = true أثناء الاختبار حتى يوقف الخادم المعطّل الجلسة بخطأ يمكنك قراءته.bearer_token_env_var وenv_vars يقرآن من بيئة العملية التي شغّلت Codex. المتغير المضبوط في تبويب طرفية آخر، أو في تطبيق سطح مكتب فُتح من الرصيف دون ملف إعدادات الصدفة، لن يراه. تحقق منه بالأمر echo $GITHUB_PAT_TOKEN.codex mcp logout <name> ثم codex mcp login <name> للحصول على جلسة جديدة..codex/config.toml في مشروع غير موثوق يُتخطّى. ثِق بالمشروع، أو انقل الإدخال إلى الملف العام.tool_timeout_sec فوق القيمة الافتراضية البالغة 60 ثانية.غالبًا ما تحتاج جلسات البرمجة إلى صور: صورة رئيسية لصفحة هبوط، أو نموذج منتج، أو مقطع قصير لملف README. تقدّم PicassoIA نماذج التوليد الخاصة بها عبر واجهة برمجية للمطورين وعبر اتصالات MCP، لذا يمكن لإعداد Codex نفسه أن يطلب وسائط دون مغادرة الطرفية.
هذه حقائق تستحق المعرفة قبل أن تربط كل شيء:
https://api.picassoia.com/v1، وتبدأ بيانات الاعتماد بالبادئة pia_sk_.picassoia.com/en/mcp/accounts بعد تسجيل الدخول، ويظهر عنوان الخادم هناك ولا يُنشر على الموقع العام.بمجرد أن تحصل على العنوان، فإعداد Codex يتبع النمط الذي رأيناه سابقًا. إذا منحتك الصفحة عنوان URL بعيد، فسجّله باستخدام codex mcp add picassoia --url <address> وأضف متغير رمز Bearer إذا طلبه. وإذا منحتك أمرًا لتشغيله محليًا، فاستخدم صيغة stdio بدلًا من ذلك. متطلبات الخطة لوصول API وMCP مدرجة في صفحة الأسعار، فتحقق منها قبل أن تبني سير عمل حولها.
قبل أن تؤتمت أي شيء، اختبر أمرًا نصيًا يدويًا لتعرف كيف يبدو الطلب الجيد:
تساعد نماذج المحادثة في عمل الإعداد أيضًا. الصق خطأً مربكًا في GPT 5.6 Sol أو Claude Sonnet 5 واسأل أي إعداد TOML يشير إليه. كلاهما مدرج في PicassoIA لمهام البرمجة، والحصول على رأي ثانٍ لا يكلّف شيئًا قبل أن تعدّل الملف.
صار لديك كل ما يلزم لإعداد Codex MCP يعمل: أماكن الملفات، وأوامر سطر الأوامر، وإعدادات النوعين من الخوادم، وروتين للتحقق، وقائمة قصيرة بالحلول. أضف خادمًا واحدًا، وأكّده بالأمر /mcp، ثم أعطِ Codex مهمة حقيقية.
إذا أردت توظيف ذلك في المرئيات، فافتح PicassoIA Image واكتب أمرك النصي الأول. صف مشهدًا كما يصفه المصوّر، مع الضوء والعدسة والملمس، ثم قارن النتيجة بنسخة من الفكرة نفسها عبر PicassoIA Video. تصفّح الكتالوج الكامل على picassoia.com/en/all-models واكتشف ما يستطيع Picasso IA صنعه لك.
اختر لغتك
