ربط Agent عبر MCP

اختر طريقة الاتصال الخاصة بك

يعرض FreeLipSync نقطة نهاية MCP عن بعد عند https://freelipsync.com/mcp. فهو يمنح الوكيل نفس إمكانيات إنشاء الفيديو وأرصدة الحساب مثل REST API. يجب أن يكون لديك حساب FreeLipSync مسجل؛ الوصول المجهول غير مدعوم. استخدم أصل staging بدلاً من ذلك عند الاختبار على staging.

يتم دعم كل من تكوين API Key و OAuth. اختر مصدرًا واحدًا لبيانات الاعتماد لكل إدخال خادم. يظل ملف التكوين الموجود وسيلة صالحة للاتصال؛ ليس عليك استخدام OAuth.

أنشئ مفتاحًا وانسخ قيمته الكاملة من نافذة الإنشاء. لا يتطلب OAuth نسخ مفتاح. يدعم كل حساب ما يصل إلى 5 مفاتيح API Key و 5 اتصالات OAuth مستقلة. يستخدم الوصول عبر API Key حصة المفاتيح ولا يشغل حصة اتصالات OAuth. تشترك الطريقتان في رصيد الحساب والنماذج والحدود.

تدفق ترخيص OAuth

1. قم بإضافة HTTPS URL البعيد في عميلك، بدون رأس Authorization أو إعداد API Key.
2. اختر Connect / Authenticate / Sign in، بما يناسب العميل.
3. في المتصفح، قم بتسجيل الدخول إلى حساب FreeLipSync الخاص بك وراجع العميل الطالب والأذونات.
4. قم بإنشاء اتصال جديد (افتراضي)، أو اختر بشكل صريح اتصالًا موجودًا لاستبداله. عادةً ما يتم احتساب التفويض الناجح على جهاز آخر بشكل منفصل.
5. اسمح للوكيل بإنفاق أرصدة واجهة برمجة التطبيقات (API) التي اشتريتها، ثم قم بالتفويض. ارجع إلى العميل وتحقق من الأدوات أدناه.

يمكنك رفض الطلب. إذا تم استخدام جميع فتحات الاتصال 5، فاستبدل أو قم بإبطال الاتصال القديم بشكل صريح في وحدة التحكم Agent؛ الترخيص الجديد لا يطرد الاتصال بصمت. لا يؤدي تحديث الرمز المميز وإعادة توصيل التفويض الحالي إلى إضافة فتحة. يمكن لاتصال OAuth أن ينفق أرصدة حسابك عند إرسال الإنشاء.

توافق العميل OAuth مهم: يدعم FreeLipSync بيانات تعريف هوية العميل المنشورة (CIMD) والعملاء المسجلين مسبقًا، بدلاً من نقطة نهاية التسجيل الديناميكي المفتوحة. استخدم إصدار عميل متوافق أو معرف العميل المعين حيثما يكون ذلك مدعومًا. إذا كان العميل يدعم فقط التسجيل الديناميكي وفشل تسجيل الدخول، فاستخدم أسلوب API Key أو اتصل بالدعم للتحقق من تسجيل العميل.

توافق العميل والاختلافات في OAuth

تسجيل OAuth ومصادقة الرمز المميز منفصلان. يدعم FreeLipSync CIMD أو معرف العميل المسجل مسبقًا، مع none + PKCE أو private_key_jwt. إنه يتفهم مجموعة CIMD الأحدث من الأساليب المدعومة بالإضافة إلى حقل الطريقة الفردية الأقدم. يستخدم العملاء الموقعون مفاتيحهم العامة المنشورة تلقائيًا؛ لا يقوم المستخدمون بتحميل مفتاح خاص.

لا يقدم FreeLipSync التسجيل الديناميكي المفتوح (DCR)، أو المصادقة السرية للعميل، أو منحة client_credentials. إذا كان العميل يحتاج إلى DCR، فاستخدم خيار العميل العام المسجل مسبقًا حيثما كان ذلك متاحًا، أو استخدم تكوين API Key في عميل يدعم رؤوس Bearer المخصصة. احصل على معرف معين وقم بتسجيل رد الاتصال الفعلي قبل تكوينه. يعد API Key ومعرف العميل OAuth بيانات اعتماد مختلفة.

