> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> اربط Krea بالوكلاء المتوافقين مع MCP حتى يتمكنوا من اكتشاف النماذج وفحص المخططات وإنشاء الصور أو مقاطع الفيديو من مساحة عملك.

تتيح Krea خادم Model Context Protocol (MCP) مستضافًا للوكلاء ومساعدي البرمجة. استخدمه عندما تريد أن يستدعي عميل متوافق مع MCP خدمة Krea مباشرةً بدلًا من كتابة طلبات API يدويًا.

<Info>
  لست بحاجة إلى مفتاح API للاتصال. أضف `https://api.krea.ai/mcp` بوصفه عنوان خادم MCP، ثم سجّل الدخول باستخدام حساب Krea الخاص بك من خلال تدفق OAuth في عميلك.
</Info>

## تفاصيل الخادم

| الإعداد  | القيمة                    |
| -------- | ------------------------- |
| النقل    | Streamable HTTP           |
| العنوان  | `https://api.krea.ai/mcp` |
| المصادقة | OAuth                     |

تعتمد الفوترة على طريقة المصادقة:

| طريقة المصادقة | مصدر الفوترة                                                  |
| -------------- | ------------------------------------------------------------- |
| OAuth          | وحدات الحوسبة الخاصة بمساحة العمل التي تختارها أثناء الموافقة |
| رمز API        | رصيد API المنفصل الخاص بمساحة عملك                            |

## المصادقة

تستخدم معظم عملاء MCP بروتوكول OAuth تلقائيًا. عندما يطلب منك العميل الاتصال، اتبع تدفق تسجيل الدخول في المتصفح وامنح الإذن لـ Krea.

### اختر مساحة عمل أثناء الموافقة

تتضمن شاشة موافقة OAuth منتقي **مساحة العمل** يعرض كل مساحات العمل التي تنتمي إليها. يتم اختيار مساحة العمل الافتراضية مسبقًا؛ اختر مساحة مختلفة إذا أردت تشغيل جلسة MCP هذه في مكان آخر (على سبيل المثال، مساحة عمل استوديو مشتركة بدلًا من مساحتك الشخصية).

ترتبط مساحة العمل التي تختارها بجلسة OAuth وتحدّد:

* **الفوترة.** تُخصم وحدات الحوسبة من مساحة العمل المختارة، وليس فقط من الحساب الذي سجلت الدخول إليه.
* **نطاق الأصول.** تُحفظ الملفات المرفوعة عبر أدوات مثل `upload_asset` في مساحة العمل المرتبطة، والأدوات التي تتطلب رفعًا (على سبيل المثال، `get_upload_url`) لا تعمل إلا بعد ربط مساحة عمل.

لتبديل مساحة العمل المرتبطة لاحقًا، افصل Krea في عميل MCP الخاص بك وأعد الاتصال — وسترى المنتقي مرة أخرى.

<Note>
  جلسات OAuth القديمة التي أُنشئت قبل إطلاق منتقي مساحة العمل ليس لها ارتباط صريح. تستخدم تلك الجلسات افتراضيًا مساحة العمل الافتراضية لحسابك. أعد الاتصال لربط الجلسة بمساحة عمل محددة.
</Note>

إذا كان عميل MCP الخاص بك لا يدعم OAuth، فيمكنك المصادقة باستخدام رمز API بدلًا من ذلك:

| مفتاح الترويسة  | قيمة الترويسة           |
| --------------- | ----------------------- |
| `Authorization` | `Bearer KREA_API_TOKEN` |

