إعداد OpenCode MCP: إضافة الخوادم و OAuth وإصلاح المهلات

تضيف خادم MCP إلى opencode.json، وتعيد تشغيل الطرفية، فلا تظهر الأدوات أبدًا. أو تظهر، ويُفتح تسجيل الدخول عبر المتصفح، ولا يصل رد الاستدعاء أبدًا. أو يعمل كل شيء حتى يفشل أول استدعاء بطيء بخطأ مهلة. هذه الأعطال الثلاثة تفسّر معظم مشكلات OpenCode MCP config، ولكل منها إصلاح قصير وبسيط.

تشرح هذه المقالة الحقول الدقيقة التي يقرأها OpenCode، والأوامر التي تكشف ما الخطأ، والإعدادات التي تُنهي التخمين. المقتطفات تتبع توثيق OpenCode الرسمي لبروتوكول MCP كما جرى التحقق منه في أكتوبر 2026، لذا الصقها كما هي، وغيّر الأسماء والمسارات وعناوين URL فقط.

أين يقرأ OpenCode إعداداته

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

مواقع الإعداد وترتيب الدمج

تعمل صيغتا JSON وJSONC (JSON مع تعليقات). إضافة "$schema": "https://opencode.ai/config.json" في الأعلى تمنح محرّرك الإكمال التلقائي والتسطير الأحمر للأخطاء الإملائية. الأخطاء الإملائية هي السبب الأكثر شيوعًا لتجاهل خادم بصمت، لذا يستحق سطر المخطط ذلك خلال دقائق.

💡 نصيحة: عندما يتصرف خادم بغرابة، تحقّق من الملف العام أولًا. قد يتجاوز إدخال قديم فيه إدخالًا سليمًا في المشروع.

استخدم المتغيرات بدلًا من الأسرار المنسوخة

يستبدل OpenCode عنصرين نائبين في أي مكان من الإعداد. يقرأ {env:NAME} متغير بيئة، ويضمّن {file:path} محتوى ملف. استخدمهما لكل توكن، ليبقى الإعداد آمنًا للإيداع في المستودع.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:TRACKER_TOKEN}"
      }
    }
  }
}

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

المسارات النسبية للملفات تُحسب من مجلد الإعداد، أما المسارات التي تبدأ بـ / أو ~ فهي مطلقة. إذا لم يكن المتغير موجودًا في الصدفة التي شغّلت OpenCode منها، لن يرى الخادم توكنًا صالحًا ويرد بالخطأ 401، وهذا يبدو تمامًا كتوكن خاطئ. صدّر المتغير في الصدفة نفسها، ثم شغّل OpenCode منها.

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

كل شيء يقع تحت حقل واحد أعلى المستوى اسمه mcp. كل عنصر فرعي هو خادم باسم تختاره، ويصبح هذا الاسم بادئة لأدواته، لذا اختر أسماء قصيرة بأحرف صغيرة ودون مسافات.

خادم محلي بأدنى إعداد

الخادم المحلي عملية يبدؤها OpenCode نيابةً عنك، ويتواصل معها عبر الإدخال والإخراج القياسيين.

{
  "mcp": {
    "files": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/dev/projects"],
      "enabled": true,
      "timeout": 15000
    }
  }
}

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

حقلان مطلوبان: "type": "local" وcommand. الجزء الذي يوقع الناس في المشكلات هو أن command مصفوفة من النصوص، بإدخال واحد لكل وسيط، وليس سلسلة نصية واحدة لصدفة. كتابة "command": "npx -y some-server" هي أسرع طريقة للحصول على خادم لا يبدأ أبدًا.

متغيرات البيئة ومجلد العمل

غالبًا ما تحتاج الخوادم المحلية إلى بيانات اعتماد أو مجلد محدد. يمرّر environment المتغيرات إلى العملية الابنة، ويحدد cwd مجلد عملها. المسارات النسبية في cwd تُحسب من مساحة العمل.

