خادم fal.ai MCP: توليد الصور في Claude Code و Codex

أنت في منتصف ميزة في Claude Code، وصفحة الهبوط تحتاج إلى صورة رئيسية، والروتين المعتاد مُرهِق: تفتح تبويب متصفح، وتختار نموذجًا، وتنتظر انتهاء التصيير، وتنزّل الملف، وتعيد تسميته، ثم تسحبه إلى المستودع. يلغي خادم fal.ai MCP هذا الالتفاف كله. بعد ربطه، يستطيع وكيل البرمجة لديك البحث في كتالوج fal الذي يضم أكثر من 1,000 نموذج توليدي، وقراءة مخطط الإدخال الخاص بالنموذج، والتحقق من السعر، وتشغيل المهمة، وإعادة رابط الصورة دون مغادرة الطرفية.

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

ماذا يفعل خادم fal.ai MCP

MCP، أي بروتوكول سياق النموذج (Model Context Protocol)، هو المعيار المفتوح الذي يتيح لعميل الذكاء الاصطناعي استدعاء أدوات خارجية. خادم fal هو نقطة نهاية مستضافة، لذا لا يوجد شيء لتثبيته أو بنائه أو إبقائه قيد التشغيل على جهازك. يستدعي وكيلك الأدوات، وتشغّل fal النماذج على وحدات GPU الخاصة بها. تنص وثائق fal على طريقة الفوترة بوضوح: تدفع فقط مقابل عمليات تشغيل النموذج التي تُطلقها، وبالسعر نفسه المعتمد في استدعاءات API المباشرة.

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

الأدوات التي يحصل عليها وكيلك

💡 نصيحة: يذكر إعلان المدونة لدى fal تسع أدوات، بينما تسرد صفحة الوثائق الحالية إحدى عشرة. توقّع أن تستمر القائمة في التغيّر، واسأل وكيلك "ما أدوات fal التي تراها؟" مباشرة بعد الربط.

لماذا يتفوق MCP على استدعاءات API الخام

• المخطط أولًا: يقرأ الوكيل معاملات كل نموذج قبل إرسال الطلب، فتُكتشف المدخلات غير الصالحة قبل أن تكلّفك شيئًا.
• السعر أولًا: يحوّل get_pricing السؤال "كم ستكلّف هذه العملية؟" إلى سؤال يجيب عنه الوكيل قبل أن يتصرف.
• لا حاجة إلى شيفرة ربط: لا تثبيت لحزمة SDK، ولا سكربت، ولا حمولة JSON تكتبها يدويًا.
• التسلسل: تستطيع جلسة واحدة أن تكتب أمرًا نصيًا، ثم تولّد الصورة، ثم تحسّن الأمر النصي بناءً على النتيجة.
• كتالوج واحد: الصور والفيديو والصوت وثلاثية الأبعاد ورفع الدقة متاحة خلف عدد قليل من الأدوات نفسها.

طريقتان للاتصال

توثّق fal مسارين، ولكل منهما عنوان URL مختلف. اختر مسارًا واحدًا لكل جهاز بدلًا من إضافة المسارين تحت الاسم نفسه.

مسار OAuth عبر وسيط

تشير الوثائق إلى https://mcp.fal.ai/mcp-relay، وهو يعمل عبر Streamable HTTP ويسجّل دخولك عبر المتصفح. لا تلصق رمزًا في ملف إعدادات أو في محادثة. هذا الخيار الأفضل لحاسوب محمول أو مكتبي يمكنك فيه فتح نافذة متصفح.

مسار رمز الوصول (Bearer Token)

يصف منشور المدونة لدى fal https://mcp.fal.ai/mcp، حيث ترسل رمز fal API الخاص بك في ترويسة Authorization: Bearer. وهذا المسار مناسب للخوادم والحاويات وCI، حيث لا يتوفر متصفح. تقول fal إن الرمز لا يُخزَّن لديها أبدًا، لكن تعامل معه كما تتعامل مع كلمة المرور على أي حال: احتفظ به في متغير بيئة، ولا تضعه أبدًا في مستودع.

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

الإعداد في Claude Code و Codex

أوامر Claude Code

تضيف Claude Code الخوادم البعيدة باستخدام claude mcp add. يتطلب كلا المسارين أمرًا واحدًا. أما مسار OAuth فيكون هكذا:

claude mcp add --transport http fal https://mcp.fal.ai/mcp-relay

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