استبدل `KREA_API_TOKEN` برمز من [krea.ai/app/api/tokens](https://www.krea.ai/app/api/tokens). يستطيع مالكو مساحات العمل والمشرفون فقط إنشاء رموز API.

تُفوتر استخدامات رمز API على رصيد API الخاص بمساحة عملك، تمامًا كما هو الحال مع استدعاءات API المباشرة. راجع [مفاتيح API والفوترة](/developers/api-keys-and-billing) للاطلاع على تفاصيل رصيد API.

<Warning>
  خزّن بيانات اعتماد MCP المعتمدة على رمز API بالطريقة نفسها التي تخزّن بها مفاتيح API. لا تُودع ملفات إعداد MCP التي تحتوي على رموز حقيقية في نظام التحكم بالإصدارات.
</Warning>

## Claude Code

شغّل هذا الأمر في الطرفية:

```bash theme={null}
claude mcp add --transport http krea-ai https://api.krea.ai/mcp
```

سجّل الدخول بحساب Krea الخاص بك عندما يطلب منك Claude Code الاتصال. أعد تشغيل Claude Code أو أعد تحميل خوادم MCP بعد إضافة الخادم.

## Codex

1. افتح **Settings** > **MCP servers** في Codex.
2. أضف خادمًا جديدًا.
3. اختر **Streamable HTTP** بوصفه طريقة النقل.
4. الصق عنوان الخادم:

```text theme={null}
https://api.krea.ai/mcp
```

5. احفظ الخادم وسجّل الدخول بحساب Krea عندما يطلب منك Codex الاتصال.

## Cursor

افتح لوحة الأوامر، وابحث عن **Open MCP settings**، ثم أضف هذا الإدخال إلى `mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "krea-ai": {
      "url": "https://api.krea.ai/mcp"
    }
  }
}
```

أعد تشغيل Cursor بعد حفظ الملف، ثم سجّل الدخول بحساب Krea عندما يطلب منك Cursor الاتصال.

## استخدام Krea عبر MCP

بمجرد الاتصال، اطلب من وكيلك سرد نماذج Krea أو فحص مخطط نموذج قبل التوليد. تتطابق معرّفات النماذج مع مسارات API المستخدمة في بقية وثائق المطورين، مثل `image/krea/krea-2/medium` أو `video/google/veo-3.1`.

على سبيل المثال:

```text theme={null}
List the available Krea image models, then generate an image with Krea 2 using a 16:9 aspect ratio.
```

إذا كان النموذج موقوفًا، فإن Krea تُرجع بيانات وصفية للإيقاف من خلال اكتشاف نماذج MCP. راجع [الإيقافات](/developers/deprecations) لإرشادات الترحيل.

## الأدوات

يكشف خادم Krea MCP عن أدوات تُقابل واجهة برمجة التطبيقات العامة. يكتشفها وكيلك تلقائيًا عبر `tools/list`؛ والأكثر شيوعًا منها:

| الأداة             | ما تقوم به                                                                   |
| ------------------ | ---------------------------------------------------------------------------- |
| `list_models`      | سرد نماذج الصور والفيديو المتاحة.                                            |
| `get_model_schema` | فحص مخطط مدخلات النموذج قبل التوليد.                                         |
| `generate`         | إرسال مهمة توليد صورة أو فيديو.                                              |
| `execute_node_app` | تشغيل تطبيق عقدة (node app).                                                 |
| `get_job`          | جلب الحالة الحالية ومخرجات المهمة باستخدام `jobId`.                          |
| `cancel_job`       | إلغاء مهمة قيد التنفيذ وحذفها من قائمة مهامك.                                |
| `get_upload_url`   | طلب عنوان URL موقّع مسبقًا قصير الأجل لرفع ملف محلي لاستخدامه كمدخل للنموذج. |

تتضمن مخرجات أدوات التوليد وتطبيقات العقد `job_id` للمهمة المُرسلة إلى جانب حمولة المهمة. مرّر هذا المعرّف إلى `get_job` لاستطلاع الحالة، أو إلى `cancel_job` لإيقاف مهمة لم تعد بحاجة إليها.

### إلغاء مهمة

تستدعي `cancel_job` خلف الكواليس `DELETE /jobs/{id}` وتُرجع `{ "job_id": "...", "deleted": true }` عند النجاح. لا يسري الإلغاء إلا أثناء وجود المهمة في حالة غير نهائية — راجع [دورة حياة المهمة](/developers/job-lifecycle) للاطلاع على القواعد والتبعات الفوترية (المهام الملغاة لا تُفوتر).

مثال على المطالبة:

```text theme={null}
Cancel job 7f3c9b1a-… because the prompt was wrong.
```

### توفير مدخلات وسائط

أي مدخل نموذج يقبل عنوان URL لوسائط (على سبيل المثال `start_image` أو `image_style_references[].url` أو `reference_images`) يقبل أحد ثلاثة أشكال:

* عنوان URL خارجي — رابط `https://` يمكن الوصول إليه علنًا لملف صورة أو فيديو أو صوت أو نموذج ثلاثي الأبعاد.
* معرّف بيانات base64 — على سبيل المثال `data:image/png;base64,iVBORw0KGgo…`.
* عنوان URL لأصل مرفوع — العنوان المُرجَع بعد رفع ملف محلي إلى Krea.

قوائم عناوين URL المفصولة بفواصل غير مدعومة. مرّر كل مدخل بوصفه حقلًا منفصلًا أو عنصر مصفوفة مستقل.

### رفع ملف محلي باستخدام `get_upload_url`

عندما يكون الملف الذي تريد استخدامه على جهازك المحلي وغير مستضاف في أي مكان بعد، اطلب من وكيلك استدعاء `get_upload_url`. تُرجع الأداة عنوان URL موقّعًا مسبقًا صالحًا لمدة ثلاث ساعات. ثم يُرسل عميلك الملف باستخدام `POST` إلى ذلك العنوان بصيغة `multipart/form-data` مع حقل `file` واحد، ويحتوي جسم الاستجابة على عنوان URL للأصل يمكنك تمريره إلى استدعاء `generate` لاحق.

مثال على التدفق:

```bash theme={null}
# 1. Ask the agent to call get_upload_url through MCP. It returns something like:
#    https://api.krea.ai/public-api/assets/presigned/...

# 2. POST the local file to that presigned URL.
curl -X POST "$UPLOAD_URL" -F "file=@/path/to/image.png"

# 3. The response body contains the asset URL. Use it in the next generate call,
#    for example as start_image or image_style_references[].url.
```

<Info>
  إذا فشل طلب الرفع `POST` بسبب تقييد منفذ الشبكة الصادر، فأضف `api.krea.ai` إلى قائمة النطاقات المسموح بها في عميلك. يُقدَّم عنوان URL الموقّع مسبقًا من المضيف نفسه الذي تُقدَّم منه بقية واجهة برمجة التطبيقات العامة.
</Info>

إذا كان ملفك متاحًا بالفعل عبر عنوان URL عام أو يمكنك تشفيره بوصفه معرّف بيانات base64، فتجاوز `get_upload_url` ومرّر تلك القيمة مباشرة إلى مدخل التوليد بدلًا من ذلك.

## أداة واجهة MCP Apps

تُرفق استدعاءات أدوات التوليد وتطبيقات العقد مورد واجهة [MCP Apps](https://modelcontextprotocol.io/). يعرض عملاء MCP الذين يدعمون MCP Apps أداة تفاعلية لنتيجة المهمة مدمجة مع استجابة الأداة، تتضمن:

* لوحة تحميل بحجم متناسب مع نسبة العرض إلى الارتفاع للمهمة أثناء وضع المهمة في قائمة الانتظار أو معالجتها.
* استطلاع تلقائي لـ `get_job` بحيث تُحدَّث الأداة مع تقدم المهمة، دون أن يستدعي الوكيل `get_job` بنفسه.
* أزرار إجراءات لإعادة محاولة التوليد أو إلغاء المهمة من داخل الأداة.
* شريط مقارنة بملء الشاشة قبل/بعد لنتائج التحسين (enhance).

تُكشف الأداة بوصفها المورد `ui://krea-public-api/job-result-frame` وتُجهَّز تلقائيًا — لا يلزم أي إعداد من جانب العميل. أما العملاء الذين لا يدعمون MCP Apps فيتجاهلون المورد ببساطة ويعودون إلى مخرجات الأداة المُهيكلة.

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

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

| المشكلة                   | الحل                                                                                                                                                                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| فشل المصادقة              | أعد الاتصال بخادم MCP وأكمل تدفق Krea OAuth في متصفحك. إذا كنت تستخدم رمز API، فتأكد من أن الترويسة هي بالضبط `Authorization: Bearer KREA_API_TOKEN` وأن الرمز لم يُلغَ.                                                                         |
| العميل لا يستطيع الاتصال  | تأكد من أن العميل مهيأ لاستخدام Streamable HTTP ويستعمل `https://api.krea.ai/mcp`.                                                                                                                                                               |
| رُفض التوليد بسبب الفوترة | إذا اتصلت عبر OAuth، فتحقق من وحدات الحوسبة في مساحة العمل التي اخترتها أثناء الموافقة — أعد الاتصال إذا كنت بحاجة إلى ربط الجلسة بمساحة عمل مختلفة. إذا اتصلت برمز API، فأضف رصيدًا إلى API على [krea.ai/app/api](https://www.krea.ai/app/api). |
| فشل استدعاء النموذج       | اطلب من وكيلك فحص مخطط النموذج قبل إعادة المحاولة. تستخدم طلبات MCP المدخلات نفسها للنموذج المستخدمة في API.                                                                                                                                     |

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="مفاتيح API والفوترة" icon="key" href="/developers/api-keys-and-billing">
    أنشئ رموز API وأدر رصيد API للطلبات المصادق عليها بالرموز.
  </Card>

  <Card title="بيئة تجريبية تفاعلية" icon="rocket" href="/developers/interactiveexample">
    جرّب الطلبات في تطبيق Krea قبل أن تطلب من وكيل تشغيلها.
  </Card>

  <Card title="الإيقافات" icon="triangle-exclamation" href="/developers/deprecations">
    اطّلع على كيفية كشف MCP لبيانات ترحيل النماذج الوصفية.
  </Card>

  <Card title="واجهات برمجة النماذج" icon="book-open" href="/api-reference/introduction">
    تصفّح مخططات نقاط النهاية ومعلمات النماذج.
  </Card>
</CardGroup>