Codex: ملف التكوين أو OAuth

إضافة أو تحرير خادم HTTP بعيد ضمن Plugins → MCPs في Codex؛ تستخدم بعض الإصدارات خوادم Settings → MCP. يدعم إدخال MCP المحلي تكوين API Key وهو منفصل عن إدخال OAuth للمكون الإضافي المستضاف الموصوف أعلاه.

اختر مصدرًا واحدًا لبيانات الاعتماد. تستخدم الأمثلة https://freelipsync.com/mcp. بالنسبة إلى staging، استبدله بـ https://staging.freelipsync.com/mcp وقم بإنشاء المفتاح في حساب staging الخاص بك. مفاتيح الإنتاج و staging غير قابلة للتبديل.

الخيار أ: قم بلصق API Key في إعدادات سطح المكتب

استخدم هذا الخيار عندما لا تريد تكوين متغيرات البيئة. أنشئ مفتاحًا في وحدة التحكم Agent، وانسخ السر الكامل، ثم املأ:

استخدم مسافة واحدة بعد Bearer؛ المفتاح نفسه لا يحتوي على بادئة Bearer. لا تقم بتسمية الرأس FLS_API_KEY أو لصق السر في Bearer token env var. حفظ وإعادة الاتصال؛ إذا كان العميل لا يزال يستخدم التكوين القديم، فأعد تشغيله أو افتح جلسة جديدة.

الإدخال الشخصي المكافئ ~/.codex/config.toml هو:

[mcp_servers.freelipsync]
url = "https://freelipsync.com/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

الخيار ب: توفير API Key من خلال متغير بيئة

Bearer token env var يأخذ اسمًا متغيرًا، وليس سرًا. اضبطه على FLS_API_KEY. يجب أن يكون هذا المتغير موجودًا في بيئة العملية التي تقوم بتشغيل Codex. قيمته هي المفتاح الكامل بدون Bearer ؛ يضيف Codex البادئة.

ملف التكوين الشخصي المقابل هو:

[mcp_servers.freelipsync]
url = "https://freelipsync.com/mcp"
bearer_token_env_var = "FLS_API_KEY"

بالنسبة لـ Codex CLI التي تم إطلاقها من محطة طرفية:

export FLS_API_KEY='YOUR_API_KEY'
codex mcp list
codex
# Inspect /mcp in the new session.

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

Headers ينشئ رؤوس طلب HTTP. Headers from environment variables يقرأ قيم الرأس من متغيرات البيئة الموجودة. لا يقوم أي من الحقلين بإنشاء متغير بيئة النظام. لا يقوم الرأس المسمى FLS_API_KEY بملء إعداد Bearer، ولا يعني العنصر النائب الرمادي مثل MCP_BEARER_TOKEN أن المتغير قد تم تكوينه.

الخيار ج: التفويض في المتصفح باستخدام OAuth

أدخل فقط URL. اترك Bearer token env var و Headers و Headers from environment variables فارغة، بما في ذلك إزالة أي صف Authorization سابق. احفظ، واختر Authenticate / Sign in حيثما يكون ذلك متاحًا، وقم بتسجيل الدخول إلى FreeLipSync وقم بالموافقة على الاتصال. لا يلزم إنشاء أو لصق API Key.

بالنسبة لملف التكوين، احتفظ فقط بما يلي:

[mcp_servers.freelipsync]
url = "https://freelipsync.com/mcp"

أوامر سطر الأوامر:

# Run the next line only if this server name does not exist; otherwise edit it.
codex mcp add freelipsync --url https://freelipsync.com/mcp
codex mcp login freelipsync
codex mcp list

استبدل freelipsync في الأوامر باسم الخادم المحفوظ الخاص بك. تعتبر كتل TOML الثلاث المذكورة أعلاه بدائل؛ احتفظ بإدخال واحد للخادم. قم بإزالة التكوين ذي المفاتيح قبل التبديل إلى OAuth: لا يؤدي تسجيل الدخول إلى إصلاح رأس Authorization غير الصحيح الذي لا يزال قيد التكوين.

