BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/external-agents.mdx
View on GitHub---
title: "الوكلاء الخارجيون: Claude، ChatGPT، Codex، المؤشر، العمل المشترك، Grok"
description: "قم بتوصيل Claude، أو ChatGPT، أو Codex، أو Cursor، أو Claude Cowork، أو Grok، أو أي مضيف متوافق مع MCP بتطبيق وكيل مستضاف - ثم إرجاع العناصر ذهابًا وإيابًا إلى UI قيد التشغيل باستخدام تطبيقات MCP والروابط العميقة."
search: "Claude Anthropic ChatGPT OpenAI Claude الكود Codex المؤشر Claude Cowork Grok xAI MCP وكيل التطبيقات الأصلي، توصيل أدوات الوكيل المحلي، الوكلاء الخارجيون"
---
# الوكلاء الخارجيون
**هذه الصفحة: قم بتوصيل وكيل خارجي أو مضيف MCP بتطبيقك.** استخدمها عندما يقوم Claude أو ChatGPT أو Codex أو Cursor أو Claude Cowork أو أي مضيف آخر متوافق مع MCP بتشغيل تطبيق وكيل مستضاف وإعادة النتيجة مرة أخرى إلى UI قيد التشغيل.
| إذا كنت تريد... | اقرأ |
| ------------------------------------------------------------------- | ---------------------------------- |
| قم بتوصيل وكيل/مضيف خارجي بتطبيقك | **هذه الصفحة** — الوكلاء الخارجيون |
| امنح وكيلك المزيد من الأدوات (استخدم خوادم MCP الأخرى) | [MCP Clients](/docs/mcp-clients) |
| إنشاء UI المضمنة التي يتم عرضها في Claude/ChatGPT | [MCP Apps](/docs/mcp-apps) |
| مرجع خادم MCP ذو المستوى الأدنى (المصادقة، الأدوات، التثبيت المخصص) | [MCP Protocol](/docs/mcp-protocol) |
يمكن الوصول إلى تطبيق الوكيل الأصلي بواسطة أي مضيف متوافق مع MCP — Claude، Claude Desktop، Claude Code، ChatGPT تطبيقات MCP المخصصة، Codex، Cursor، Claude Cowork، VS Code GitHub Copilot، Goose، Postman، MCPJam، والعملاء المستقبليين الذين ينفذون المعيار. يعد الوكلاء الخارجيون رائعين في إنتاج العناصر (مسودة، أو حدث، أو لوحة معلومات) لكنهم غالبًا ما يعيشون في محطة طرفية أو تطبيق آخر. بدون جسر، يحصل المستخدم على جدار JSON وعليه البحث عن الشيء.
يقوم جسر الوكيل الخارجي بإغلاق الحلقة. أولاً، تقوم بتوصيل الوكيل الخاص بك بتطبيق **مستضاف** — إما عن طريق لصق MCP URL الخاص بالتطبيق في مضيف دردشة مثل Claude أو ChatGPT، أو عن طريق تشغيل تدفق المطور CLI لوكلاء الترميز المحليين. ثم يقوم الوكيل بالعمل على MCP ويسلم المستخدم إما **MCP App** UI المضمن في المضيفين المتوافقين أو رابط **"فتح في <app> →"** واحد يفتح التطبيق الحقيقي الذي يركز على ما تم إنتاجه بالضبط. إنها تعيد استخدام عقد `navigate` / `application_state` الحالي الذي يستنزف UI بالفعل كل ثانيتين (انظر [Context Awareness](/docs/context-awareness)) - لا توجد آلية تنقل ثانية.
<Diagram id="doc-block-13sglel" title={"رحلة ذهابًا وإيابًا للوكيل الخارجي"} summary={"يقوم مضيف خارجي باستدعاء أداة عبر MCP؛ يقوم التطبيق بإرجاع قطعة أثرية بالإضافة إلى رابط مفتوح. يؤدي النقر فوقه إلى حل جلسة المتصفح وتركيز العنصر في واجهة المستخدم قيد التشغيل - لا يحمل الرابط أي حالة مميزة."}>
```html
<div class="xa-trip">
<div class="diagram-box" data-rough>
مضيف خارجي<br /><small class="diagram-muted"
>Claude · ChatGPT · Codex · Cursor</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center" data-rough>
<span class="diagram-pill accent">أداة MCP call</span
><small class="diagram-muted">e.g. <code>manage-draft</code></small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box" data-rough>
ينتج التطبيق أثرًا<br /><small class="diagram-muted"
>+ <code>Open in <app> →</code> deep link / MCP App</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">↓</div>
<div class="diagram-box" data-rough>ينقر المستخدم على الرابط</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center" data-rough>
<span class="diagram-pill ok"><code>/_agent-native/open</code></span
><small class="diagram-muted"
>resolves the <strong>browser</strong> session</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box" data-rough>
Writes <code>navigate</code> app-state<br /><small class="diagram-muted"
>تركز الواجهة على الأثر</small
>
</div>
</div>
```
```css
.xa-trip {
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
}
.xa-trip .center {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
}
.xa-trip .diagram-arrow {
font-size: 22px;
line-height: 1;
}
.xa-trip code {
font-size: 0.85em;
}
```
</Diagram>
قاعدة الهوية هي مفصل الأمان: الرابط هو مجرد `view` + معرفات السجل + عوامل التصفية، ويتم تحديد نطاق كتابة `navigate` التي تركز على السجل على كل من قام بتسجيل الدخول إلى **المتصفح** - وليس الرمز المميز MCP للوكيل الخارجي أبدًا. ولهذا السبب يكون الرابط آمنًا للصقه في المحطة الطرفية أو في نص الدردشة.
## ما هو مسار الوكيل الذي تحتاجه؟ {#which-agent-path}
- **مضيف MCP الخارجي:** استخدم هذه الصفحة عندما يقوم Claude أو ChatGPT أو Codex أو Cursor أو OpenCode أو GitHub Copilot / VS Code أو مضيف آخر متوافق مع MCP باستدعاء التطبيق الأصلي للوكيل المستضاف.
- **وقت التشغيل الخاص بك خلف دردشة Agent-Native:** راجع [Agent Surfaces](/docs/agent-surfaces#byo-agent) و[Native واجهة الدردشة](/docs/native-chat-ui#byo-agent-runtimes) عندما يقوم وكيل تم إنشاؤه باستخدام إطار عمل آخر بتشغيل `<AssistantChat runtime={...}>`.
- **تطبيقك الذي يستهلك أدوات MCP:** راجع [MCP Clients](/docs/mcp-clients) عندما يحتاج تطبيق وكيل أصلي إلى استدعاء الأدوات التي كشفها خادم MCP آخر.
- **تطبيق أو وكيل آخر عبر A2A:** استخدم [Agent Mentions](/docs/agent-mentions) و[A2A](/docs/a2a-protocol) عندما يتعين على التطبيقات الأصلية للوكيل اكتشاف وتفويض بعضها البعض.
- **الوكلاء الفرعيون المحليون المخصصون:** استخدم [موارد الوكيل](/docs/agent-resources) عندما تريد ملفات تعريف الوكيل المخصصة داخل مساحة العمل الأصلية للوكيل نفسها.
## سهولة الإعداد {#easy-setup}
يوفر كل تطبيق Agent-Native عنوان MCP أساسيًا واحدًا:
```text
https://<your-app>.agent-native.com/mcp
```
في التطبيق، افتح **Settings → Connections → Integrations** وابحث باسم المضيف الذي تعرفه:
Claude أو Claude Cowork أو Claude Code أو Anthropic أو ChatGPT أو OpenAI أو Codex
أو Grok أو xAI. تفتح النتيجة الوحيدة للمضيف الخارجي **Settings → MCP server** مع تحديد
الدليل الأقرب. انسخ **MCP server URL** والصقه في مضيف الذكاء الاصطناعي. العنوان هو
عنوان URL الأساسي للتطبيق المنشور مع إضافة `/mcp`.
للعمل في مساحة العمل أو عبر التطبيقات، استخدم Dispatch:
```text
https://dispatch.agent-native.com/mcp
```
Dispatch هو البوابة الوحيدة للبريد والتقويم والتحليلات والعقل و
تطبيقات مساحة العمل. في صفحة **الوكلاء** الخاصة بـ Dispatch، اختر ما إذا كانت البوابة يمكنها ذلك
الوصول إلى جميع التطبيقات أو التطبيقات المحددة فقط. ثم يحصل المضيف المتصل على
تمت تصفية `list_apps` و`ask_app` و`open_app` لتلك المجموعة الممنوحة.
بالنسبة إلى تطبيق واحد معزول عمدًا، استخدم هذا التطبيق مباشرةً:
```text
https://mail.agent-native.com/mcp
https://<your-app>.agent-native.com/mcp
```
يحتوي كل تطبيق مستضاف أيضًا على صفحة مساعدة على
`https://<app>/mcp/connect` مع URL القابل للنسخ و
علامات تبويب خاصة بكل مضيف لكل من Claude وChatGPT وCursor وVS Code وClaude Code وCodex وGrok وغير ذلك.
## روابط Content الخاصة {#private-content-links}
يمكن لرابط مشاركة Content الخاص تحديد المستند من دون كشف محتواه. أضف عنوان `/mcp` من مثيل Content نفسه كخادم MCP بعيد في الوكيل، وسجّل الدخول بحساب Agent-Native، وفعّل الاتصال أو أدواته، ثم أعد محاولة طلب المستند الأصلي. توفر صفحة `/mcp/connect` خيارات الإعداد، لكن فتحها وحده لا يثبّت الاتصال داخل الوكيل.
تعمل هذه الخطوات مع أي مضيف يدعم MCP، بما في ذلك Claude وChatGPT وClaude Code وCodex وCursor وAntigravity وOpenCode وGitHub Copilot / VS Code. تختلف شاشات الإعداد والمصادقة باختلاف المضيف. يدير Antigravity الخوادم البعيدة من **Settings → Customizations → Installed MCP Servers** أو ملف إعداد MCP؛ ولا يضبط أمر `connect` في Agent-Native إعداد Antigravity حاليًا.
تحدد المصادقة الحساب المتصل ولا توسّع أذونات المستند. يظل المستند العام مقروءًا من صفحة المشاركة. ولا يمكن قراءة المستند الخاص عبر MCP إلا إذا كان الحساب يملك الوصول مسبقًا. إذا أعاد `get-document` نتيجة «غير موجود» بعد الاتصال، فلا تميز الاستجابة بين الإذن المفقود ومعرّف مستند قديم أو محذوف أو غير صالح. تحقق من الرابط ووصول الحساب المتصل قبل تغيير الأذونات.
لا تؤدي إعادة تثبيت الموصل أو تغيير رابط المشاركة العام إلى حل رفض صلاحية مؤكد للحساب المتصل.
تُحفظ الصور المرفوعة إلى مستند خاص في متنه كروابط `/api/private-media/<id>`، ولا تُحمَّل إلا مع تسجيل الدخول إلى Content. عندما يقرأ وكيل المستند عبر MCP، تُرجع `get-document`، و`pull-document` بتنسيق Markdown، أيضًا `privateMediaLinks`: كل رابط محفوظ مقرونًا بعنوان URL يفتح تلك الصورة وحدها دون تسجيل الدخول لمدة ساعة. تربط القراءة الواحدة 200 صورة على الأكثر، ويَعُدّ `omitted` الباقي. أعد قراءة المستند للحصول على روابط جديدة. احتفظ بالروابط المحفوظة عند تعديل المتن.
<a id="access-tab"></a>
### إعداد MCP داخل التطبيق {#mcp-settings}
تتضمن الإعدادات صفحة **MCP server** ضمن مجموعة التطبيق. تعرض
عنوان MCP الأساسي للتطبيق، وبطاقة وكيل A2A عند توفرها، وتعليمات الإعداد نفسها
المستخدمة في صفحة الاتصال الكاملة. استخدم **Settings → MCP server** كنقطة البداية داخل
التطبيق، أو افتح `/mcp/connect` مباشرةً للتدفق الكامل والرمز الاحتياطي.
### Claude وChatGPT OAuth {#oauth}
Claude / Claude Desktop: يفتح **إضافة إلى Claude** صفحة **Customize →
Connectors** مع نافذة **Add custom connector** وقد عُبّئ فيها اسم التطبيق وعنوان
MCP مسبقًا. اختر **Add**، وسجّل الدخول بحساب Agent-Native، ووافق على نطاقات MCP،
وفعّل الموصل في محادثة. يستخدم Claude Code العنوان نفسه: شغّل
`claude mcp add --transport http --scope user <server-name> <mcp-url>` ليصبح
الخادم متاحًا في كل المشاريع، ثم شغّل `/mcp` واختر **Authenticate**.
ChatGPT: تتطلب تطبيقات MCP المخصصة مساحة عمل مدعومة على ChatGPT web. إذا كان
لديك وصول، افتح **Settings → Apps → Advanced settings**، وفعّل وضع المطور عند
الحاجة، واختر **Create app**، والصق عنوان MCP نفسه، واختر OAuth، وافحص الأدوات،
وسجّل الدخول باستخدام Agent-Native، ووافق على النطاقات المطلوبة، ثم فعّل التطبيق
في محادثة. تدعم مساحات Business وEnterprise وEdu بروتوكول MCP الكامل، بما في
ذلك إجراءات الكتابة؛ بينما يدعم Pro القراءة والجلب في وضع المطور. إذا لم يظهر
**Apps** أو **Create app**، فإن خطتك أو سياسة مساحة العمل لا تسمح بهذا الإعداد.
منح OAuth مخصصة لكل مضيف ولكل مستخدم. يقوم المضيف بتخزين الرموز المميزة و
يتوسط استدعاءات الأدوات/الموارد، لذلك لا تتلقى معاينات تطبيق MCP المضمّنة بيانات أولية أبدًا
الرموز المميزة OAuth. يمكن لـ ChatGPT الاحتفاظ بأداة الموصل التي تمت مراجعتها أو نشرها
اللقطة حتى تقوم بتحديثها/مراجعتها مرة أخرى، لذا أعد فحص الموصل بعد MCP
تغييرات البيانات التعريفية لتطبيق MCP. إذا كان لا يزال لديك موصلات قديمة لكل تطبيق
ممكّن جنبًا إلى جنب مع Dispatch أو تحديث أو إعادة توصيل كل موصل قديم؛ التحديث
لا يقوم Dispatch بإعادة كتابة تقويم/بريد ChatGPT أو Claude المخزن مؤقتًا/البريد/إلخ.
لقطات. نطاقات `mcp:read` / `mcp:write` / `mcp:apps` / `offline_access` هي نفسها الموضحة في
[OAuth القياسي لـ MCP البعيد](#standard-oauth) أدناه.
### Cursor وVS Code وCodex {#install-links}
تحتوي أدلة **Claude** و**Cursor** و**VS Code** في **Settings → MCP server** وفي
`/mcp/connect` على أزرار تثبيت. يفتح **إضافة إلى Claude** نافذة إضافة موصل في
Claude وقد عُبّئ فيها الاسم والعنوان مسبقًا. يفتح **إضافة إلى Cursor** نافذة
**Install MCP server?** في Cursor. ويفتح **إضافة إلى VS Code** و**إضافة إلى VS
Code Insiders** صفحة خادم فيها زر **Install**. لا يحمل الرابط إلا اسمًا وعنوان MCP، ونوع النقل أيضًا في VS Code، ولا يحمل أبدًا رمزًا مميزًا أو ترويسة أو بيانات حساب.
ويُجري العميل تسجيل دخول OAuth الخاص به عند أول اتصال. وفي VS Code تظهر الأدوات
بعد ذلك في عرض Chat في وضع Agent. ومن دون الزر، شغّل **Chat: Open
Customizations**، وافتح **MCP Servers**، واختر **+**، واختر **HTTP**، والصق
عنوان MCP.
في Codex، شغّل `codex mcp add <server-name> --url <mcp-url>` ثم
`codex mcp login <server-name>` لتسجيل الدخول عبر OAuth. تملأ علامة التبويب
**Codex** القيمتين.
تستخدم Goose وPostman وMCPJam والعملاء الآخرون عنوان MCP البعيد نفسه من شاشات
خوادم MCP الخاصة بها عندما يدعم إصدارها خوادم MCP البعيدة التي تستخدم OAuth.
### أسماء الخوادم {#server-names}
يسمّي التطبيق خادم MCP الخاص به، وتستخدم كل الواجهات هذا الاسم: روابط التثبيت،
والأوامر القابلة للنسخ، و`npx @agent-native/core@latest connect`.
يستخدم الإنتاج الاسم وحده، مثل `agent-native-mail`. وتضع عمليات النشر التجريبية
والمعاينة والمحلية اسم البيئة في أوله، مثل `beta-agent-native-mail`، حتى يحتفظ
العميل نفسه بإدخال للإنتاج وآخر للنسخة التجريبية جنبًا إلى جنب. هذه البادئات
محجوزة: لا يمكن أن يبدأ `mcp.serverName` بـ `beta-` أو `preview-` أو `local-`،
لذا لا يطابق اسم تجريبي أبدًا اسم الإنتاج لتطبيق آخر. يمكن للبرامج النصية قراءة
الاسم من `GET /mcp/connect/identity`، الذي لا يحتاج إلى تسجيل دخول ويعيد اسم
الخادم واسم التطبيق وعنوان التطبيق وعنوان MCP والبيئة، إضافة إلى العلامة `connect`
التي تكون `false` عند إيقاف `mcp.connect`.
### موجه اختبار سريع {#quick-test}
بعد الاتصال، جرّب أحد الإجراءات التالية:
```text
Use Agent-Native Analytics to generate a weekly conversion-rate bar chart and show it inline.
```
```text
Use Agent-Native Mail to draft a short follow-up email to me, but do not send it.
```
في الأجهزة المضيفة التي تدعم تطبيقات MCP، يمكن لـ Analytics عرض لوحة التحكم الحقيقية ومسارات التحليل بشكل مضمن، ويمكن للبريد عرض الإنشاء الحقيقي UI مضمنًا لمسودة المراجعة. في الأجهزة المضيفة التي لا تعرض تطبيقات MCP، لا يزال استدعاء الأداة نفسه يعرض رابطًا عميقًا مثل **فتح مسودة في البريد →** أو **فتح لوحة المعلومات في Analytics →**.
## الإعداد المتقدم: الوكلاء المحليون {#connect}
استخدم هذا التدفق لعملاء الوكلاء المحليين على جهازك — رمز Claude، ورمز Claude CLI، وCodex، وClaude Cowork، وCursor، وOpenCode، وGitHub Copilot / VS Code. يمكن للمؤشر وغيره من عملاء OAuth الأصليين أيضًا استخدام تدفق اللصق URL أعلاه عندما يدعم UI MCP OAuth عن بعد.
قم بتشغيل أمر الاتصال من خلال npm:
```bash
npx @agent-native/core@latest connect https://dispatch.agent-native.com
```
يسأل الأمر عن عملاء الوكيل المحليين الذين يجب أن يتلقوا تكوين MCP. يتم اختيار جميع العملاء مسبقًا في المرة الأولى؛ بعد الاختيار، يتم حفظ التحديد في `~/.agent-native/connect.json` بحيث يمكن إعادة استخدامه في التشغيل التالي باستخدام Enter، أو يمكنك تحرير العناصر المحددة.
بالنسبة لرمز Claude، ورمز Claude، وCLI، وCursor، وOpenCode، وGitHub Copilot / VS Code، يكتب `connect` إدخال HTTP MCP قياسي عن بعد بدون رؤوس ثابتة. أعد تشغيل العميل وقم بالمصادقة من MCP UI عند المطالبة بذلك. بالنسبة إلى Codex وClaude Cowork، يستخدم `connect` تدفق كود جهاز التوافق: فهو يفتح المتصفح الخاص بك في التطبيق، ثم تنقر فوق **Authorize** مرة واحدة، ويكتب الأمر إدخال رمز حامل مميز محدد النطاق. إذا اخترت مزيجًا من العملاء، فسيتم تنفيذ الأمرين معًا.
استمر في تشغيل الأمر `connect` حتى تكتمل الموافقة على المتصفح. إذا كان
تم إيقاف عملية الانتظار مبكرًا، ويمكن أن تنجح الموافقة في المتصفح ولكن
لن يتلقى تكوين العميل المحلي الرمز المميز.
إذا كنت قد قمت مسبقًا بتوصيل رمز Claude من خلال تدفق الرمز المميز القديم لحامله، فما عليك سوى تشغيل نفس أمر `npx @agent-native/core@latest connect ... --client claude-code` مرة أخرى. يستبدل CLI رؤوس `Authorization` القديمة بإدخال URL فقط OAuth ويطلب منك إعادة المصادقة من `/mcp`.
| العميل المحلي | تم كتابة التكوين بواسطة `connect` | تدفق المصادقة |
| ---------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------- |
| رمز Claude / رمز Claude CLI | `.mcp.json` أو `~/.claude.json`، اعتمادًا على `--scope` | جهاز التحكم عن بعد القياسي MCP OAuth في Claude `/mcp` UI |
| المؤشر | `.cursor/mcp.json` أو `~/.cursor/mcp.json` | جهاز التحكم عن بعد القياسي MCP OAuth في MCP UI الخاص بالمؤشر |
| الرمز المفتوح | `opencode.json` أو `~/.config/opencode/opencode.json` | جهاز التحكم عن بعد القياسي MCP OAuth في MCP UI الخاص بـ OpenCode |
| GitHub مساعد الطيار / رمز VS | تكوين مستخدم `.vscode/mcp.json` أو VS Code MCP | جهاز التحكم عن بعد القياسي MCP OAuth في MCP UI الخاص بـ VS Code |
| Codex | `$CODEX_HOME/config.toml` أو `~/.codex/config.toml` | الاحتياطي للحامل المعتمد للمتصفح |
| Claude العمل الجماعي | `~/.cowork/mcp.json` باستخدام الشكل Claude الرمز MCP | الاحتياطي للحامل المعتمد للمتصفح |
أعد تشغيل العميل الوكيل بعد الاتصال حتى يلتقط خادم MCP الجديد؛ قد يطالبك عملاء OAuth الأصليون بعد ذلك بالمصادقة من MCP UI.
عند استكشاف أخطاء تكوين MCP المحلي وإصلاحها، قم بتنقيح `Authorization`، `http_headers`،
وقيم الرمز المميز قبل مشاركة السجلات. لا تستخدمي الضفيرة الخام كبديل لـ
استضافة جلسة MCP؛ بعد الاتصال، استخدم الأدوات المكشوفة للمضيف أو أعد تشغيل
العميل إذا لم يكن الخادم الجديد مرئيًا بعد.
استخدم `--client codex` (أو `--client claude-code`، `--client claude-code-cli`، `--client cursor`، `--client opencode`، `--client github-copilot`، `--client cowork`، `--client all`) لتخطي منتقي البرامج النصية أو عمليات التثبيت لمرة واحدة.
يقوم تطبيق الطرف الأول skills بتثبيت الإرشادات وموصل MCP المستضاف مع Agent-Native CLI:
```bash
npx @agent-native/core@latest skills add assets # alias: image-generation
```
مسار Vercel/open Skills CLI متاح أيضًا عندما تريد المحمول فقط
التعليمات:
```bash
npx skills@latest add BuilderIO/agent-native --skill assets
```
يقوم `skills` CLI بتثبيت ملفات `SKILL.md` فقط؛ لا يزال عملاء MCP المحليون
تحتاج إلى موصل مثل `npx @agent-native/core@latest connect https://assets.agent-native.com`.
| المهارة | الاسم المستعار | من أجل |
| -------- | ------------------ | ------------------- |
| `assets` | `image-generation` | إنشاء الصور/الفيديو |
تحديد العميل الافتراضي هو كافة العملاء المحليين المعتمدين؛ أضف `--client codex` أو `--client claude-code` أو هدفًا محددًا آخر لتضييق نطاق الإعداد. يعرض المضيفون المضمنون (ChatGPT ودردشة Claude على الويب وسطح المكتب والهاتف، بالإضافة إلى علامة تبويب Code في Claude Desktop) شبكة المنتقي/المتغيرات داخل المحادثة؛ أما المضيفون الذين يعتمدون على الروابط (Codex CLI وطرفية Claude Code وCowork وCode على claude.ai) فيعيدون رابط "فتح في … →" ليختار المستخدم في المتصفح ثم يلصق ملخص التسليم في المحادثة. [لا يعلن Cowork عن دعم MCP Apps حتى الآن، وقد يؤدي استخدامه على الموصل نفسه إلى اختفاء التطبيقات المضمنة في Chat حتى تعيد توصيل الموصل.](https://github.com/anthropics/claude-code/issues/103924)
عندما تحتاج حقًا إلى تطبيق معزول بدلاً من بوابة مساحة عمل Dispatch،
قم بتشغيل نفس الأمر مع مضيف هذا التطبيق:
```bash
npx @agent-native/core@latest connect https://mail.agent-native.com
```
لا يزال `connect --all` موجودًا لإعدادات العميل القديمة لكل تطبيق، ولكنه جديد
يجب أن تفضل إعدادات مساحة العمل موصل Dispatch الفردي.
الاتصال **لكل مستخدم، ومحدد النطاق، وقابل للإلغاء**. في مسار OAuth، يقوم المضيف بتخزين الرموز المميزة بعد مصادقة `/mcp`؛ في المسار الاحتياطي، تكون جلسة المتصفح التي سمحت بها هي الهوية التي يعمل بها الوكيل. لا شيء يكشف السر المشترك للنشر.
### إعادة المصادقة بعد 401 {#reconnect}
يتطلب تحديث ربط مالك OAuth أن يُجرى [اتصال جديد مرة واحدة](/docs/external-agents#reconnect) لكل اتصال OAuth قائم. تُرفض رموز وصول OAuth القديمة بعد طرح التحديث. تُعيد رموز التحديث القديمة غير المرتبطة بمالك `invalid_grant`، ويجب إعادة بدء الموافقة لرموز التفويض القديمة التي لم تُستخدم بعد. تستخدم رموز الوصول الصادرة حديثًا مدة الصلاحية المضبوطة، وتخضع لفحوص العضوية المباشرة. لا يغيّر هذا الانتقال بيانات اعتماد `mcp-connect` القديمة بتنسيق A2A أو رموز A2A بين التطبيقات. ويجب أيضًا إعادة الاتصال للاتصالات التي تستخدم رموز Connect القديمة بتنسيق OAuth.
بمجرد الاتصال، يجب أن تستمر المصادقة على المدى الطويل - تستمر رموز الوصول لمدة 30 يومًا افتراضيًا (يتم التجاوز باستخدام `MCP_OAUTH_ACCESS_TOKEN_TTL` على الخادم، على سبيل المثال `7d` أو `12h`) ولا يوجد لمنح التحديث تاريخ انتهاء ثابت، لذلك يجب أن تكون رموز 401 العشوائية نادرة. وعندما يحدث ذلك، استخدم أمر إعادة الاتصال الخفيف بدلاً من إعادة التثبيت:
```bash
npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
```
يبحث `reconnect` عن أي إدخال تكوين MCP ينتهي URL بـ `/mcp` للمضيف المحدد والعميل المحدد (المطابقة بواسطة URL بغض النظر عن اسم الموصل)، ثم يقوم بتحديث مادة المصادقة أو استبدالها دون لمس skills المثبت أو إعادة تشغيل تدفق التثبيت الكامل. تمرير التطبيق الأساسي URL (على سبيل المثال، `https://plan.agent-native.com`) - يتم استنتاج لاحقة `/mcp`. يتم تحميل المصادقة والأداة لكل عميل، لذا قم بإعادة تشغيل/إعادة تحميل هذا العميل بعد ذلك؛ يحتاج Codex إلى جلسة جديدة قبل ظهور الأدوات المحملة حديثًا.
في Claude Code، مسار UI المكافئ هو: تشغيل `/mcp` واختيار **مصادقة** (أو **إعادة الاتصال**) للموصل ذي الصلة.
لا تقم مطلقًا بإعادة تثبيت المهارة من البداية فقط لإصلاح الخطأ 401 — `reconnect` هي الأداة الصحيحة.
### ربط الصفحة الاحتياطية {#connect-page-fallback}
بالنسبة لعملاء MCP الذين لا يمكنهم إضافة OAuth URL عن بعد مباشرةً، افتح التطبيق في متصفحك واستخدم تكلفة **الاتصال** (المقدمة في `https://<app>/mcp/connect`). أثناء تسجيل الدخول، انقر فوق **الاتصال / التفويض**. تمنحك الصفحة إما رابطًا عميقًا بنقرة واحدة يقوم بتكوين الوكيل المكتشف، أو كتلة `.mcp.json` جاهزة للصقه:
```jsonc
// .mcp.json
{
"mcpServers": {
"mail": {
"type": "http",
"url": "https://mail.agent-native.com/mcp",
"headers": { "Authorization": "Bearer <minted-token>" },
},
},
}
```
أعد تشغيل العميل الوكيل بعد الاتصال حتى يلتقط خادم MCP الجديد.
استخدم كتلة الحامل اليدوية هذه لعملاء MCP الذين لا يمكنهم إكمال تدفق MCP OAuth القياسي عن بعد، أو لتصحيح الأخطاء لمرة واحدة عندما تريد لصق رمز مميز بشكل صريح.
### جهاز التحكم عن بعد القياسي MCP OAuth {#standard-oauth}
تدعم التطبيقات المحلية للوكيل المستضاف أيضًا تدفق MCP OAuth القياسي عن بعد. بالنسبة للعملاء الذين يقومون بتطبيق MCP OAuth، أضف خادم HTTP البعيد URL بدون رؤوس ثابتة:
```bash
claude mcp add --transport http agent-native \
https://dispatch.agent-native.com/mcp
```
هذا هو نفس الإدخال URL فقط الذي يكتبه لك `npx @agent-native/core@latest connect https://dispatch.agent-native.com --client claude-code`. ثم قم بتشغيل `/mcp` في رمز Claude واختر **Authenticate**. يكتشف العميل المصادقة من تحدي `401 WWW-Authenticate` الخاص بخادم MCP، ويجلب `/.well-known/oauth-protected-resource` و`/.well-known/oauth-authorization-server`، ويسجل عميل OAuth العام ديناميكيًا، ويفتح صفحة ترخيص التطبيق، ويخزن الرمز المميز الناتج بشكل آمن. تستخدم موصلات وضع المطور ChatGPT نفس الخادم URL:
```text
https://dispatch.agent-native.com/mcp
```
تدفق OAuth هو رمز التفويض + PKCE مع رموز تحديث لا يتم تدويرها. رموز الوصول مرتبطة بالجمهور بمورد MCP الدقيق URL وتحمل هوية المستخدم/المؤسسة الموقعة، لذا فإن استدعاءات الأدوات، `resources/read`، وMCP App iframe `tools/call` كلها تعمل من خلال نفس نطاق المستأجر `runWithRequestContext` مثل مسار JWT الحالي المتصل. لا يتلقى إطار iframe رموز OAuth الأولية أبدًا؛ يتوسط المضيف المكالمات من خلال اتصال MCP المصادق عليه.
النطاقات الحالية هي:
| النطاق | يسمح |
| ---------------- | ------------------------------------------------------------------ |
| `mcp:read` | MCP actions للقراءة فقط واكتشاف الأدوات/الموارد العادية |
| `mcp:write` | تعديل actions والأداة الوصفية `ask-agent` |
| `mcp:apps` | قائمة/قراءة موارد تطبيقات MCP وعرض UI المضمن حيثما يكون ذلك متاحًا |
| `offline_access` | الوصول إلى رمز التحديث حتى يظل المضيف متصلاً |
عندما لا يطلب العميل نطاقًا صريحًا، يمنح التطبيق النطاقات الأربعة جميعًا بحيث يتصرف الموصل مثل تدفق الاتصال المعتمد من المتصفح ويمكنه تحديث الوصول دون تسجيل دخول آخر. احتفظ بصفحة Connect-token Connect و`npx @agent-native/core@latest connect --token <token>` الاحتياطية للمطورين المحليين والمضيفين الاحتياطيين والعملاء حيث تحتاج إلى كتلة تكوين جاهزة لللصق.
## طبقات الكتالوج {#catalog-tiers}
هذا هو الشرح الأساسي لطبقات كتالوج MCP — رابط الصفحات الأخرى هنا.
يقدم خادم MCP **كتالوجًا مضغوطًا بشكل افتراضي لكل متصل** - الموصلات المستضافة (ChatGPT، Claude)، وعملاء التعليمات البرمجية (Claude Code، Cursor، Codex)، والوكيل CLI/stdio المحلي على حد سواء. يتم عرض سطح الإجراء الكامل فقط عند الاشتراك الصريح. لا يتم استنتاج الكتالوج أبدًا من اسم العميل أو وكيل المستخدم.
<Diagram id="doc-block-1ras8t9" title={"مستويين من الكتالوج"} summary={"يحصل كل متصل على المستوى المدمج بشكل افتراضي؛ سطح الأداة الكامل ~ 105 قابل للاشتراك فقط. يعمل البحث عن الأدوات على سد الفجوة بحيث لا يتم إخفاء أي شيء على الإطلاق."}>
```html
<div class="xa-tiers">
<div class="diagram-card" data-rough>
<span class="diagram-pill ok"
>Compact / connector tier · default</span
><strong>~20–30 tools</strong
><small class="diagram-muted"
>Template-declared app actions + cross-app builtins
(<code>list_apps</code>, <code>open_app</code>, <code>ask_app</code>,
<code>create_embed_session</code>) + always-present
<code>tool-search</code>.</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">↔</div>
<div class="diagram-card" data-rough>
<span class="diagram-pill accent">Full tier · opt-in</span
><strong>~105 أداة</strong
><small class="diagram-muted"
>Explicit opt-in only: <code>--full-catalog</code> token or
<code>AGENT_NATIVE_MCP_FULL_CATALOG=1</code>.</small
>
</div>
</div>
<p class="diagram-muted note">
يكتشف <code>tool-search</code> أدوات الطبقة الكاملة عند الطلب؛ ويجب أن يسمح
كتالوج الموصل أو سياسة القراءة المصادق عليها بالتنفيذ، ما لم يشترك المتصل
صراحةً في الطبقة الكاملة.
</p>
```
```css
.xa-tiers {
display: flex;
align-items: stretch;
gap: 14px;
flex-wrap: wrap;
}
.xa-tiers .diagram-card {
display: flex;
flex-direction: column;
gap: 6px;
padding: 14px 16px;
flex: 1;
min-width: 240px;
}
.xa-tiers .diagram-arrow {
align-self: center;
font-size: 24px;
line-height: 1;
}
.xa-tiers .note {
flex-basis: 100%;
margin: 4px 0 0;
font-size: 0.85em;
}
.xa-tiers code {
font-size: 0.85em;
}
```
</Diagram>
### الطبقة المدمجة / الموصل (افتراضي) {#connector-tier}
افتراضيًا، يرى كل وكيل متصل كتالوجًا صغيرًا ومنظمًا (~20–30 أداة مقابل ~105 أدوات في السطح الكامل). يمكن للتطبيقات إما إدارة `connectorCatalog` صريح، أو الاشتراك في سياسة القراءة المصادق عليها:
- **التطبيق المُعلن عن القالب actions** — القائمة المسموح بها الآمنة على مستوى التطبيق. بالنسبة للخطة `create-visual-plan`، و`get-visual-plan`، و`share-resource`، و`navigate`، و`tool-search`، وما شابه ذلك.
- **إنشاء أدوات مشتركة بين التطبيقات** — `list_apps`، `open_app`، `ask_app`، `create_embed_session`.
- **`tool-search`** موجود دائمًا للاكتشاف. لا يزال الإجراء المكتشف بحاجة إلى أن يكون في كتالوج الموصل، أو مشمولًا بسياسة القراءة المصادق عليها، أو متاحًا عبر الاشتراك الصريح في الكتالوج الكامل قبل أن يتمكن `tools/call` من تنفيذه.
لا يتم الإعلان عن الأدوات الموجودة خارج القائمة — على سبيل المثال `db-exec`، و`seed-*`، ومجموعة الامتدادات، وأدوات جلسة المتصفح، وأدوات سياق الأشعة السينية —، ويتم رفض الاستدعاءات إليها باستخدام "أداة غير معروفة" ما لم يشترك المتصل في الكتالوج الكامل. يؤدي هذا إلى إبقاء نافذة سياق كل وكيل متصل صغيرة وإزالة الأدوات الآمنة فقط للتطوير المحلي للمستأجر الواحد.
يعمل `tool-search` بطريقتين: يمكنك استدعاؤه باستخدام **بدون استعلام** للقائمة الكاملة لأسماء الأدوات بالإضافة إلى أوصاف من سطر واحد (رخيص، بدون مخططات)، أو باستخدام استعلام للمطابقات المرتبة مع ملخصات المعلمات. يساعد العميل المضغوط على اكتشاف الإمكانات؛ استخدم `ask_app` لأي شيء يتطلب استدلال وكيل التطبيق الأوسع أو عملية كتابة.
#### عمليات القراءة المصادق عليها افتراضيًا
يمكن للتطبيقات التي تريد أن تعمل أدوات القراءة المباشرة دون إدارة قائمة سماح طويلة الاشتراك في عمليات القراءة المصادق عليها تلقائيًا:
```ts
export default createAgentChatPlugin({
appId: "example-app",
externalAgents: {
authenticatedReads: "auto",
writes: "ask_app_only",
// حظر اختياري للدفاع المتعمق عن عمليات القراءة شديدة الحساسية.
denyActions: ["get-sensitive-export"],
},
});
```
هذا مثال عام للسياسة. يضبط Analytics الخيار `authenticatedReads: "off"` عمدًا، ولا يعرض سوى إجراءات `connectorCatalog` التي خضعت للمراجعة.
يضيف `authenticatedReads: "auto"` فقط الإجراءات التي تعلن صراحةً كل ما يلي:
- `http: { method: "GET" }`
- `readOnly: true`
- `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`
تجمع السياسة هذه الإجراءات مع أي إدخالات صريحة في `connectorCatalog`، ثم تطبق `denyActions`. مع `writes: "ask_app_only"` (الإعداد الافتراضي عند تمكين القراءة التلقائية)، لا يمكن استدعاء أدوات التغيير مباشرةً؛ وجّه العمل متعدد الخطوات وعمليات التغيير عبر `ask_app`. لا تستخدم `writes: "allowlisted"` إلا للتطبيقات التي تدير عمدًا قائمة سماح صريحة للكتابة.
هذه السياسة مصادق عليها وليست مجهولة. تستمر هوية MCP OAuth/connect عبر `runWithRequestContext`، لذلك تظل فحوصات الوصول على مستوى الإجراء ونطاق المالك/المؤسسة ونطاقات قراءة OAuth سارية. لا تتضمن القراءة التلقائية الإجراءات العامة أو غير المصادق عليها.
لا يتم تضمين `db-schema` و`db-query` الأساسيين تلقائيًا في القراءات الخارجية. يظلان متاحين لوكيل التطبيق داخل التطبيق عبر مسار SQL المقيّد المعتاد، لكن الوصول العام إلى المخطط وSQL واسع جدًا لاستنتاجه من بيانات القراءة فقط. إذا احتاج التطبيق إلى استعلام خارجي مباشر، فعليه إضافة action مملوك للتطبيق بحدود وصول واضحة أو قائمة سماح صريحة للجداول والأعمدة مع حدود للصفوف والبايت والمهلة والتدقيق. يبقى `db-exec` و`db-patch` خارج السطح التلقائي.
هذا استبعاد صارم يعتمد على الاسم، وليس مجرد إغفال في البيانات الوصفية: أدوات قاعدة البيانات وseed وجلسة المتصفح والامتدادات وسياق الأشعة السينية العامة لا يُكشف عنها تلقائيًا أبدًا، حتى لو وسم تغيير مستقبلي إحداها عن طريق الخطأ بمجموعة أعلام القراءة المصادق عليها الكاملة — فهي تتطلب دائمًا إدخالًا صريحًا في `connectorCatalog`.
يستبدل التطبيق الذي يوفّر `resolveExecutionContext` تسلسل الهوية الافتراضي هذا صراحةً. ويجب على أداة الحل الخاصة به أن ترفض بشكل مستقل المتصلين غير المتحقق منهم والضيوف والأعضاء الخارجيين ومساحات العمل غير المرتبطة قبل إرجاع هوية رئيسية.
تطابق رسائل Slack الخاصة التي تم التحقق منها عضوًا موجودًا في مؤسسة Agent-Native، وتحفظ رابط هوية مساحة العمل/المستخدم قبل تشغيل الوكيل؛ ثم يحمّل سياق المستخدم/المؤسسة الناتج موارد ذلك المستخدم وتعليماته ومهاراته. يُرفض افتراضيًا عضو مساحة العمل الذي نجح جلب بياناته لكن بريده الإلكتروني مفقود أو لم ينضم بعد إلى المؤسسة. يمكن للتطبيقات ضبط `allowAnonymousOrgScopedSlackDm: true` صراحةً لتشغيل هؤلاء الأعضاء بهوية خدمة مجهولة ضمن نطاق المؤسسة — وهي طبقة الرؤية نفسها على مستوى المؤسسة التي تستخدمها القنوات المشتركة، من دون أي وصول خاص بالمستخدم — مع ملاحظة يراها الوكيل وتنبيه لمرة واحدة في Slack يشرح كيفية الحصول على وصول شخصي. لا يسمح هذا الاشتراك أبدًا بحالات فشل جلب البيانات أو المتصلين غير المتحقق منهم أو الضيوف أو الأعضاء الخارجيين (Slack Connect) أو مساحات العمل غير المرتبطة بمؤسسة؛ بل تتلقى هذه الحالات ردًا مهذبًا بالرفض بدل إسقاط الرسالة بصمت. تستخدم قنوات Slack المشتركة هوية خدمة ولا تستعير الأذونات الخاصة لأي مشارك. يطلب OAuth المُدار والنموذج المُنشأ لتطبيق Slack نطاق البوت `users:read.email`. يجب إعادة ربط/تثبيت عمليات التثبيت الحالية لمنح نطاق أُضيف حديثًا، بينما يجب أن تضيف عمليات التثبيت القديمة التي تستخدم رمز بوت النطاق يدويًا في Slack. ومن دونه، تُرفض الرسائل الخاصة ما لم يفعّل التطبيق `allowAnonymousOrgScopedSlackDm` صراحةً.
### الطبقة الكاملة (الاشتراك الصريح فقط) {#full-tier}
يتم عرض سطح الإجراء الكامل المكون من 105 أداة فقط عند الاشتراك الصريح، بطريقتين:
- **لكل رمز** — تم إصداره باستخدام `--full-catalog`، والذي يتضمن مطالبة `catalog_scope: "full"` في JWT. تتجاوز الطلبات اللاحقة عامل التصفية المضغوط لهذا الرمز المميز:
```باش
npx @agent-native/core@latest Connect https://plan.agent-native.com --مخطوطة العميل --الكتالوج الكامل
```
- **لكل عملية نشر** — قم بتعيين `AGENT_NATIVE_MCP_FULL_CATALOG=1` (بيئة عملية الخادم) لخدمة السطح بالكامل لجميع المتصلين. استخدمه للمثيلات المستضافة لمستأجر واحد والتي تريد السطح الكامل بدون الاشتراك لكل رمز مميز.
### نموذج الإعلان {#catalog-declaration}
تعلن القوالب عن كتالوج الموصلات الخاصة بها في خيارات `createAgentChatPlugin`:
```ts
export default createAgentChatPlugin({
appId: "plan",
actions: loadActionsFromStaticRegistry(actionsRegistry),
connectorCatalog: [
"create-visual-plan",
"get-visual-plan",
"list-visual-plans",
"update-visual-plan",
// … other safe app-level actions
"set-resource-visibility",
"share-resource",
"upload-image",
"navigate",
"view-screen",
"manage-automations",
"tool-search",
],
});
```
الأدوات المدمجة عبر التطبيقات (`list_apps`، `open_app`، `ask_app`،
`create_embed_session`، `create_workspace_app`، `list_templates`) دائمًا
متضمن بغض النظر عن القائمة المعلنة.
## ما يمكنك فعله بمجرد الاتصال {#what-you-can-do}
بمجرد اتصال وكيلك، يحصل كل متصل على الكتالوج المدمج بشكل افتراضي
(راجع [Catalog tiers](#catalog-tiers)) - عملاء مطوري الكود/stdio، المحليين
الوكيل CLI ومضيفو الدردشة مثل Claude وChatGPT على حدٍ سواء. هذا السطح هو
التطبيق المُعلن عنه بواسطة القالب actions بالإضافة إلى الأفعال المضمنة عبر التطبيقات (`list_apps`،
`open_app` و`ask_app` ومساعد التضمين للتطبيق فقط). استخدم `ask_app` لتوجيه
مهمة باللغة الطبيعية من خلال وكيل التطبيق (نفس نقطة الدخول عبر التطبيقات
استخدامات [A2A](/docs/a2a-protocol)). `tool-search` موجود دائمًا، لذا فإن أي أداة
يظل من الممكن الوصول إلى خارج القائمة المدمجة عند الطلب. للحصول على أداة ~105
الظهور في المقدمة، الاشتراك بشكل صريح باستخدام `--full-catalog` أو
`AGENT_NATIVE_MCP_FULL_CATALOG=1`. وفي جميع الأحوال، اطلب من الوكيل القيام بعمل حقيقي
ويقوم بإرجاع رابط مباشرة إلى التطبيق قيد التشغيل:
```
> draft an email to John about the Q3 report
Claude Code calls: manage-draft(to: "john@example.com", subject: "Q3 Report", body: "…")
→ Open draft in Mail → https://mail.agent-native.com/_agent-native/open?app=mail&view=inbox&compose=…
```
انقر على هذا الرابط وسيتم فتح البريد مع استعادة المسودة - مع التركيز على مكان تواجدك، كمستخدم قام بتسجيل الدخول. لم يكن على الوكيل أن يعرف جلستك أبدًا؛ لقد أنتجت القطعة الأثرية للتو.
### توافق تطبيقات MCP {#mcp-apps-compatibility}
تتحدث التطبيقات الأصلية للوكيل أيضًا بامتداد MCP Apps الرسمي. عند القيام بأي إجراء
يعلن `mcpApp`، يعلن الخادم
`extensions["io.modelcontextprotocol/ui"]`، يتضمن `_meta.ui.resourceUri` /
`_meta["ui/resourceUri"]` في `tools/list`، ويخدم HTML UI حتى
`resources/list` + `resources/read` كـ `text/html;profile=mcp-app`. الموارد
البيانات الوصفية للأمان، مثل أذونات CSP ووضع الحماية موجودة على المورد
الإدخالات ومحتوى `resources/read`، وليس في واصف الأداة.
بالنسبة لمضيفي تطبيقات OAuth بنمط ChatGPT/Claude، يكون سطح الاكتشاف مضغوطًا بشكل افتراضي: يعلن `tools/list` و`resources/list` عن مسار التضمين العام `open_app` بدلاً من كل مورد تطبيق MCP خاص بالإجراء (راجع [Catalog tiers](#catalog-tiers)). قم بوضع علامة على إجراء فردي باستخدام `mcpApp.compactCatalog: true` فقط عندما يحتاج حقًا إلى أن يظل مرئيًا في اكتشاف مضيف الدردشة.
يؤدي ذلك إلى جعل سطح التطبيق نفسه متاحًا لكل مضيف متوافق بدلاً من إنشاء حشوات لكل عميل. المضيفون الذين يعرضون تطبيقات MCP مضمّنة (ومشكلة ذاكرة التخزين المؤقت للموصل بعد تغييرات البيانات التعريفية) يعيشون في [MCP Apps → Client support and caching](/docs/mcp-apps#client-support) - تلك الصفحة هي الصفحة الرئيسية الوحيدة لمصفوفة العميل.
في الممارسة العملية، يجب تأليف كل تطبيق أصلي للوكيل باستخدام كل من: MCP Apps للمراجعة/التحرير المضمن في الأجهزة المضيفة القادرة، و`link` للرجوع الشامل إلى التطبيق الكامل. عملاء CLI/محرر التعليمات البرمجية الذين لا يعرضون إطار iframe يتراجعون إلى الرابط العميق. يمكن لأدوات التحديد البشري إضافة خطوة لصق إلى هذا الإجراء الاحتياطي: على سبيل المثال، يفتح منتقي الأصول من الرابط الاحتياطي، ويتيح للمستخدم اختيار الوسائط في المتصفح، ثم ينسخ ملخص التسليم الذي يلصقه المستخدم مرة أخرى في الدردشة.
يحصل الوكلاء الخارجيون على أدوات الإنشاء/التحديث الحقيقية الخاصة بالتطبيق — نفس الإجراءات المسمّاة التي يستدعيها الوكيل داخل التطبيق — لذا عندما يطلب المستخدم محتوى جديدًا (تصميمًا، أو عرضًا تقديميًا، أو نموذجًا، أو مستندًا)، يجب تأليفه مباشرة وحفظه بتلك الأدوات بدلاً من تفويض العمل عبر `ask_app`. الإجراءات المُعلَّمة بـ `endsTurn: true`، مثل نموذج أسئلة داخل التطبيق ينتظر إجابة المستخدم في محادثة ذلك التطبيق نفسه، تكون مخفية عن MCP وWebMCP وA2A ما لم يُضبط `mcpTool: true` — راجع [endsTurn في تعريف Actions](/docs/actions-defining). تحمل مدخلات ونتائج الأدوات حتى 500,000 حرف على WebMCP، بحيث تتسع شاشة أو عرض تقديمي أو مستند كامل في عملية كتابة واحدة — راجع [WebMCP](/docs/webmcp). تحمل استدعاءات WebMCP المحلية للصفحة أيضًا معرّف علامة تبويب المتصفح (نفس قيمة `getBrowserTabId()` التي تستخدمها الواجهة — راجع [الوعي بالسياق](/docs/context-awareness))، بحيث يُحلّ التنقل والتحديد الخاصان بكل علامة تبويب إلى علامة التبويب التي يقودها الوكيل، حتى عندما تكون مخفية.
### جسر تطبيقات MCP من الدرجة الأولى {#mcp-app-bridge}
يبدأ `embedApp()` من هدف `link` للإجراء، وينشئ جلسة تضمين قصيرة الأجل, ويطلق مسار التطبيق الموقع. تستخدم شبكة Claude مسار زرع أحادي الإطار؛ يحصل ChatGPT على إطار iframe للمسار يتم التحكم فيه باستخدام مضيف `window.openai` APIs. تعرض كافة المسارات مسار React العادي. تستدعي المسارات المائية مباشرة `ui/update-model-context` و`ui/message` و`ui/open-link` و`ui/request-display-mode` عبر الجسر المضيف؛ يقوم مسار ChatGPT بترحيل نفس الطلبات عبر `agentNative.mcpHost.*` postMessage. `embedApp({ height })` الافتراضي هو `560px` ويتم تثبيته على `320-900px`.
راجع [MCP Apps](/docs/mcp-apps) للحصول على تفاصيل الجسر الكاملة - الزرع مقابل الإطار المتحكم فيه، وأوضاع التضمين، وجداول `ui/*` وpostMessage، وقواعد `embedStartUrl`، وقواعد CSP، وتضمين الامتداد `srcDoc`، وتثبيت الارتفاع، وعميل الجسر المضيف الكامل API.
### الأفعال العامة عبر التطبيقات {#cross-app}
علاوة على أدوات تنفيذ الإجراء، يعرض خادم MCP مجموعة أفعال ثابتة، بحيث يتمتع الوكيل الخارجي بسطح يمكن التنبؤ به دون تخمين أسماء الإجراءات لكل تطبيق:
| الأداة | الآثار الجانبية | المرتجعات |
| -------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_apps` | لا شيء | تطبيقات مساحة العمل + URL/حالة التشغيل |
| `open_app({ app, view?, path?, params?, embed? })` | لا شيء | رابط عميق أو مسار من نفس المصدر؛ يعرض `embed: true` التطبيق الكامل مضمنًا حيث يكون مدعومًا |
| `ask_app({ app, message, async?, maxWaitMs? })` | حلقة الوكيل | توجيه مهمة باللغة الطبيعية إلى الوكيل داخل التطبيق لذلك التطبيق؛ تُرجع المهام الطويلة `taskHandle` مع `taskId` قديم لاستطلاع `ask_app_status` |
| `create_workspace_app({ name, template })` | السقالات | تطبيق جديد تم تشغيله عبر مسار مساحة العمل، بالإضافة إلى URL قيد التشغيل + رابط عميق |
| `list_templates` | لا شيء | النماذج المسموح بها فقط |
يرفض `create_workspace_app` أي قالب غير مدرج في القائمة المسموح بها - القائمة المسموح بها للقالب العام في `packages/shared-app-config/templates.ts` موثوقة ومحمية بواسطة CI؛ ولا يمكن لعامل خارجي توسيعه. يتجاوز إجراء القالب الذي يحمل نفس الاسم الإجراء المدمج (أسبقية القالب على المركز الأساسي). قم بتعطيل المجموعة بأكملها باستخدام `MCPConfig.builtinCrossAppTools: false`.
يتم ضغط كتالوجات الأدوات والموارد لمضيفي التطبيقات بشكل افتراضي - راجع [Catalog tiers](#catalog-tiers). يظل `publicAgent.expose` خيار الاشتراك على مستوى الإجراء لأدوات القراءة/التناول الآمن خارج هذا الكتالوج المدمج؛ ويمكن للتطبيقات تعيين `externalAgents.authenticatedReads: "auto"` للإعلان عن عمليات القراءة المصادق عليها دون كتالوج مكتوب يدويًا. قم بتعيين `mcpApp.compactCatalog: true` فقط كاستثناء نادر لـ actions التي يجب أن تظهر في اكتشاف مضيف الدردشة.
بالنسبة لعمليات التسليم السريعة لـ ChatGPT/Claude، يكون المسار المثالي مباشرًا: اتصل بالإجراء الذي ينشئ القطعة الأثرية أو يفتحها، ثم اسمح لتطبيق MCP بتشغيل المسار. يجب أن يستدعي طلب البريد `manage_draft` ويقدم مسار الإنشاء الحقيقي. يجب أن يستدعي طلب لوحة المعلومات `open_app({ path, embed: true })` أو إجراء لوحة المعلومات باستخدام `mcpApp` ويقدم مسار Analytics الكامل. يجب أن يتبع التقويم والنماذج والمحتوى والشرائح والتصميم والمقاطع نفس النمط مع المسودة/الإنشاء/البحث في actions. يكون `list_apps` مفيدًا عندما يتعين على النموذج الاختيار من بين التطبيقات الممنوحة؛ لا ينبغي أن يكون `resources/list` واسع النطاق، أو اكتشاف الكتالوج الكامل، أو تفويض `ask_app` هو المسار الطبيعي لعملية تسليم UI الواضحة.
### الطلبات الوكيلية طويلة الأمد
عندما تُرجع `ask_app` قيمة `taskHandle`، مرّر هذه القيمة المعتمة دون تغيير إلى
`ask_app_status`؛ فهي تحفظ مسار المهمة الأصلي حتى إذا تغيّر اكتشاف التطبيقات بين
الاستدعاءات. تظل وسيطتا `app` و`taskId` الأقدم مقبولتين خلال فترة الانتقال.
لا تشترك مضيفات وبوابات MCP في مهلة زمنية واحدة طويلة لاستدعاء الأداة؛ يفرض بعضها حدًا أقصى مدته خمس دقائق بينما يكون بعضها الآخر قابلاً للتكوين. لا تصمم تكامل الوكيل الخارجي بالاعتماد على استدعاء `tools/call` محظور لمدة عشر دقائق. يقر كل من `ask-agent` و`ask_app` بالعمل المستضاف بسرعة، ثم يُرجعان `taskHandle` مع `taskId` قديم عند انتهاء مهلة الانتظار المضمّن. استطلع باستخدام `ask_app_status` عبر إعادة `poll.arguments` المُرجعة دون تغيير، ولا سيما `taskHandle`؛ وتتضمن النتيجة `pollAfterMs` كفاصل زمني ملائم للمضيف. يجب إنشاء المهمة قبل أن تنتهي مهلة الاستجابة الأولى، لذا فإن رابط الاستطلاع الذي يُرجع فقط بعد استدعاء طويل ليس عقد استرداد يمكن الاعتماد عليه.
عند عدم إتاحة قراءة حالة عابرة ومحدودة المدة، يمكن أن تُرجع `ask_app_status` القيم
`status: "unknown"` و`statusRead: "unavailable"` و`retryable: true`، إلى جانب
`app` و`taskId` الأصليين و`pollAfterMs` / `poll`. يعني ذلك أن قراءة الحالة غير
متاحة، وليس أن المهمة الدائمة قد فشلت. أعد محاولة `ask_app_status` باستخدام
`poll.arguments` المُرجعة نفسها، بما فيها `taskHandle` عند وجودها؛ أما النتائج القديمة
من دون مقبض فيجب أن تعيد استخدام `app` و`taskId` نفسيهما. لا تعِد إرسال `ask_app` للاسترداد مطلقًا، إذ قد يكرر
الإرسال العمل. تظل أخطاء المصادقة الدائمة أو عدم العثور أو البروتوكول أخطاءً.
### جولة لكل تطبيق {#tour}
يقوم كل قالب مدرج في القائمة المسموح بها ينتج موردًا قابلاً للملاحة أو يسرده بشحن أداة إنشاء `link`، وتقوم القوالب ذات الاستيعاب الثقيل بشحن إجراء GET + `publicAgent` حتى يتمكن الوكيل المتصل من سحب الحالة المباشرة:
- **البريد** — تقوم `manage-draft` بإرجاع رابط عميق مشفر بـ `compose`؛ يؤدي النقر فوقه إلى فتح البريد الوارد مع استعادة المسودة إلى `compose-<id>`. يشير `list-emails` / `search-emails` إلى طريقة عرض البريد الوارد التي تمت تصفيتها.
- **التقويم** — تقوم `manage-event-draft` بإرجاع رابط عميق `calendarDraft` + `eventDraftId`؛ يؤدي النقر عليه إلى فتح مسودة عنصر نائب مرئي في التقويم باستخدام محرر الأحداث الأصلي للمراجعة/الإرسال. لا يزال `create-event` يُرجع `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })`؛ تصل النقرة إلى التقويم مع تركيز هذا الحدث على تاريخه.
- **التحليلات** — `update-dashboard` / `save-analysis` تُرجع `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })`؛ ينشئ الوكيل لوحة معلومات على MCP ويعيد "فتح لوحة المعلومات في Analytics".
- **التصميم** — `get-design-snapshot` هو إجراء استيعاب GET + `publicAgent`: فهو يُرجع محتويات ملف **live** Yjs بالإضافة إلى قيم التعديل التي تم حلها بحيث يستمر الوكيل من التصميم المضبوط، وليس الرموز المميزة الأصلية. `apply-tweaks` ذهابًا وإيابًا باستخدام رابط محرر "التصميم المفتوح".
- **المحتوى** — `pull-document` هو إجراء استيعاب GET + `publicAgent`: فهو ينقل أي جلسة تعاونية مباشرة مفتوحة إلى SQL أولاً حتى يستوعب الوكيل الخارجي ما يراه المستخدم بالضبط، ثم يعرض رابطًا عميقًا للمستند.
- **Brain** — يعرض `ask-brain` / `search-everything` إجابة مستشهد بها بالإضافة إلى رابط عميق للمعرفة/الالتقاط الأساسي، بحيث يرتبط بحث وكيل المحطة مباشرة بالمصدر في التطبيق قيد التشغيل.
## التأليف (لمؤلفي النماذج) {#authoring}
كل ما ورد أعلاه مخصص **للمستخدمين** الذين يتصلون بالتطبيق ويستخدمونه. بقية هذه الصفحة مخصصة لـ **مؤلفي النماذج** الذين يقومون بتوصيل التطبيق ليكون مواطنًا وكيلًا خارجيًا صالحًا: منشئ `link`، وتطبيقات MCP الاختيارية UI، ومسار `/_agent-native/open` الداخلي، واستيعاب actions.
### منشئ `link` {#link-builder}
يقبل `defineAction` أداة إنشاء `link` الاختيارية. عند التعيين، تُلحق كل نتيجة MCP/A2A لتلك الأداة تلقائيًا كتلة `[label →](absoluteUrl)` وكتلة `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl, vscodeUrl }` المنظمة. يضيف `tools/list` `annotations["agent-native/producesOpenLink"]` ولاحقة وصف حتى يعرف الوكيل الخارجي أن الأداة تنتج رابطًا قابلاً للفتح ويجب أن يعرضه.
قم ببناء URL باستخدام `buildDeepLink(...)` - فهو المصدر الوحيد للحقيقة لتنسيق المسار المفتوح. لا تقم مطلقًا بتنسيق `/_agent-native/open` URL يدويًا.
مثال حقيقي — `manage-draft` للبريد (`templates/mail/actions/manage-draft.ts`):
```ts
import { buildDeepLink } from "@agent-native/core/server";
function composeDeepLink(draft: Record<string, string>): string {
return buildDeepLink({
app: "mail",
view: "inbox",
compose: encodeComposerDraft(draft), // base64url JSON → compose-<id> draft
});
}
export default defineAction({
// ...schema, run...
link: ({ result }) => {
if (!result || typeof result !== "object") return null;
const draft = (result as { draft?: Record<string, string> }).draft;
const id = (result as { id?: string }).id;
if (!draft || !id) return null;
return {
url: composeDeepLink(draft),
label: "Open draft in Mail",
view: "inbox",
};
},
});
```
تشير قائمة/بحث actions إلى عرض يركز على السجل بنفس الطريقة - على سبيل المثال. يُرجع `create-event` الخاص بالتقويم `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` بالتسمية `"Open event in Calendar"`. تستخدم مسودة التقويم actions نفس النمط: تقوم `manage-event-draft` بإرجاع `buildDeepLink({ app: "calendar", view: "calendar", to: "/", params: { eventDraftId, calendarDraft, date } })` مع التصنيف `"Review invite in Calendar"`، بحيث يمكن للوكلاء الخارجيين إعادة رابط مسودة المراجعة المباشر دون إنشاء الحدث أولاً.
### تطبيقات MCP الاختيارية UI {#mcp-apps}
يمكن لـ Actions الإعلان عن مورد UI المضمّن باستخدام `mcpApp` للمضيفين الذين يدعمون ملحق MCP Apps. استخدم `embedRoute({ title, openLabel, path })` كغلاف ملائم, أو قم بتعيين `embedApp(...)` إلى `mcpApp.resource` مباشرة. كل تطبيق MCP هو طريق React حقيقي، وليس عنصر واجهة مستخدم عادي منفصل HTML. احتفظ دائمًا بمنشئ `link` - يستخدمه مضيفو CLI فقط، والعملاء الأقدم، والمضيفون من غير MCP-Apps كبديل.
راجع [MCP Apps](/docs/mcp-apps) للحصول على دليل التأليف الكامل - `embedRoute` مقابل `embedApp`، وشكل تكوين `mcpApp`، وCSP، والارتفاع، ومسار التضمين `sendToAgentChat()`، ومساعدي عميل جسر المضيف.
### عقد `link` {#link-contract}
إن منشئ `link` **نقي ومتزامن — لا يوجد إدخال/إخراج، ولا انتظار**. يتم تشغيله بأقصى جهد: يتم ابتلاع رمية أو `null` أو `undefined` و **مطلقًا** يفشل استدعاء الأداة. فهو يقرأ فقط `args` و`result` للمكالمة؛ يجب ألا يستعلم عن قاعدة البيانات، أو يقرأ حالة التطبيق، أو يتصل بـ actions أخرى. قم بإرجاع `null` عندما لا يكون هناك شيء لفتحه.
ترجع `buildDeepLink({ app, view, params?, to?, compose? })` المسار النسبي للتطبيق `/_agent-native/open?app=…&view=…&<recordId>=…`. تحول طبقة MCP ذلك إلى شبكة مطلقة URL (`toAbsoluteOpenUrl`، باستخدام أصل الطلب)، وسطح مكتب `agentnative://open?…` URL (`toDesktopOpenUrl`), وامتداد VS Code URL (`toVsCodeOpenUrl`) لـ `vscode://builder.agent-native/open?url=…`؛ يستخدم رابط Markdown سطح المكتب URL عندما يشير العميل إلى `target: "desktop"`.
### مسار `/_agent-native/open` {#open-route}
عندما ينقر المستخدم على الرابط في أي متصفح أو عرض ويب مضمن، يقوم `GET /_agent-native/open` (`createOpenRouteHandler`، المثبت بواسطة البرنامج الإضافي للمسارات الأساسية) بتنفيذ الخطوات أدناه.
<Endpoint id="doc-block-1bwrrkb" method="GET" path="/_agent-native/open" summary={"المسار المفتوح للارتباط العميق — يركز المتصفح UI على سجل"} auth={"Browser session via `getSession`. The auth guard bypasses this exact path; if unauthenticated it serves login HTML at the same URL, and the form reload re-enters authenticated (no `?next=` plumbing)."} params={[
{
"name": "app",
"in": "query",
"type": "string",
"description": "Target app id (e.g. `mail`)."
},
{
"name": "view",
"in": "query",
"type": "string",
"description": "View to focus; also folded into the `navigate` payload."
},
{
"name": "to",
"in": "query",
"type": "string",
"description": "Optional explicit same-origin relative redirect target. Falls back to a per-template `resolveOpenPath`, then `/<view>`."
},
{
"name": "compose",
"in": "query",
"type": "string",
"description": "base64url-encoded draft, decoded into a `compose-<id>` application-state key."
},
{
"name": "f_*",
"in": "query",
"type": "string",
"description": "Filter params forwarded to the redirect so lists/dashboards open pre-filtered."
}
]} responses={[
{
"status": "302",
"description": "Redirect to a safe same-origin relative path. Cross-origin, scheme-relative `//host`, and control-char redirects are rejected (open-redirect guard)."
},
{
"status": "200",
"description": "Login HTML served at the same URL when the browser session is unauthenticated."
}
]}>
Resolves the browser session, writes a one-shot `navigate` application-state command scoped to that session, and 302-redirects to a safe same-origin path. Always build the URL with `buildDeepLink(...)`; never hand-format it. Can be disabled per app with `disableOpenRoute`.
</Endpoint>
1. حل جلسة **المتصفح** عبر `getSession` (يتجاوز حارس المصادقة المسار الدقيق `/_agent-native/open`).
2. إذا لم تتم مصادقته، فإنه يخدم تسجيل الدخول الذي تم تكوينه HTML **في نفس URL**; يقوم معالج نجاح النموذج بإعادة تحميل `window.location`، وإعادة إدخال المسار المصادق عليه - بدون سباكة `?next=`.
3. يكتب أمر حالة التطبيق `navigate` الموجود مرة واحدة (الحمولة = كل معلمة استعلام غير محجوزة + `view`) الذي يتم تحديد نطاقه على البريد الإلكتروني لجلسة المتصفح باستخدام `requestSource: "deep-link"`، ويفك تشفير مسودة `compose` base64url إلى مفتاح `compose-<id>`.
4. 302-يعيد التوجيه إلى مسار نسبي آمن من نفس الأصل (`to=`، أو `resolveOpenPath` لكل قالب، أو `/<view>`)، وإعادة توجيه معلمات مرشح `f_*` بحيث يتم فتح القوائم/لوحات المعلومات بعد تصفيتها مسبقًا قبل استنزاف أمر `navigate`.
يتم رفض عمليات إعادة توجيه `//host` ذات الأصل المشترك والنسبية للمخطط وحرف التحكم (حارس إعادة التوجيه المفتوح). يمكن تعطيل المسار لكل تطبيق عبر `disableOpenRoute`.
#### قاعدة هوية جلسة المتصفح {#identity-rule}
لا يحمل الرابط **أي حالة مميزة** — فهو مجرد `view` + معرفات السجلات + عوامل التصفية. يتم تحديد نطاق الكتابة `navigate` التي تركز على السجل على كل من قام بتسجيل الدخول إلى **المتصفح**، وليس الرمز المميز MCP للوكيل الخارجي أبدًا. لذا، يمكن للوكيل الذي تمت مصادقته كهوية واحدة أن يسلم المستخدم رابطًا، وعندما ينقر عليه هذا المستخدم، يتم فتح السجل حيث تم تسجيل دخول المستخدم. وهذا ما يجعل الرابط العميق آمنًا للظهور في المحطة الطرفية أو نص الدردشة. راجع [Context Awareness](/docs/context-awareness) للاطلاع على عقد `navigate` / `application_state` لهذه الجسور.
### استوعب actions {#ingest}
يجب أن يكون الإجراء الذي يقرأه وكيل خارجي لسحب حالة التطبيق المباشرة إلى سياقه الخاص:
```ts
export default defineAction({
description: "…",
schema: z.object({ id: z.string() }),
http: { method: "GET" },
readOnly: true,
publicAgent: { expose: true, readOnly: true, requiresAuth: true },
run: async ({ id }) => {
/* read LIVE state, not the stale DB snapshot column */
},
});
```
يبقي `GET` + `readOnly` الإجراء خاليًا من التأثيرات الجانبية وبعيدًا عن حدث تغيير تحديث الشاشة. `publicAgent` هو **الاشتراك الصريح** — مسار الويب العام لا يعني أبدًا التعرض العام لـ MCP/A2A؛ انظر [Actions](/docs/actions-overview). استيعاب التصميم/المحتوى actions MUST قراءة حالة **مباشرة** (مستند Yjs التعاوني، وليس عمود لقطة قاعدة بيانات قديمة) بحيث يرى الوكيل الخارجي ما يمتلكه المستخدم بالفعل على الشاشة. يقوم `pull-document` الخاص بالمحتوى بنقل أي جلسة تعاون مباشرة مفتوحة إلى SQL أولاً؛ يقوم `get-design-snapshot` الخاص بالتصميم بإرجاع محتويات ملف Yjs المباشر بالإضافة إلى قيم التعديل التي تم حلها بواسطة المستخدم.
## متقدم: التطوير المحلي والإعداد اليدوي {#advanced}
يعد تدفق `connect` المستضاف أعلاه هو المسار الموصى به. الخيارات أدناه مخصصة للتطوير المحلي والإعدادات اليدوية.
### التنمية المحلية {#local-dev}
قم بتشغيل تطبيقك محليًا (`pnpm dev` / `npx @agent-native/core@latest dev`)، ثم قم بتوجيه وكيل محلي إليه باستخدام أمر واحد:
```bash
npx @agent-native/core@latest mcp install --client claude-code|claude-code-cli|codex|cowork \
[--app <id>] [--scope user|project]
```
يقوم بتوفير رمز مميز (`ACCESS_TOKEN` عشوائي في مساحة العمل `.env` للتطوير المحلي، أو JWT موقع إذا اكتشف أصلًا مستضافًا) ويكتب إدخال خادم stdio غير فعال:
- **claude-code / claude-code-cli** — إدخال `mcpServers` في `.mcp.json` (نطاق المشروع، الافتراضي) أو `~/.claude.json` (`--scope user`).
- **العمل المشترك** — نفس شكل الرمز Claude JSON في `~/.cowork/mcp.json`.
- **codex** — كتلة `[mcp_servers.<name>]` في `~/.codex/config.toml`.
يعمل الإدخال على تشغيل `npx @agent-native/core@latest mcp serve --app <id>`، وهو افتراضيًا ** وكيل stdio رفيع ** إلى `/mcp` للتطبيق المحلي قيد التشغيل - لذا يظل سجل الإجراء المباشر، HMR، والروابط العميقة الصحيحة المصدر الوحيد للحقيقة. قم بتمرير `--standalone` لإنشاء التسجيل قيد التشغيل بدلاً من ذلك. عندما يكتشف `npx @agent-native/core@latest mcp install` أصلًا مستضافًا (مضيف غير محلي `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL` في مساحة العمل `.env`)، فإنه يكتب إدخال عميل `http` يشير إلى `<origin>/mcp` باستخدام `Bearer` JWT بدلاً من إدخال stdio.
الأوامر الفرعية المصاحبة:
| الأمر | ماذا يفعل |
| ---------------------------------------------------------- | -------------------------------------------------------------------------- |
| `npx @agent-native/core@latest mcp serve [--app <id>]` | قم بتشغيل نقل MCP stdio (ما هي تكوينات العميل التي يتم نشرها). |
| `npx @agent-native/core@latest mcp install --client <c>` | توفير رمز مميز + كتابة تهيئة MCP للعميل (الفعال). |
| `npx @agent-native/core@latest mcp uninstall --client <c>` | قم بإزالة إدخال MCP المسمى من تكوين العميل (Idempotent). |
| `npx @agent-native/core@latest mcp status` | إظهار MCP URL/المنفذ الذي تم حله، وحالة الرمز المميز، والإدخالات لكل عميل. |
| `npx @agent-native/core@latest mcp token [--rotate]` | اطبع (أو قم بتدوير) `ACCESS_TOKEN` المحلي في مساحة العمل `.env`. |
أعد تشغيل العميل بعد `install` حتى يلتقط خادم MCP الجديد.
### إدخال `.mcp.json` HTTP يدويًا {#manual-entry}
يمكنك أيضًا كتابة تكوين عميل MCP يدويًا على أي نقطة نهاية منشورة باستخدام رمز مميز توفره بنفسك (`ACCESS_TOKEN`، أو `A2A_SECRET` JWT يحمل توقيع المتصل `sub` + `org_domain` بحيث يظل تشغيل الأداة ضمن نطاق المستأجر):
```jsonc
// .mcp.json
{
"mcpServers": {
"analytics": {
"type": "http",
"url": "https://analytics.agent-native.com/mcp",
"headers": { "Authorization": "Bearer <ACCESS_TOKEN-or-JWT>" },
},
},
}
```
هذا هو المعادل غير المُدار لما يكتبه لك `connect`. راجع [MCP Protocol](/docs/mcp-protocol) للاطلاع على مصفوفة المصادقة الكاملة env-var.
### سطح أداة التطوير مقابل أداة الإنتاج {#dev-vs-prod}
في التطوير المحلي البسيط (`NODE_ENV=development` و`AGENT_MODE !== "production"`)، يكشف MCP `tools/list` عمدا فقط عن الإضافات العامة بالإضافة إلى actions مع `publicAgent.requiresAuth === false` - استيعاب كل تطبيق actions (`requiresAuth: true`) وتحور actions (لا `publicAgent`) يتم تصفيتها (`filterPublicAgentActions`). الكتالوج المدمج هو الإعداد الافتراضي لكل متصل بعد المصادقة - عملاء stdio/code الذين يستخدمون وكيل `agent-native`، وCLI المحلي، والمتصلين عن بعد بنمط الدردشة HTTP على حد سواء - لذلك لا يمكن لـ ChatGPT/Claude (أو أي عميل) تفريغ كتالوج إجراءات كامل ضخم في المحادثة. يتم تقديم كتالوج المطورين الكامل فقط عند الاشتراك الصريح (رمز `--full-catalog` أو `AGENT_NATIVE_MCP_FULL_CATALOG=1`)؛ `tool-search` يبقي كل أداة في متناول اليد في هذه الأثناء.
### تبديل تطبيقات الطرف الأول بين المنتج والمطور {#dev-switch}
عندما تكون لديك بالفعل تطبيقات مستضافة للطرف الأول متصلة وتريد اختبار تغييرات إطار العمل المحلي من خلال `pnpm dev:lazy`، استخدم مبدل المطورين:
```bash
pnpm dev:lazy -- --apps mail,calendar,analytics
npx @agent-native/core@latest connect dev --apps mail,calendar,analytics --client codex
```
يعيد `connect dev` كتابة نفس أسماء خوادم MCP المستقرة (`agent-native-mail`، `agent-native-calendar`، وما إلى ذلك) إلى بوابة التطوير المحلية البطيئة، لذلك لا تتغير أسماء الأدوات. يقوم بعمل نسخة احتياطية لإدخالات الإنتاج الحالية في `~/.agent-native/connect-profiles.json` قبل كتابة إدخالات التطوير. البوابة الافتراضية هي `http://127.0.0.1:8080`؛ استخدم `--gateway <url>` أو `--port <n>` إذا تم نقل بوابتك.
التبديل مرة أخرى باستخدام:
```bash
npx @agent-native/core@latest connect prod --apps mail,calendar,analytics --client codex
```
إذا لم يتمكن `connect dev` من استنتاج هوية المالك المحلي الخاصة بك من JWT المتصل الحالي، فقم بتمرير `--owner-email you@example.com`؛ يؤدي هذا إلى إبقاء أدوات التطوير المحلية على سطح MCP المصادق بالكامل بدلاً من سطح التطوير المتناثر غير المصادق.
## كيفية العمل والأمان {#how-it-works}
لا يكشف مسار OAuth القياسي أبدًا الرموز المميزة لتطبيقات MCP: يقوم المضيف بتخزين الرموز المميزة للوصول/التحديث إلى OAuth ويتوسط استدعاءات الأدوات و`resources/read` عبر اتصال MCP المصادق عليه. تتلقى إطارات iframe المضمنة بيانات التطبيق ونتائج الأدوات، وليس أسرار حاملها.
تتجنب عمليات تضمين التطبيق الكامل أيضًا تسليم الرمز المميز لحامل MCP إلى المتصفح. يقوم المتصل MCP بإصدار تذكرة مضمنة لمرة واحدة في SQL؛ يستهلكه مسار تشغيل iframe ويقوم بتعيين ملف تعريف ارتباط قصير العمر وآمن لجلسة iframe. يحمل URL الهبوطي معلمة استعلام `__an_embed_token` مؤقتة لفترة كافية فقط ليتمكن العميل من التقاطها وإزالتها من شريط العناوين وإرفاقها باستدعاءات `fetch` من نفس المصدر عند حظر ملفات تعريف الارتباط التابعة لجهات خارجية. يتم تحديد نطاق جلسات التضمين؛ تتضمن عمليات جلب التطبيق الهدف المضمن الحالي، ويرفض الخادم إعادة استخدام الرمز المميز خارج المسار المسكوك. لا تقوم صفحات التطبيق عمدًا بإصدار `X-Frame-Options` أو CSP `frame-ancestors`، لذا يمكن لمضيفي تطبيقات Builder وDesign وMCP وضع إطار iframe لها. يتم أيضًا تمكين التنقل عبر iframe في المتصفح COEP/CORP عند الحاجة للمضيفين المعزولين من مصادر مشتركة.
لا يقوم تدفق `connect` المستضاف الاحتياطي بنسخ السر المشترك للنشر مطلقًا. بدلاً من ذلك:
- تقوم جلسة المتصفح التي تم تسجيل الدخول بإصدار رمز مميز **لكل مستخدم، محدد النطاق، قابل للإلغاء** — `A2A_SECRET` موقع JWT يحمل `sub` + `org_domain` للمتصل و`jti` فريد من نوعه، بحيث تظل كل أداة يتم تشغيلها ضمن نطاق المستأجر عبر `runWithRequestContext`.
- تقبل نقطة النهاية `/mcp` الحالية هذا الرمز المميز مثل أي حامل آخر (راجع [MCP Protocol](/docs/mcp-protocol)) - لا توجد نقطة نهاية جديدة ولا نقل جديد.
- تدرج نفس صفحة الاتصال كل الرموز المميزة التي قمت بسكها وتتيح لك **إلغاء** أيًا منها بواسطة `jti`. تعامل معها مثل رموز الوصول الشخصية: واحدة لكل عميل وكيل، ويتم إبطالها عند إيقاف تشغيل الجهاز.
- لا يحمل الرابط العميق الذي يعيده الوكيل أي حالة مميزة. يتم دائمًا تحديد نطاق كتابة `navigate` التي تركز على السجل على جلسة **المتصفح**، وليس الرمز المميز للوكيل أبدًا — لذلك يكون الرابط آمنًا للصقه في محطة طرفية أو نص دردشة.
## افعل / لا تفعل {#do-dont}
**افعل**
- قم بتوصيل وكيلك الخاص بـ Dispatch باستخدام `npx @agent-native/core@latest connect https://dispatch.agent-native.com`؛ استخدم التطبيق المباشر URL فقط عندما تريد تطبيقًا واحدًا معزولًا.
- أضف منشئ `link` إلى أي إجراء ينتج عنه أو يدرج موردًا قابلاً للتنقل (مسودة، حدث، لوحة معلومات، مستند).
- قم ببناء URL باستخدام `buildDeepLink(...)` — المصدر الوحيد للحقيقة لتنسيق المسار المفتوح.
- حافظ على `link` نقيًا ومتزامنًا؛ قم بإرجاع `null` عندما لا يكون هناك شيء لفتحه.
- اجعل الوكيل الخارجي يستوعب actions GET + `readOnly` + `publicAgent`، واقرأ الحالة المباشرة (Yjs)، وليس عمود قاعدة البيانات التي لا معنى لها.
- السماح للمسار المفتوح بحل جلسة المتصفح؛ قم بتمرير معرفات السجل كمعلمات الارتباط العميق واترك UI يركز عليها عبر أمر `navigate` الذي تم استطلاعه.
- قم بإلغاء رمز الاتصال المميز بواسطة `jti` عندما يتم إيقاف تشغيل عميل الوكيل.
- اختبر تطبيقات MCP باستخدام التركيبات خفيفة الوزن حول `embedApp()` و
`McpAppRenderer`; they cover CSP, host context, app launch, and bridge
سلوك الرسالة دون الحاجة إلى مضيف خارجي حقيقي.
- عند التحقق من صحة الويب ChatGPT أو Claude، قم بتشغيل استدعاء أداة جديد بعد الصدفة
يقوم بتغيير وقياس إطار iframe المرئي. الإطارات المعروضة مسبقًا في
قد تستمر نفس المحادثة في إظهار الارتفاع المخبأ أو سلوك التشغيل.
- احتفظ بكتالوجات مضيف التطبيق ChatGPT/Claude مضغوطة. استخدم ديسباتش و
`open_app({ embed: true })` لمعاينات التطبيق الكامل؛ ضع علامة على
الإجراء `mcpApp.compactCatalog: true` عندما يجب أن يظهر مباشرةً في
سطح اكتشاف المضيف المضغوط.
**لا تفعل ذلك**
- انسخ `ACCESS_TOKEN` / `A2A_SECRET` المشترك لعملية النشر إلى تكوين العميل عندما يتمكن `connect` من سك رمز مميز قابل للإلغاء لكل مستخدم بدلاً من ذلك.
- قم بتنسيق `/_agent-native/open` URL يدويًا — انتقل دائمًا عبر `buildDeepLink`.
- إجراء الإدخال/الإخراج، أو الانتظار، أو قراءة قاعدة البيانات، أو قراءة حالة التطبيق داخل منشئ `link`.
- حدد نطاق الكتابة `navigate` إلى الرمز المميز للوكيل، أو قم بتمرير الحالة المميزة من خلال الرابط العميق - إنه مؤشر خالص.
- اخترع آلية تنقل جديدة؛ جسر إلى عقد `navigate` / `application_state` الحالي.
- قم بتوسيع القائمة المسموح بها للنموذج العام عند دعم تطبيق من وكيل خارجي - تكون القائمة المسموح بها موثوقة ومحمية.
## ذات صلة {#related}
- [MCP Apps](/docs/mcp-apps) — تأليف تطبيق MCP UI، والجسر المضمن، والجسر المضيف API.
- [WebMCP](/docs/webmcp) — أدوات محلية للصفحة، وحد 500,000 حرف للمدخلات/النتائج، ورأس معرّف علامة تبويب المتصفح.
- [MCP Protocol](/docs/mcp-protocol) — خادم MCP المثبت تلقائيًا والأداة التعريفية `ask-agent`.
- [MCP Clients](/docs/mcp-clients) — الاتجاه المتماثل: يستهلك تطبيقك خوادم MCP المحلية/البعيدة.
- [A2A Protocol](/docs/a2a-protocol) — الأداة التعريفية `ask-agent` واستدعاءات الأقران JSON-RPC.
- [Actions](/docs/actions-overview) — تعريف actions، `publicAgent`، GET / `readOnly`.
- [Context Awareness](/docs/context-awareness) — يتعاقد `navigate` / `application_state` على جسور المسار المفتوح.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |