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

# استكشاف الأخطاء

> أصلح أخطاء اتصال كرزون MCP والصلاحيات والحجم الشائعة.

## خادم MCP لا يبدأ (stdio)

| العرض                       | الإصلاح                                                        |
| --------------------------- | -------------------------------------------------------------- |
| `Missing KARZOUN_API_URL`   | عيّن عنوان GraphQL في `env` إعداد MCP                          |
| `Missing KARZOUN_APP_TOKEN` | أنشئ رمز تطبيق من **المطوّر ← التطبيقات**                      |
| `npx` يتوقف أو يفشل         | تأكد من Node 18+؛ جرّب `npx -y @karzounchat/mcp-server@latest` |
| الخادم يظهر أحمر في Cursor  | افتح **Settings → MCP** → اعرض السجلات؛ صحّح أخطاء env         |

أعد تشغيل خادم MCP بعد كل تغيير في الإعداد.

## قائمة الأدوات فارغة

* تأكد أن حالة الخادم **connected** (أخضر) في إعدادات Cursor MCP
* تحقق من `KARZOUN_MCP_TOOL_PREFIX` — قد تستبعد بادئة ضيقة جدًا جميع الأدوات
* حدّث الحزمة: `npx -y @karzounchat/mcp-server@latest`

## الأداة تعيد خطأ صلاحية

* قد لا تتضمن مجموعة مستخدمي التطبيق العملية — عدّل النطاقات في **المطوّر ← التطبيقات**
* انتهت صلاحية الرمز أو أُلغي — أنشئ رمز تطبيق جديد
* اختبر نفس العملية في [ساحة التجربة](https://karzoun.chat/developer/playground)

## الاستجابة تتجاوز حد الحجم

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "error": "Response exceeds 524288 bytes. Narrow your query parameters..." }
```

* قلّل `perPage`
* أضف `searchValue` أو عوامل تصفية
* ارفع الحد فقط عند الحاجة: `KARZOUN_MCP_MAX_RESPONSE_BYTES=1048576`

## أخطاء /mcp المستضاف

| HTTP / JSON-RPC                      | المعنى                                                               |
| ------------------------------------ | -------------------------------------------------------------------- |
| `401 Missing x-app-token`            | أرسل `x-app-token` في كل طلب                                         |
| `400 invalid or missing MCP session` | استدعِ `initialize` أولًا؛ مرّر ترويسة `mcp-session-id` في المتابعات |
| انقطاع الاتصال                       | الجلسات في الذاكرة؛ أعد التهيئة بعد إعادة تشغيل البوابة              |

راجع [MCP المستضاف](/ar/mcp-server/setup/hosted) للمصافحة الكاملة.

## الوكيل يتجاهل أدوات كرزون

* اطلب صراحة: *"Use Karzoun MCP tools to …"*
* أضف [أنماط الوكلاء](/ar/mcp-server/guides/agent-patterns) إلى قواعد المشروع
* تحقق من ظهور الأدوات في قائمة أدوات MCP في Cursor للجلسة

## ما زلت عالقًا؟

1. تحقق من GraphQL بـ curl ([البداية السريعة](/ar/developers/getting-started/quickstart))
2. قارن اسم الأداة في [الكتالوج](/ar/mcp-server/tools/catalog) بما استدعاه الوكيل
3. تواصل مع الدعم بمعرّف التطبيق (وليس الرمز الخام)، واسم الأداة، ورسالة الخطأ بعد التنقيح


## Related topics

- [استكشاف الأخطاء](/ar/miniapps/guides/troubleshooting.md)
- [إعداد Claude Desktop (stdio)](/ar/mcp-server/setup/claude-desktop.md)
- [مكالمات واتساب](/ar/help-center/guides/whatsapp/whatsapp-calling.md)
- [الأخطاء](/ar/developers/guides/errors.md)
- [MCP المستضاف (/mcp)](/ar/mcp-server/setup/hosted.md)