تحقق من الاتصال بعد الحفظ

في جلسة جديدة، اسأل: "اتصل بـ FreeLipSync get_capabilities و get_usage للتحقق من النماذج ووحدات الرصيد الخاصة بي. لا تقم بإنشاء مقطع فيديو. " استجابة الحساب الناجحة تؤكد الاتصال؛ اسم الخادم الذي يظهر في القائمة وحده لا يظهر.

بالنسبة إلى HTTP 401,، تحقق من أن URL والمفتاح ينتميان إلى نفس البيئة، والمفتاح مكتمل، والرأس الثابت هو Authorization: Bearer YOUR_API_KEY، ولم يبق أي إعداد Bearer قديم متغير أو Authorization مكرر. باستخدام الخيار B، تحقق أيضًا من بيئة العملية التي تقوم بتشغيل العميل فعليًا.

راجع دليل OpenAI MCP الرسمي ومرجع التكوين للتعرف على تعريفات الحقول.

Claude Code: ملف التكوين أو OAuth

للوصول إلى API Key، ضع هذا الإدخال في تكوين MCP شخصي/محلي أو ادمجه في .mcp.json للمشروع. يتم توسيع متغير البيئة بواسطة Claude Code. احتفظ بالمفتاح الفعلي خارج التكوين المشترك وابدأ Claude Code بمجموعة المتغيرات.

{
  "mcpServers": {
    "freelipsync": {
      "type": "http",
      "url": "https://freelipsync.com/mcp",
      "headers": {"Authorization": "Bearer ${FLS_API_KEY}"}
    }
  }
}

export FLS_API_KEY='YOUR_API_KEY'
claude mcp list

بالنسبة إلى OAuth، قم بإزالة الإدخال ذي المفتاح أو رأس Authorization الخاص به أولاً، وأضف خادم URL فقط HTTP، وقم بالمصادقة عبر /mcp في جلسة Claude Code التفاعلية:

claude mcp add --transport http --scope user freelipsync https://freelipsync.com/mcp
claude
# In Claude Code, run /mcp and choose Authenticate for freelipsync.

استخدم طريقة واحدة في كل مرة. لن يتم إصلاح رأس Bearer غير الصالح الذي تم تكوينه عن طريق تسجيل الدخول من خلال تدفق مختلف. راجع دليل MCP الرسمي Claude Code.

Claude Desktop و Claude web

بالنسبة إلى OAuth، افتح صفحة إدارة Connectors الخاصة بـ Claude، وأضف موصل الويب/البعيد المخصص المسمى FreeLipSync، وأدخل https://freelipsync.com/mcp. اختر تسجيل الدخول واستخدم هوية عميل Claude المنشورة حيثما كان ذلك متاحًا؛ أكمل صفحة ترخيص FreeLipSync. قد تطلب إحدى المؤسسات من مالكها تمكين الموصل أولاً. يجب أن تصل الموصلات البعيدة إلى نقطة نهاية HTTPS عامة؛ لا يمكن الوصول إلى المضيف المحلي من سحابة كلود. راجع دليل الموصل البعيد لكلود.

بالنسبة للمسار الأقدم Claude Desktop لملف التكوين، يحتاج عميل stdio فقط إلى جسر محلي إلى نقطة النهاية البعيدة؛ إن لصق url عن بعد في تكوين stdio ليس كافيًا. بعد تثبيت Node.js / npx، قم بدمج هذا الإدخال في claude_desktop_config.json (افتحه من إعدادات مطور سطح المكتب) وأعد تشغيل سطح المكتب. استبدل العنصر النائب محليًا واحتفظ بهذا الملف الشخصي خاصًا.

{
  "mcpServers": {
    "freelipsync": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://freelipsync.com/mcp",
        "--header", "Authorization:${FLS_AUTH_HEADER}"
      ],
      "env": {"FLS_AUTH_HEADER": "Bearer YOUR_API_KEY"}
    }
  }
}