{
  "mcp": {
    "reports": {
      "type": "local",
      "command": ["node", "./tools/reports-server.js"],
      "cwd": "./mcp",
      "environment": {
        "API_TOKEN": "{env:REPORTS_API_TOKEN}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

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

خادم بعيد مع ترويسات

الخادم البعيد يعمل أصلًا في مكان آخر، لذا يحتاج OpenCode فقط إلى عنوان، وغالبًا إلى بيانات اعتماد.

{
  "mcp": {
    "docs": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:DOCS_MCP_TOKEN}"
      },
      "oauth": false,
      "timeout": 20000
    }
  }
}

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

ضبط "oauth": false هو الخيار الصحيح لأي خادم يصادق بتوكن ثابت. بدونه يعتبر OpenCode الخطأ 401 إشارة لبدء تسجيل دخول عبر OAuth، وهذا مربك عندما تكون المشكلة الحقيقية توكنًا خاطئًا.

تحقّق من النتيجة باستخدام mcp list

شغّل opencode mcp list بعد كل تعديل. يطبع الأمر كل خادم معرّف وحالته، فتعرف خلال ثانيتين إن كان الخادم متصلًا أم يحتاج إلى مصادقة أم فشل. افعل ذلك قبل أن تفتح جلسة وتتساءل لماذا الأدوات مفقودة.

هذا هو مرجع الحقول الكامل في مكان واحد:

💡 نصيحة: اضبط "enabled": false على الخوادم التي تحتاجها أحيانًا فقط. يبقى الإدخال في الملف، ولا يُحمَّل شيء في جلستك حتى تعيد تفعيله.

إصلاح مشكلات تسجيل الدخول عبر OAuth

الخوادم البعيدة التي تتبع مسار تفويض MCP لا تحتاج تقريبًا إلى أي إعداد. عندما يستقبل OpenCode الخطأ 401، يبدأ OAuth تلقائيًا، ويسجّل نفسه كعميل عبر Dynamic Client Registration (RFC 7591)، ويفتح متصفحك، وينتظر إعادة التوجيه. تُخزَّن التوكنات الناتجة في ~/.local/share/opencode/mcp-auth.json.

كيف يعمل OAuth التلقائي

بالنسبة إلى خادم يدعم ذلك، يتكون الإعداد كله من حقلين وأمر واحد.

1. أضف الخادم باستخدام type وurl فقط.
2. شغّل opencode mcp auth tracker، مع استبدال tracker باسم الخادم لديك.
3. وافق على الطلب في تبويب المتصفح الذي يُفتح.
4. شغّل opencode mcp list وتأكد من أن الخادم يظهر كمتصل.

أربعة أوامر تغطي دورة الحياة كاملة:

عندما يفشل تسجيل دخول كان يعمل الأسبوع الماضي فجأة، يكون السبب غالبًا توكنًا قديمًا أو ملغيًا. شغّل opencode mcp logout <name>، ثم opencode mcp auth <name> مرة أخرى، وستبدأ من الصفر.

العملاء المسجَّلون مسبقًا والنطاقات

بعض المزوّدين يرفضون التسجيل الديناميكي، ويريدون منك تسجيل تطبيق يدويًا. في هذه الحالة، أعطِ OpenCode تفاصيل العميل التي كان سينشئها بنفسه.

{
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:TRACKER_CLIENT_ID}",
        "clientSecret": "{env:TRACKER_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

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

قيمة scope نص واحد تُفصل فيه النطاقات بمسافات، تمامًا كما يوثّقها المزوّد. اطلب أصغر مجموعة تعمل. النطاق الواسع الذي يرفضه المزوّد ينتج صفحة خطأ في تسجيل الدخول لا تقول شيئًا مفيدًا عن النطاق المسبب للمشكلة.

فشل تسجيل الدخول على جهاز بعيد

هذه هي المشكلة التي تستنزف فترة بعد الظهر كاملة. يستمع OpenCode إلى منفذ استدعاء محلي أثناء تسجيل الدخول، وتذكر تقارير المستخدمين أن المنفذ الافتراضي هو 19876. إذا كان OpenCode يعمل على مضيف بعيد عبر SSH، فإن متصفحك على الحاسوب المحمول يعيد التوجيه إلى 127.0.0.1:19876 على الحاسوب المحمول، حيث لا يستمع أحد. تنجح الموافقة، ولا يصل الاستدعاء أبدًا، وينتهي الأمر بانتهاء المهلة.

الحل هو توجيه منفذ من حاسوبك المحمول إلى المضيف البعيد:

ssh -o ExitOnForwardFailure=yes -L 127.0.0.1:19876:127.0.0.1:19876 user@remote-host

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

شغّل opencode mcp auth <name> داخل جلسة SSH تلك، وافتح العنوان المطبوع في متصفحك المحلي، وسيمر الاستدعاء الآن عبر النفق.

تقبل الإصدارات الحديثة أيضًا callbackPort وredirectUri داخل كائن oauth، للمزوّدين الذين يشترطون استدعاءً ثابتًا مسجلًا مسبقًا. يجب أن يستخدم عنوان إعادة التوجيه http:// مع localhost أو 127.0.0.1 أو [::1] ومنفذًا صريحًا. وإذا غيّرت المنفذ، فوجّه المنفذ نفسه. تحقّق من المخطط في محرّرك قبل الاعتماد على أي من الحقلين، لأن الإصدارات الأقدم لن تعرفهما.

إصلاحات المهلات التي تنجح

هناك مهلتان مختلفتان، وخلطهما يضيّع ساعات. الأولى تحدد المدة التي ينتظرها OpenCode حتى يبدأ الخادم ويعرض أدواته. والثانية تحدد المدة التي يمكن أن يستغرقها استدعاء أداة واحدة بعد أن يصبح الخادم جاهزًا.

المهلة الافتراضية عند البدء

حقل timeout بالمللي ثانية، والافتراضي 5000 للخوادم المحلية والبعيدة. خمس ثوانٍ كافية لسكربت صغير. وليست كافية للحزمة npx -y عند بدء التشغيل بذاكرة تخزين مؤقت باردة، لأن الحزمة يجب أن تُنزَّل قبل أن يبدأ الخادم أصلًا. عندها يظهر الخادم كفاشل ولا تُحمَّل أدواته أبدًا.

أصلحه بهذا الترتيب:

1. ارفع الحقل لذلك الخادم وحده. اضبط "timeout": 15000 أو 30000 على الإدخال البطيء، واترك البقية كما هي.
2. أزل عملية التنزيل. ثبّت الحزمة عالميًا باستخدام npm install -g، ثم وجّه command إلى الملف التنفيذي المثبّت. سينخفض زمن البدء إلى جزء من الثانية.
3. اختبر نقطة النهاية للخوادم البعيدة. شغّل curl عادي على العنوان. إذا كان curl بطيئًا أيضًا، فالمشكلة في زمن الشبكة أو في الخادم، وليست في إعدادك.

عندما تنتهي استدعاءات الأدوات عند 60 ثانية

يظهر خطأ مختلف لاحقًا، في منتصف الجلسة: MCP error -32001: Request timed out. هذه مهلة الطلب في مكتبة عميل MCP، والعديد من العملاء المبنيين على TypeScript SDK يعتمدون 60 ثانية كافتراضي. رفع timeout عند البدء لا يغيّر هذه المهلة لاستدعاء أداة قيد التشغيل.

ابحث أولًا في مخطط الإصدار الذي تستخدمه عن إعداد لكل طلب. إذا لم تجد شيئًا، فغيّر الأداة بدلًا من العميل. اجعل الأداة الأولى تُرجع معرّف مهمة فورًا، وأضف أداة ثانية تعرض حالة المهمة. يرسل النموذج الطلب، ويحصل على معرّف، ثم يتحقق من النتيجة لاحقًا، وهو نمط "الإرسال ثم الاستعلام" نفسه الذي تستخدمه واجهات API لتوليد الصور والفيديو للسبب ذاته.

💡 نصيحة: أرسل سجلات الخادم إلى stderr، وليس إلى stdout أبدًا. الخادم المحلي يشارك stdout مع البروتوكول، لذا قد يُفسد سطر console.log طائش واحد المصافحة فيبدو كأنه مهلة.

تشخيص خادم لا يتصل

عندما لا يكون الإصلاح واضحًا، توقف عن تعديل الإعداد واختبر كل طبقة على حدة.

شغّل الخادم يدويًا

انسخ مصفوفة command إلى الطرفية وشغّلها كسطر واحد. الخادم المحلي السليم يبدأ ويبقى صامتًا منتظرًا الإدخال. إذا طبع خطأ، مثل وحدة مفقودة أو مسار خاطئ، فقد وجدت المشكلة دون وجود OpenCode في المعادلة. ثم شغّل opencode mcp debug <name>، الذي يشخّص مشكلات الاتصال و OAuth لذلك الخادم وحده.

بالنسبة إلى خادم بعيد، نفّذ curl -i على العنوان بالترويسات نفسها. الخطأ 401 يعني مشكلة في بيانات الاعتماد، والخطأ 404 يعني مشكلة في المسار، والتوقف يعني مشكلة في الشبكة.

الأخطاء الشائعة وإصلاحها

إبقاء السياق صغيرًا لكل وكيل

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

عطّل عالميًا وفعّل لكل وكيل

تحمل أسماء الأدوات اسم الخادم كبادئة، لذا يبدّل نمط glob خادمًا كاملًا دفعة واحدة. * يطابق صفرًا أو أكثر من الأحرف، و? يطابق حرفًا واحدًا بالضبط.

{
  "tools": {
    "files_*": false,
    "tracker_*": false
  },
  "agent": {
    "builder": {
      "tools": { "files_*": true }
    },
    "planner": {
      "tools": { "tracker_*": true }
    }
  }
}

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

مع هذا الإعداد، لا يرى الوكيل builder سوى أدوات نظام الملفات، ولا يرى الوكيل planner سوى المتتبّع. ولا يدفع أي منهما تكلفة التوكنات الخاصة بقائمة أدوات الخادم الآخر.

كيف تستخدم Claude Sonnet 5

أخطاء الإعداد مطابقة أنماط مملّة: نص حيث يجب أن تكون مصفوفة، ومتغير غير مُصدَّر، ومنفذ لم يوجّهه أحد. هنا يثبت نموذج البرمجة قيمته. يقرأ Claude Sonnet 5 على PicassoIA نصوص الإعداد ومخرجات الأخطاء وحتى لقطات الشاشة، فيمكنك لصق ما تراه وسؤاله عن الخطأ.

1. افتح صفحة النموذج. اذهب إلى Claude Sonnet 5 على PicassoIA وابحث عن مربع الأمر النصي.
2. الصق كتلة mcp الخاصة بك. استبدل كل توكن وسر بعنصر نائب أولًا، ثم أضف مخرجات opencode mcp debug <name>.
3. اضبط مستوى الجهد. الافتراضي low يتجاوز التفكير ويجيب بأسرع وقت. استخدم medium أو high عندما تتفاعل عدة ملفات، مثل إعداد عام يتجاوزه إعداد مشروع.
4. أضف موجّه نظام مرة واحدة. شيء مثل: "أنت تراجع إعدادات MCP في opencode.json. تحقّق من type وcommand وtimeout وoauth. أجب بـ JSON المصحَّح فقط."
5. أرفق لقطة شاشة إن كانت لديك. إدخال الصور يقرأ أخطاء الطرفية. ارفع أقصى دقة للصورة عندما يكون النص في اللقطة صغيرًا.
6. أبقِ max_tokens على 8192. هذا هو الافتراضي، ويكفي تمامًا لبضع كتل إعداد.
7. تحقّق قبل اللصق. راجع كل حقل يقترحه مقابل الجدول أعلاه والوثائق الرسمية.

💡 نصيحة: لا تلصق توكنًا حقيقيًا في أي مربع دردشة. العناصر النائبة مثل TRACKER_TOKEN تمنح النموذج كل ما يحتاجه.

أنشئ صورك الخاصة اليوم

الإعداد ليس سوى نصف ما يستطيع MCP فعله. عندما يستطيع وكيل برمجي استدعاء الأدوات، يستطيع أيضًا استدعاء مولّدات الصور. تعرض PicassoIA مولّداتها عبر MCP، ويوجد عنوان الخادم في صفحة اتصالات MCP في حسابك. أي خادم يتحدث HTTP يتبع نمط الخادم البعيد نفسه من هذه المقالة: type، وurl، وترويسة أو OAuth، وtimeout مناسب.

إذا كنت تفضّل تجاوز الإعداد والاكتفاء بإنشاء الصور، فافتح Picasso IA وجرّب نماذج تحويل النص إلى صورة هذه:

• PicassoIA Image للحصول على نتائج سريعة وعامة
• Seedream 5 Pro للمشاهد التفصيلية الشبيهة بالتصوير الفوتوغرافي
• GPT Image 2 للأوامر النصية التي تتطلب تخطيطًا دقيقًا
• FLUX 2 Pro لملمس حاد وإضاءة طبيعية

اختر واحدًا، واكتب أمرًا نصيًا عن الشيء الذي أعددته للتو، وقارن كيف يفهمه كل نموذج. عشر دقائق من التجربة تعلّمك عن صياغة الأوامر النصية أكثر من ساعة من القراءة، وكل صورة تولّدها تدريب مجاني للصورة التالية.