Karzoun Docs

يحوّل MCP المستضاف مساحة عمل كرزون إلى أدوات حية لوكلاء الذكاء الاصطناعي السحابيين — نفس عمليات GraphQL التي تستخدمها في ساحة التجربة، معروضة كأدوات MCP مسماة يمكن لنموذج اللغة استدعاؤها نيابة عنك. استخدم هذا الدليل عندما يعمل تطبيق الذكاء الاصطناعي في السحابة (Claude.ai، Manus، ChatGPT، Cursor عن بُعد) ويجب أن يصل إلى كرزون عبر HTTPS، وليس عبر npx على جهازك.

افتح المطوّر ← إعداد MCP في كرزون (/developer/mcp-setup) للحصول على عنوان نقطة النهاية الخاص بمستأجرك ومثال curl لـ initialize جاهز للنسخ.

تفاصيل اتصالك

اجمع هذه مرة واحدة قبل ربط أي عميل:

الحقل	القيمة
عنوان MCP	`https://{subdomain}.api.karzoun.chat/mcp`
ترويسة المصادقة	`x-app-token: YOUR_APP_JWT`
النقل	Streamable HTTP (POST + بث GET اختياري)
مصدر الرمز	المطوّر ← التطبيقات — دليل المصادقة

# Quick sanity check (save mcp-session-id from response headers)
curl -sD - -X POST 'https://YOUR.api.karzoun.chat/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'x-app-token: YOUR_TOKEN' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

المصافحة الكاملة: MCP المستضاف.

لا تلصق رموز التطبيقات في إضافات المتصفح، أو إعدادات ChatGPT المشتركة، أو الشيفرة من جهة العميل. اتصل من مضيف ذكاء اصطناعي موثوق أو من خلفيتك. راجع الأمان.

ما الذي تفتحه

يعرض كرزون أكثر من 75 أداة مربوطة 1:1 بواجهة GraphQL العامة. لا يحتاج الوكيل إلى اختراع صياغة الاستعلام — يستدعي الأدوات باسم العملية (customers، tasksAdd، webhooks، …). تصفّح القائمة الكاملة: كتالوج الأدوات.

حسب المجال

المجال	أمثلة أدوات	ما يمكن للوكيل فعله
جهات الاتصال وCRM	`customers`، `companies`، `tags`، `tagsTag`	البحث عن الأشخاص، تقسيم القوائم، تطبيق الوسوم
صندوق الوارد	`conversations`، `conversationMessageAdd`	قراءة المحادثات، صياغة أو إرسال ردود (ضمن نطاق التطبيق)
المهام	`tasks`، `tasksAdd`، `tasksBoards`	سرد العمل، إنشاء متابعات، فحص اللوحات
خطافات الويب	`webhooks`، `webhooksAdd`	تسجيل اشتراكات الأحداث الصادرة
قاعدة المعرفة	`knowledgeBaseSearch`، `knowledgeBaseArticles`	تأصيل الإجابات في محتوى المساعدة لديك
التطبيقات	`apps`، `appsAdd`	فحص أو تدوير بيانات اعتماد التكامل (نطاق إداري)

أوامر تُظهر القوة

بعد الاتصال، جرّب طلبات باللغة الطبيعية مثل:

“List my 10 most recently updated customers and summarize their tags.”
“Find open tasks assigned to me on the Sales board and group by due date.”
“Search the knowledge base for return policy and draft a short customer reply.”
“Show webhook subscriptions for customer events — which URLs are active?”
“Find the conversation with alice@example.com and summarize the last 5 messages.”

اربط MCP مع أنماط الوكلاء حتى يقرأ النموذج قبل أن يعدّل.

قريبًا: تسجيل شاشة — ربط MCP المستضاف، ثم تشغيل بحث CRM + سير عمل وسوم في أمر واحد.

اختر العميل المناسب

العميل	stdio محلي	`/mcp` مستضاف	المصادقة التي يتوقعها كرزون
Cursor	نعم (موصى به للتطوير)	نعم	ترويسة `x-app-token`
Claude Desktop	نعم	عن بُعد عبر واجهة Connectors	ترويسة أو OAuth (حسب العميل)
Claude.ai	—	نعم	عنوان موصّل مخصص؛ راجع ملاحظة المصادقة أدناه
Manus	—	نعم	HTTP + مفتاح API / ترويسات مخصصة
ChatGPT Apps	لا	نعم (عن بُعد فقط)	غالبًا OAuth 2.1 — راجع التحفظ
Claude Code	—	نعم	نقل HTTP + ترويسات
خلفيتك الخاصة	—	نعم	`x-app-token` في كل طلب