mcp-remote عبارة عن جسر توافق لجهة خارجية، وليس حزمة FreeLipSync. قم بمراجعة تعليمات الصيانة والإصدار المثبت لديك. تدعم وسيطة الرأس الخاصة بها توسيع البيئة؛ يتجنب التنسيق أعلاه أيضًا المسافات داخل الوسيطة. تفضل دعم HTTP الأصلي للعميل عند توفره. ملف سطح المكتب هذا ليس آلية التكوين لـ Claude web.

Cursor: ملف التكوين أو OAuth

للوصول إلى API Key، استخدم ~/.cursor/mcp.json الشخصي (أو مشروع .cursor/mcp.json يظل خارج التحكم بالمصدر عندما يحتوي على مفتاح). استبدل العنصر النائب محليًا. لا تفترض أن توسيع البيئة من تنسيق عميل آخر يعمل في إصدار Cursor المثبت لديك.

{
  "mcpServers": {
    "freelipsync": {
      "url": "https://freelipsync.com/mcp",
      "headers": {"Authorization": "Bearer YOUR_API_KEY"}
    }
  }
}

بالنسبة إلى OAuth، استخدم نفس الإدخال مع url فقط، مع إزالة كائن الرؤوس. في إعدادات Cursor الخاصة بـ MCP، قم بالاتصال/المصادقة وإكمال ترخيص المتصفح إذا تم عرضه. أعد تحميل العميل أو أعد تشغيله بعد تغيير تكوينه، ثم تحقق من الأدوات في وضع Agent. إذا كان تدفق تسجيل هذا الإصدار غير متوافق، فاستخدم تكوين المفتاح أعلاه. راجع تعليمات MCP الرسمية Cursor.

VS Code و GitHub Copilot

بالنسبة لتكوين VS Code MCP الأصلي، أنشئ .vscode/mcp.json باستخدام كلمة مرور مُدخلة بدلاً من مفتاح حقيقي في الملف:

{
  "inputs": [
    {"type":"promptString","id":"fls-key","description":"FreeLipSync API Key","password":true}
  ],
  "servers": {
    "freelipsync": {
      "type":"http",
      "url":"https://freelipsync.com/mcp",
      "headers":{"Authorization":"Bearer ${input:fls-key}"}
    }
  }
}

بالنسبة إلى OAuth، قم بإزالة inputs وheaders، مع الاحتفاظ بنوع الخادم و URL. ابدأ/توصيل الخادم واتبع مطالبة المصادقة؛ يجب أن يكون تسجيل العميل متوافقًا كما هو موضح أعلاه. حدد أدواته في وضع Agent الخاص بـ Copilot وحاول التحقق من المطالبة أدناه. يستخدم تنسيق VS Code servers، وليس mcpServers لعميل آخر؛ لا يتم دعم المدخلات التفاعلية بواسطة كل مجموعة Copilot أو التكوين المحمول. راجع VS Code MCP مرجع.

تحقق من الأدوات وحاول المطالبة

اسأل وكيلك أولاً: "استخدم FreeLipSync للتحقق من الموديلات المتاحة والرصيد الائتماني. لا تقم بإنشاء فيديو بعد." يجب عليه الاتصال بـ get_capabilities وget_usage، بدون إنفاق وحدات الرصيد. الخادم المدرج في ملف التكوين ليس دليلاً كافيًا على نجاح المصادقة.

ثم حاول: "قم بعمل صورة ناطقة قصيرة Image Fast من الصورة والصوت الخاص بي. احصل على عرض أسعار أولاً وأخبرني بوحدات الرصيد. انتظر تأكيدي قبل الإرسال. إذا لم تتمكن من تحميل ملفاتي المحلية، فأعطني روابط تحميل المتصفح. " حافظ على تمكين موافقة العميل على أدوات الإنفاق.

تحميل الملفات المحلية من وكيل

يوجد مساران للملف المحلي، بالإضافة إلى استيراد HTTPS. لا تقم بتمرير مسار محلي كـ import_asset URL.

