MCP

نفس الواجهة، موجَّهة إلى مساعد بدل سيناريو. يختار عميل MCP ما يستدعيه أثناء التشغيل من أوصاف الأدوات — فيصل تمامًا إلى ما تصل إليه بيانات اعتماده، وتحت كل أداة استدعاء للواجهة العامة.

نقطة نهاية واحدة

كل شيء يذهب إلى POST /v1/mcp. لا جلسة تُفتح ولا تدفّق يُمسك: يردّ GET وDELETE بـ 405، وكل رسالة طلب قائم بذاته.

POST https://api.mosaqo.app/v1/mcp
Authorization: Bearer $MOSAQO_KEY
MCP-Protocol-Version: 2026-07-28

تُخدَم جميع مراجعات البروتوكول من 2025-03-26 إلى 2026-07-28. العميل الذي يبدأ بـ initialize يحصل على المصافحة التي يتوقعها؛ والذي يذكر نسخته في كل طلب يُخدَم هكذا.

الربط بمفتاح واجهة

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

معظم العملاء يقبلون كتلة مثل هذه:

{
  "mcpServers": {
    "mosaqo": {
      "type": "http",
      "url": "https://api.mosaqo.app/v1/mcp",
      "headers": { "Authorization": "Bearer $MOSAQO_KEY" }
    }
  }
}

curl -X POST https://api.mosaqo.app/v1/mcp \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

الربط عبر OAuth

لموصّل في دليل شخص آخر، حيث لا يلمس الإنسان مفتاحًا أبدًا. الاكتشاف وفق RFC 9728 وRFC 8414، ويسجّل العملاء أنفسهم عبر RFC 7591، وكل تفويض يستخدم PKCE مع S256.

curl https://api.mosaqo.app/.well-known/oauth-protected-resource
curl https://api.mosaqo.app/.well-known/oauth-authorization-server

الاستدعاء غير المصرَّح به يقول بنفسه إلى أين يذهب وماذا يطلب:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Mosaqo MCP",
  resource_metadata="https://api.mosaqo.app/.well-known/oauth-protected-resource",
  scope="qr:read analytics:read reviews:read exports:read"

من يوافق يكون قد سجّل الدخول إلى Mosaqo، ويختار مساحة العمل المعنية، ولا يمكنه ذلك إلا حيث يكون مالكًا أو مسؤولًا — الحدّ نفسه الذي يقرر من يصدر مفتاح واجهة. ويمكن فصله لاحقًا من Bulk & API.

ما الذي يستطيعه المساعد

النطاقات التي تعرفها أصلًا، دون تغيير. الأداة التي لا تسمح بها بيانات الاعتماد لا تظهر في tools/list ولا تُستدعى بذكر اسمها — فالجواب الحيّ لأي اتصال هو tools/list نفسه.

ما لن يصل إليه أبدًا

ما كتبه الناس في استبيان. يفتح reviews:read أماكنك واستبياناتك وكيف تسير: الأعداد والدرجات وتوزيع الإجابات لكل سؤال. أما الجمل التي كتبها زائر فلا تُعاد هنا ولا في أي مكان آخر تصله بيانات الاعتماد — للسبب نفسه الذي يجعل أحداث feedback.* تحمل درجة ولا تحمل الكلمات أبدًا.

حذف رمز. يطلب مسار REST تأكيدًا مكتوبًا لأن إتلاف إعادة التوجيه خلف رمز مطبوع لا يُعكَس، وهذا ليس تأكيدًا يقدّمه مساعد نيابة عن أحد. تُعرَض الأرشفة بدلًا منه، وهي قابلة للعكس.

الكتابة موسومة ككتابة. الأداة التي تغيّر شيئًا تحمل readOnlyHint: false، والأرشفة تحمل destructiveHint: true — وهذا ما يجعل العميل يتوقف ويسأل إنسانًا قبل أن ينفّذ.