افتح Claude Code وشغّل /mcp. اختر fal وأكمل تسجيل الدخول عبر المتصفح. يتوافق هذا مع صياغة fal نفسها: أضف الخادم البعيد، ثم وثّق باستخدام /mcp.

أما مسار رمز الوصول فهكذا:

export FAL_TOKEN="paste-your-fal-token-here"

claude mcp add --transport http fal-ai https://mcp.fal.ai/mcp \
  --header "Authorization: Bearer $FAL_TOKEN"

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

اسم المتغير FAL_TOKEN مجرد تسمية، فاختر أي اسم تريده. أضف --scope user لجعل الخادم متاحًا في كل مشروع، أو --scope project لكتابته في .mcp.json مشترك. إذا كان الفريق يشارك هذا الملف، فأشِر إلى المتغير فيه بدلًا من لصق الرمز.

للتحقق من الاتصال، اعرض قائمة الخوادم لديك:

claude mcp list

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

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

أوامر Codex

يحتفظ Codex بإعدادات MCP في ~/.codex/config.toml، ويمكن للمشاريع الموثوقة أن تضيف .codex/config.toml خاصًا بها. يمكنك تعديل الملف يدويًا أو استخدام مجموعة الأوامر codex mcp. يبدو مسار الأمر الواحد هكذا:

codex mcp add fal --url https://mcp.fal.ai/mcp-relay
codex mcp login fal

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

خطوة تسجيل الدخول هي التي تنبّه إليها وثائق fal الخاصة بمسار Codex: أضف الخادم، ثم شغّل codex mcp login fal. يتغير Codex بسرعة، لذلك إذا رُفض أحد الخيارات، فشغّل codex mcp add --help للحصول على الصيغة الحالية.

يؤدي مسار config.toml المهمة نفسها يدويًا:

[mcp_servers.fal]
url = "https://mcp.fal.ai/mcp-relay"

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

في مسار رمز الوصول، أشِر Codex إلى متغير بيئة بدلًا من كتابة الرمز في الملف:

[mcp_servers.fal_token]
url = "https://mcp.fal.ai/mcp"
bearer_token_env_var = "FAL_TOKEN"

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

صدّر FAL_TOKEN في الصدفة قبل أن تبدأ Codex. بعد ذلك، يجب أن يعرض codex mcp list الخادم.

Claude Code مقابل Codex في لمحة

أول طلب لتوليد صورة

أمر نصي يعمل

ابدأ بتحديد دقيق، واجعل الوكيل يعرض خطوات عمله قبل أن ينفق أي شيء:

Use fal to find a fast photorealistic text-to-image model. Show me its price and input schema, wait for my OK, then generate one 16:9 image of a quiet harbor at dawn.

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

تشغّل الجلسة السليمة search_models، ثم get_model_schema وget_pricing، وتتوقف لطلب موافقتك، ولا تستدعي run_model إلا بعد ذلك. تطلب وثائق fal نفسها من المساعدين عرض التكلفة المقدّرة وطلب الموافقة قبل التوليد، لذا يتطابق هذا التدفق مع التصميم المقصود.

احفظ النتيجة في مستودعك. تعيد الأداة رابط URL. اطلب الخطوة التالية في الرسالة نفسها: "نزّل الصورة إلى public/images/harbor.jpg باستخدام curl، وأشر إليها في مكوّن الصورة الرئيسية." يعني الملف المحلي أن صفحتك لا تعتمد على بقاء رابط بعيد حيًا.

المهام القصيرة والمهام الطويلة

ينتظر run_model حتى 45 ثانية افتراضيًا، وهذا مناسب لمعظم نماذج الصور. أما الأعمال الأبطأ، مثل الفيديو أو رفع الدقة الثقيل، فتُرسل إلى قائمة الانتظار:

1. submit_job يبدأ العمل ويعود فورًا.
2. check_job يعرض الحالة.
3. get_job_result يجلب المخرجات عند انتهاء المهمة.
4. cancel_job يوقف مهمة بدأتها عن طريق الخطأ.

أخبر الوكيل بالوضع الذي تريده. تعمل عبارة "أرسل هذه كمهمة وتحقق منها كل 20 ثانية" جيدًا للفيديو.

اجعل الإنفاق متوقعًا

السعر أولًا، ثم التشغيل

ضع القاعدة في المكان الذي يقرأها فيه الوكيل في كل جلسة: CLAUDE.md لـ Claude Code، وAGENTS.md لـ Codex.

fal.ai rules:
- Call get_pricing before every run_model or submit_job.
- Show the estimated cost and wait for my approval when it is above $0.50.
- Never generate more than four images per request without asking.

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

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