• إذا كان العميل يستطيع قراءة الملفات وإرسال HTTP PUT، يستدعي create_asset_upload مع kind وfilename وcontent_type وsize_bytes وidempotency_key. ثم يرفع بايتات الملف الفعلية إلى URL المستلم باستخدام الرؤوس المحددة، ويستدعي confirm_asset_upload. لا ترسل API Key إلى روابط التخزين الموقعة مطلقًا.
• العميل الذي ليس لديه وصول إلى الملف المحلي/HTTP يستدعي create_asset_upload_session لكل صورة/فيديو/صوت. تقوم بفتح browser_upload_url، وتسجيل الدخول إلى نفس حساب FreeLipSync والتحميل في المتصفح. يحتفظ الوكيل بـ asset_id ويستقصي get_asset؛ ليس عليك نسخ المعرف مرة أخرى. لا تشارك تذكرة التحميل علنًا.
• بالنسبة لملف HTTPS عام موجود، يبدأ import_asset مع kind، url، idempotency_key في الاستيراد. انتظر حتى تصبح جاهزة قبل عرض السعر.

لا يتمكن موصل السحابة/URL فقط من الوصول إلى ملفات سطح المكتب لديك ببساطة عن طريق استخدام MCP. على سبيل المثال، يتم تشغيل موصلات Claude البعيدة من السحابة الخاصة به، لذا استخدم روابط تحميل المتصفح عندما لا يتمكن العميل من نقل المرفق الخاص بك إلى URL الموقع.

وحدات الرصيد وإعادة المحاولة وإدارة الاتصال

تستخدم API و MCP المعدلات نفسها: Video Lip Sync / Image Fast يستهلك 1 وحدة رصيد/ثانية؛ Image Max يستهلك 2؛ Image Super / Music Video يستهلك 3. تُقرّب مدة الصوت المتحقق منها إلى الثانية الكاملة الأعلى، بحد أدنى 5 ثوانٍ. يعيد estimate_generation قيمة total_points ومعرّف عرض السعر؛ ويأخذ create_generation ذلك quote_id مع idempotency_key. الرفع وفحص الاستخدام والتقدير لا تستهلك الرصيد. لا يمكن إلغاء إنشاء مقبول؛ وحده فشل المعالجة يعيد المبلغ المحجوز الأصلي كاملًا. راجع فوترة API والتعافي من الأخطاء.

احتفظ بنفس عرض السعر ومفتاح Idempotency بعد تقديم غير مؤكد. احفظ معرف المهمة الذي تم إرجاعه واستفسر عنه؛ لا تطلب من الوكيل "المحاولة مرة أخرى" عن طريق القيام بمهمة أخرى. استقصاء باستخدام poll_after_seconds، والتراجع عن Retry-After، واستخدام list_generations للاستعلام عن عدة وظائف نشطة معًا. تتشارك واجهة برمجة التطبيقات (API) و MCP في مجموعة قراءة الحساب، بينما تشترك نقاط الدخول الثلاثة لموقع الويب/API/MCP في تكرار الإرسال وقدرة تنفيذ الفيديو. يحتوي موقع الويب و API/MCP على بدلات منفصلة للمهمة غير المكتملة: Free 1, Starter 3, Pro 10 في كل مجموعة. تشترك جميع بيانات اعتماد REST/MCP في تجمع API/MCP. راجع لماذا نستخدم API/MCP للحصول على أمثلة.

قم بإلغاء اتصال المفتاح أو OAuth من وحدة التحكم Agent. يؤدي إلغاء المفتاح إلى إيقاف الاستخدام المستقبلي له في كل عميل يشاركه، بما في ذلك REST؛ يؤثر إبطال اتصال OAuth على هذا الاتصال فقط. ولا تؤدي أي من العمليتين إلى إلغاء المهام المقبولة بالفعل. لا يؤدي حذف إدخال عميل محلي وحده إلى إلغاء بيانات الاعتماد على FreeLipSync. استخدم مفاتيح منفصلة أو تفويضات مستقلة عندما تحتاج إلى إبطال منفصل، وليس لزيادة التزامن.

استكشاف الأخطاء وإصلاحها

قد تتغير إعدادات العميل بين الإصدارات. ارجع إلى الوثائق الرسمية المرتبطة بكل عميل للحصول على التعليمات الحالية. هل تحتاج إلى تكامل مباشر مع HTTP؟ اقرأ وثائق واجهة برمجة التطبيقات.