قاعدة عامة: إذا أتاح العميل تعيين ترويسات HTTP مخصصة، فإن MCP المستضاف لكرزون يعمل اليوم. إذا كان العميل يدعم فقط اكتشاف OAuth (شائع في ChatGPT Apps)، فتحتاج إلى وكيل وسيط صغير أو وكيل خلفية حتى يتوفر OAuth على كرزون.

Claude.ai

يدعم Claude على الويب موصّلات MCP عن بُعد مخصصة (Settings → Connectors → Add custom connector).

أنشئ رمز تطبيق

في كرزون: المطوّر ← التطبيقات → أنشئ تطبيقًا بالصلاحيات التي يحتاجها وكيلك (ابدأ للقراءة فقط: العملاء، الوسوم، المهام).

أضف الموصّل

افتح Claude Connectors (أو Admin → Connectors على Team/Enterprise).
انقر Add custom connector.
Server URL: https://{subdomain}.api.karzoun.chat/mcp
إذا عرضت الواجهة حقول مصادقة Advanced ودعم خطتك بيانات اعتماد ثابتة، فضّل التوجيه عبر عميل يدرك الترويسات (Cursor عن بُعد، Manus، أو خلفيتك) حتى يُوثَّق OAuth لكرزون.

فعّل في المحادثة

استخدم قائمة + في محادثة → Connectors → فعّل كرزون لتلك المحادثة.اختبر: “Using Karzoun tools, run currentUser and list my first 5 tags.”

Claude Desktop للبرمجة المحلية ما زال الأفضل مع stdio. الموصّلات عن بُعد في Claude.ai لجلسات السحابة — لا تضف عنوان HTTPS إلى claude_desktop_config.json؛ استخدم واجهة Connectors بدلًا من ذلك.

Manus

يدعم Manus خوادم MCP مخصصة عبر HTTP — ملاءمة قوية لكرزون المستضاف لأنك تستطيع الإشارة إلى عنوان /mcp عام وتزويد بيانات الاعتماد.

افتح Custom MCP

Settings → Integrations → Custom MCP (أو + Add custom MCP → Direct configuration).

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

الحقل	القيمة
Name	`Karzoun` (أو اسم مساحة عملك)
Transport	`HTTP` / Streamable HTTP
Server URL	`https://{subdomain}.api.karzoun.chat/mcp`
Authentication	API key / Bearer / custom — اربطه بـ `x-app-token` إذا عرضت الواجهة حقل ترويسة مخصصة

إذا كان Manus يوفّر حقل API key واحدًا فقط ويرسل Authorization: Bearer، فاستخدم وكيلًا عكسيًا رفيعًا على بنيتك يترجم Authorization: Bearer <token> → x-app-token: <token> (متقدم؛ أبقِ الوكيل خاصًا).

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

يتحقق Manus من الخادم ويعرض الأدوات المكتشفة. اذكر كرزون في الأوامر:“Pull my top 10 customers by last updated date and create a Manus doc summarizing their tags.”المرجع الرسمي: وثائق Manus custom MCP.

ChatGPT Apps والموصّلات

تدعم OpenAI MCP عن بُعد عبر Apps / Connectors (وضع المطوّر في إعدادات ChatGPT). يتصل ChatGPT من سحابة OpenAI — stdio المحلي لا يعمل.

فعّل وصول المطوّر

في ChatGPT: Settings → Apps & Connectors (أو Connectors → Advanced) → فعّل Developer mode إن كان متاحًا في خطتك.

أضف عنوان MCP

أنشئ تطبيقًا/موصّلًا جديدًا والصق:

https://{subdomain}.api.karzoun.chat/mcp

راجع الأدوات المكتشفة قبل تفعيل التطبيق في المحادثات.

تتوقع العديد من تدفقات موصّلات ChatGPT OAuth 2.1 مع تسجيل عميل ديناميكي. يصادق MCP المستضاف لكرزون عبر x-app-token (نفس واجهة GraphQL العامة)، وليس عبر نقاط نهاية اكتشاف OAuth.ما يعمل اليوم: الاتصال عبر Manus، Cursor عن بُعد، Claude Code، أو وكيل خلفية خاص يستدعي /mcp مباشرة.بالنسبة لـ ChatGPT تحديدًا: إذا فشل إعداد الموصّل عند المصادقة، شغّل أدوات كرزون من عامل خلفية (خادمك يحمل الرمز) أو استخدم بوابة MCP تضيف OAuth أمام كرزون. سنوثّق OAuth من الطرف الأول لـ ChatGPT عند توفره.

Cursor (عن بُعد)

للفرق التي تفضّل عدم تشغيل npx محليًا، يدعم Cursor MCP عن بُعد عبر url + headers في mcp.json.

{
  "mcpServers": {
    "karzoun-hosted": {
      "url": "https://YOUR_SUBDOMAIN.api.karzoun.chat/mcp",
      "headers": {
        "x-app-token": "${env:KARZOUN_APP_TOKEN}"
      }
    }
  }
}