انتبه لحدود التزامن

تذكر fal أن خادم MCP يلتزم بحدود التزامن نفسها المعتمدة في استدعاءات API المباشرة. إذا طلبت اثني عشر تنويعًا دفعة واحدة، فتوقّع أن ينتظر بعضها في قائمة انتظار. الدفعات المكونة من ثلاثة أو أربعة عناصر تكتمل أسرع، وتكون أسهل في المراجعة.

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

بدائل الخادم المُستضاف

الخادم المُستضاف ليس الطريقة الوحيدة للوصول إلى fal من وكيل برمجي، وfal ليست الخلفية الوحيدة التي تستحق الربط.

خوادم المجتمع على GitHub

يُثبَّت الأول كإضافة لـ Claude Code:

/plugin install fal-ai@raveenb/fal-mcp-server

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

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

Platform MCP للقراءة فقط

تشحن fal أيضًا Platform MCP منفصلًا على https://api.fal.ai/v1/mcp/platform. وهو للقراءة فقط بشكل صارم، وأدواته البالغ عددها 16 مخصصة لإدارة حسابك: تطبيقات serverless، وسجل الطلبات، والسجلات، والتحليلات. يستخدم مخطط تفويض مختلفًا عن الخادم الرئيسي، لذلك لا تعيد استخدام الترويسة بينهما أبدًا. وهو ليس أداة صور، لكن يمكنك ربط الاثنين في الوقت نفسه.

موصّل PicassoIA MCP كخيار ثانٍ

إن أردت سير العمل نفسه مع الوكيل على خلفية مختلفة، فإن PicassoIA يشغّل موصّل MCP خاصًا به. داخل Claude يعرض تسع أدوات: generate_image، وedit_image، وgenerate_video_picassoia، وgenerate_video_seedance، وget_generation، وlist_generations، وcancel_generation، وlist_models، وget_account.

المهام غير متزامنة. يعيد استدعاء التوليد predict_id بمجرد أن تقبل وحدة GPU المهمة، ثم تستعلم عبر get_generation بعد التأخير المقترح حتى تصبح الحالة نجاحًا أو فشلًا. يخدم الموصّل أربعة نماذج: PicassoIA Image، وPicassoIA Image Editor Pro، وPicassoIA Video وSeedance 2.5 Lite، والاثنان الأخيران ينتجان فيديو. يسمح الحساب بخمس تنبؤات متزامنة، مشتركة بين كل الاتصالات.

💡 نصيحة: يذكر وصف الموصّل نفسه أن التوليدات على نماذج GPU الخاصة بـ PicassoIA مجانية في خطتي Infinite وWonder. تحقق من صفحة التسعير لمعرفة ما تتضمنه خطتك قبل أن تبني سير عمل حولها.

نماذج تستحق الاستدعاء حسب المهمة

أيًّا كان الخادم الذي تستخدمه، يعتمد النموذج المناسب على المهمة. هذه النماذج هي التي أجربها أولًا، وكلها متاحة في كتالوج PicassoIA:

نموذج النص مهم أيضًا، لأنه يكتب الأمر النصي الذي يتلقاه نموذج الصور. يوجد Claude Sonnet 5 وGPT 5.6 Sol في كتالوج PicassoIA، لذلك يمكنك اختبار كتابة الأوامر النصية جنبًا إلى جنب قبل أن تلتزم بأحدهما.

أي مسار يناسبك؟ يضع هذا الجدول الخيارات الثلاثة جنبًا إلى جنب:

دورك الآن في التوليد

ربط خادم يستغرق خمس دقائق. أما اختيار النموذج المناسب فيحتاج إلى بضع تجارب، وهذا الجزء أمتع في المتصفح. افتح Picasso IA، وتصفح قائمة النماذج الكاملة، وشغّل أمرًا نصيًا واحدًا عبر نموذجين أو ثلاثة جنبًا إلى جنب. ابدأ بـPicassoIA Image، المدرج كمولّد غير محدود لتحويل النص إلى صورة، ثم جرّب Flux 2 Pro وSeedream 4.5 بالصياغة نفسها.

عندما تعرف النموذج الذي يمنحك المظهر الذي تريده، أعد هذا الاختيار إلى Claude Code أو Codex واكتبه في ملف القواعد لديك. عندها يتوقف وكيلك عن التخمين، وتبدأ كل صورة رئيسية في مشروعك القادم من نموذج اخترته عن قصد.