صدّر KARZOUN_APP_TOKEN في ملف تعريف الصدفة (تطبيقات سطح المكتب قد لا تحمّل .zshrc — استخدم بيئة النظام أو أنماط الأسرار المدعومة في Cursor). يجب أن يظهر إعدادات Cursor ← MCP بحالة connected مع نحو 75 أداة. فضّل stdio المحلي للتطوير دون اتصال؛ واستخدم المستضاف عندما يكون npx محظورًا أو تريد نقطة نهاية مشتركة واحدة. الوثائق: Cursor MCP — remote servers.

Claude Code

يمكن لـ Claude Code تسجيل خوادم MCP عبر HTTP من سطر الأوامر:

claude mcp add --transport http karzoun \
  https://YOUR_SUBDOMAIN.api.karzoun.chat/mcp \
  --header "x-app-token: YOUR_APP_TOKEN"

استخدم .mcp.json للمشروع للوصول على مستوى المستودع. دوّر الرموز عبر المطوّر ← التطبيقات إذا شارك إعداد CLI.

ابنِ وكيلك الخاص

أي مكدس يتحدث Streamable HTTP MCP يمكنه استدعاء كرزون: المضيفات النموذجية: LangGraph، عمال Node/Python مخصصون، أتمتة بأسلوب Zapier، بوتات Slack داخلية.

POST initialize → التقط mcp-session-id
POST tools/list → اكتشف العمليات
POST tools/call → نفّذ بحجج بشكل GraphQL

أمثلة وcurl: MCP المستضاف. تصميم الأوامر: أنماط الوكلاء.

ضيّق نطاق الرموز لوكلاء أكثر أمانًا

قبل ربط عميل قوي:

الهدف	صلاحيات التطبيق	بيئة اختيارية
مساعد CRM للقراءة فقط	استعلام العملاء، الوسوم، الشركات	`KARZOUN_MCP_TOOL_PREFIX` على stdio فقط
فرز الدعم	المحادثات + قراءة قاعدة المعرفة	ضيّق نطاق التطبيق في الواجهة
إدارة التكامل	خطافات الويب + تعديلات التطبيقات	رمز منفصل بامتياز عالٍ

ابدأ بتطبيق للقراءة فقط، تحقّق من الأوامر، ثم أصدر رمزًا أوسع عند الحاجة.

استكشاف أخطاء الموصّلات

العرض	السبب المحتمل	الإصلاح
401 Missing `x-app-token`	الترويسة غير مرسلة	أضف الترويسة في إعداد العميل أو الوكيل
400 invalid session	تخطّيت `initialize` أو جلسة قديمة	أعد المصافحة؛ راجع MCP المستضاف
أدوات فارغة / خطأ صلاحية	نطاق التطبيق ضيق جدًا	وسّع الصلاحيات؛ اختبر في ساحة التجربة
العميل لا يصل إلى العنوان	شبكة خاصة / localhost	استخدم `*.api.karzoun.chat` العام فقط
فشل مصادقة ChatGPT	موصّل OAuth فقط	استخدم Manus، Cursor عن بُعد، أو وكيل خلفية

المزيد: استكشاف الأخطاء.

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

MCP المستضاف — تفاصيل البروتوكول ومرجع curl
أنماط الوكلاء — أوامر متعددة الخطوات موثوقة
كتالوج الأدوات — اسم كل عملية
الأمان — تدوير الرموز والاستجابة للحوادث

نظرة عامة

الإعداد

أدلة

الأدوات

ربط تطبيقات الذكاء الاصطناعي بـ MCP المستضاف

تفاصيل اتصالك

ما الذي تفتحه

حسب المجال

أوامر تُظهر القوة

اختر العميل المناسب

Claude.ai

Manus

ChatGPT Apps والموصّلات

Cursor (عن بُعد)

Claude Code

ابنِ وكيلك الخاص

ضيّق نطاق الرموز لوكلاء أكثر أمانًا

استكشاف أخطاء الموصّلات

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

​تفاصيل اتصالك

​ما الذي تفتحه

​حسب المجال

​أوامر تُظهر القوة

​اختر العميل المناسب

​Claude.ai

​Manus

​ChatGPT Apps والموصّلات

​Cursor (عن بُعد)

​Claude Code

​ابنِ وكيلك الخاص

​ضيّق نطاق الرموز لوكلاء أكثر أمانًا

​استكشاف أخطاء الموصّلات

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

تفاصيل اتصالك

ما الذي تفتحه

حسب المجال

أوامر تُظهر القوة

اختر العميل المناسب

Claude.ai

Manus

ChatGPT Apps والموصّلات

Cursor (عن بُعد)

Claude Code

ابنِ وكيلك الخاص

ضيّق نطاق الرموز لوكلاء أكثر أمانًا

استكشاف أخطاء الموصّلات

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