Client Setup

يرى كل عميل أدناه الأدوات المعلنة نفسها وعددها 31 أداة، ويُقرأ العدد من الخادم المباشر. اعتمد على استجابة tools/list من الخادم المتصل.

يربط هذا الدليل خادم Minds MCP لأبحاث السوق بعملاء الذكاء الاصطناعي الذين يدعمون الأدوات البعيدة. استخدم https://getminds.ai/mcp كرابط الخادم.

ChatGPT

استخدم ChatGPT على الويب. يعتمد التوفر والأذونات على الحساب ومساحة العمل؛ راجع إرشادات OpenAI الحالية لإعداد MCP.

1. افتح Plugins واختر Add ← Create MCP App. إذا لم يظهر الخيار، فعّل وضع المطوّر أو اطلب من مسؤول مساحة العمل السماح بتطبيقات MCP المخصصة.
2. سمِّ التطبيق Minds، وأدخل https://getminds.ai/mcp في Server URL، واختر OAuth في Authentication، وأكّد تنبيه المخاطر، ثم انقر Create.
3. انقر Continue to Minds، وسجّل الدخول إلى حساب Minds، واختر Allow.
4. في محادثة جديدة اكتب @Minds واطلب قائمة Audiences. تتطلب Studies الأوسع مراجعة وتأكيدًا صريحًا قبل التنفيذ.

إذا ظهر Minds في دليل الإضافات لحسابك، يمكنك أيضًا إضافته من Plugins وتسجيل الدخول بالطريقة نفسها.

في تطبيق ChatGPT لسطح المكتب، افتح Plugins واختر Add → Add MCP server. اضبط النوع على Streamable HTTP والعنوان على https://getminds.ai/mcp، وانقر Save ثم Restart، ثم اختر Authenticate لتسجيل الدخول إلى Minds.

يعرض دليل إعداد ChatGPT كل شاشة، بما في ذلك خياري دليل الإضافات وتطبيق سطح المكتب.

يمكن للبيئات المتوافقة على الويب عرض النتائج داخل المحادثة. على الهاتف تقدم ودجة Minds المعروضة رابطا للمتابعة في Minds بدلا من عناصر التحكم التفاعلية.

Claude (claude.ai وClaude Desktop)

موصل بعيد (دعم الودجات حسب العميل)

تعمل الموصلات المخصصة بالطريقة نفسها على claude.ai وفي Claude Desktop، وتتم مزامنتها بينهما.

1. افتح Customize ← Connectors، وانقر +، واختر Add custom connector
2. أدخل https://getminds.ai/mcp كعنوان خادم MCP البعيد وانقر Add
3. انقر Connect، وسجّل الدخول إلى حساب Minds، واختر Allow
4. في المحادثة، فعّل Minds من + ← Connectors

في خطط Team وEnterprise، يضيف المالك الموصل أولًا ضمن Organization settings ← Connectors؛ ثم يربط الأعضاء حسابات Minds الخاصة بهم ضمن Customize ← Connectors.

Option B: Local Connector (API key، نص فقط)

أضف إلى ملف التهيئة (~/Library/Application Support/Claude/claude_desktop_config.json على macOS):

{
  "mcpServers": {
    "mindsai": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://getminds.ai/mcp",
        "--header",
        "Authorization: Bearer minds_YOUR_API_KEY"
      ]
    }
  }
}

أعد تشغيل Claude Desktop. الأدوات تعمل فوراً لكن الـ widgets التفاعلية غير متاحة مع الـ local connectors.

دعم Widget في Claude

تُرجع الأدوات المُعلنة ردوداً نصية مع روابط قابلة للنقر لفتح النتائج في webapp الخاص بـ Minds. ويُبقي الخادم أيضاً أدوات دورة حياة أساسية إضافية قابلة للاستدعاء للتكاملات الصريحة؛ راجع مرجع الأدوات. يعتمد سلوك الـ widgets التفاعلية على العميل وإصداره، لذلك يجب أن يبقى التكامل قابلاً للاستخدام بالكامل من النتائج النصية والمنظمة دون افتراض أن الـ widget قد عُرضت.

Claude Code (CLI)

claude mcp add --transport http minds https://getminds.ai/mcp

شغّل /mcp في Claude Code، واختر minds، ثم اختر Authenticate لتسجيل الدخول عبر OAuth. مفتاح API اختياري: لاستخدامه بدلاً من ذلك، أضف --header "Authorization: Bearer minds_YOUR_API_KEY" إلى الأمر.

Codex

باستخدام Codex CLI:

codex mcp add minds --url https://getminds.ai/mcp
codex mcp login minds

يفتح codex mcp login صفحة تسجيل الدخول إلى Minds. يسجّل Codex نفسه باستخدام Client ID Metadata Document، لذلك لا تحتاج إلى client ID أو secret.

في تطبيق Codex أو إضافة IDE، افتح Settings → MCP servers، واختر Add server، ثم Streamable HTTP، وأدخل https://getminds.ai/mcp. احفظ وأعد التشغيل، ثم اختر Authenticate.

لاستخدام مفتاح API بدلاً من ذلك، اضبط bearer_token_env_var = "MINDS_API_KEY" ضمن [mcp_servers.minds] في ~/.codex/config.toml وصدّر المفتاح في ذلك المتغير.

Gemini CLI

أضف الخادم إلى ~/.gemini/settings.json:

{
  "mcpServers": {
    "minds": { "httpUrl": "https://getminds.ai/mcp" }
  }
}

أو شغّل gemini mcp add --transport http minds https://getminds.ai/mcp. يكتشف Gemini CLI إعدادات OAuth من الخادم ويفتح صفحة تسجيل الدخول عند أول استخدام. يمكنك أيضاً تشغيل /mcp auth minds.

Google Antigravity

أضف الخادم إلى ~/.gemini/config/mcp_config.json (أو إلى .agents/mcp_config.json في مساحة عمل). يحتاج Antigravity إلى serverUrl؛ ولا يقبل url أو httpUrl:

{
  "mcpServers": {
    "minds": { "serverUrl": "https://getminds.ai/mcp" }
  }
}

أو شغّل agy mcp add --type http minds https://getminds.ai/mcp. لتسجيل الدخول افتح Settings ← Customizations، واختر Authenticate بجوار minds، ثم الصق الرمز الذي يظهر بعد تسجيل الدخول. يشرح دليل Minds في Google Antigravity تثبيت الإضافة ومفاتيح API.

Cursor

1. أضف الخادم إلى ~/.cursor/mcp.json، أو إلى .cursor/mcp.json داخل مشروع:

{
  "mcpServers": {
    "minds": { "url": "https://getminds.ai/mcp" }
  }
}

2. صادِق عندما يطلب Cursor ذلك، وسجّل الدخول إلى Minds.

VS Code (GitHub Copilot)

1. شغّل MCP: Add Server من لوحة الأوامر، واختر HTTP، وأدخل https://getminds.ai/mcp. أو أضفه إلى .vscode/mcp.json:

{
  "servers": {
    "minds": { "type": "http", "url": "https://getminds.ai/mcp" }
  }
}

2. شغّل الخادم واسمح لـ VS Code بتسجيل الدخول إلى Minds عند الطلب. تظهر أدوات Minds بعد ذلك في Copilot Chat في وضع agent.

Windsurf

في لوحة Cascade، افتح القائمة … واختر Open MCP config file. أضف Minds ضمن mcpServers:

{
  "mcpServers": {
    "minds": { "serverUrl": "https://getminds.ai/mcp" }
  }
}

احفظ الملف، ثم سجّل الدخول إلى Minds عندما يطلب Windsurf ذلك. لاستخدام مفتاح API بدلاً من ذلك، أضف "headers": { "Authorization": "Bearer ${env:MINDS_API_KEY}" } إلى الإدخال.

OpenRouter وOpen WebUI والبوابات المتوافقة مع OpenAI

تعتمد المصادقة على العميل الذي ينفذ طلب MCP وبيانات الاعتماد التي يمررها. مفتاح مزود النموذج لا يصادق الطلب لدى Minds.

تمرير رمز OAuth

تقبل واجهة Responses من OpenAI رمز وصول OAuth موجودًا في حقل authorization لأداة MCP. يتولى تطبيقك التفويض والتجديد بشكل منفصل ويرسل الرمز في كل طلب. راجع دليل OpenAI لمصادقة MCP.

Open WebUI / OpenRouter

اضبط اتصال Streamable HTTP إلى https://getminds.ai/mcp. إذا كان العميل أو وضع التنفيذ لا يستطيع إكمال OAuth وتمرير الرمز، فأنشئ مفتاح Minds من الإعدادات ← مفاتيح API واضبط مصادقة Bearer باستخدام مخزن الأسرار لدى العميل. اختبر باستخدام list_audiences. تحقق من دعم MCP الحالي وصيغة الوصف لدى OpenRouter والبوابات الأخرى؛ توافق Chat Completions مع OpenAI وحده لا يضمن دعم MCP البعيد.

مثال واجهة Responses من OpenAI

يقرأ المثال مفتاح Minds من متغير بيئة. لاستخدام OAuth، استبدل headers بالقيمة "authorization": os.environ["MINDS_OAUTH_ACCESS_TOKEN"] بعد أن يحصل تطبيقك على رمز Minds صالح.

import os
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5.2",
    input="List my Audiences",
    tools=[{
        "type": "mcp",
        "server_label": "minds",
        "server_url": "https://getminds.ai/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['MINDS_API_KEY']}"},
        "allowed_tools": ["list_audiences"],
        "require_approval": "never",
    }],
)
print(response.output_text)

مصادقة API Key

للوصول البرمجي أو العملاء الذين لا يدعمون OAuth:

1. افتح Settings → API Keys في Minds
2. أنشئ مفتاح API جديداً (يبدأ بـ minds_)
3. مرِّره كـ Bearer token: Authorization: Bearer minds_your_key_here

Scopes

تطلب عملاء OAuth أذونات OpenID الأساسية (openid وemail وprofile) ونطاقات Minds الواردة أدناه. تعرض شاشة موافقة Minds كل نطاق بمصطلحات المنتج قبل أن تختار Allow. العميل الذي لا يطلب أي نطاق يحصل على جميع النطاقات.

OAuth Discovery

للمطورين الذين يبنون تكاملات MCP، تتوفر OAuth metadata في:

OAuth 2.1 مع PKCE (S256) مطلوب. العملاء العامون (token_endpoint_auth_method: "none") مدعومون.

يمكن للعملاء الأصليين تسجيل عناوين إعادة توجيه loopback (http://127.0.0.1 وhttp://localhost وhttp://[::1])؛ لا تتم مطابقة المنفذ، لذا يمكن للعميل الاستماع على أي منفذ متاح (RFC 8252). يمكن للعميل أيضاً استخدام Client ID Metadata Document: عنوان https يُستخدم كـ client_id وينشر بيانات العميل الوصفية (client_id_metadata_document_supported: true). تقبل نقطة نهاية الرمز المميز client_id في جسم الطلب أو عبر مصادقة HTTP Basic بسرّ فارغ.

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

خطأ "Authentication required"

تأكد من إكمال تدفق تفويض OAuth. افصل عميل MCP وأعد اتصاله لإعادة التفويض.

تحقق من أن المكون المنفذ لطلبات MCP يمرر بيانات Bearer صالحة لـ Minds. أعد توصيل OAuth أو جدد الرمز عبر العميل المسؤول عنه؛ استخدم مفتاح API إذا كان التكامل لا يمرر رموز OAuth. مفتاح المزود أو تسجيل الدخول إلى المضيف لا يحل محل بيانات Minds.

‏"Not authorized" لـ Study أو Audience أو Mind يمكنك فتحها في Minds

عميل MCP مسجّل الدخول بحساب Minds مختلف عن الحساب الذي يملك العنصر؛ تذكر رسالة الخطأ الحساب المتصل. أعد ربط العميل بالحساب المالك، أو شارك العنصر مع الحساب المتصل.

OAuth في Claude Desktop لا يكتمل

إذا فُتحت نافذة OAuth المنبثقة لكنها لم تكتمل أبداً، جرِّب نهج API key (Option B أعلاه). OAuth في remote connector الخاص بـ Claude Desktop قد يكون متقطعاً.

Mind غير موجود

عند استخدام mindName، تأكد من أن الاسم يطابق الـ Mind الخاص بك بشكل وثيق. يستخدم النظام fuzzy matching لكنه يتطلب درجة تشابه معقولة.

Mind لا يزال يتدرب

قد تستغرق الـ Minds الجديدة لحظة لإكمال التدريب. استخدم get_mind_status للتحقق من اكتمال التدريب قبل الدردشة.

انتهاء مهلة سؤال الـ Study

أسئلة الـ study مع audiences كثيرة قد تستغرق أكثر من دقيقتين. حاول تقليل عدد الـ audiences أو تبسيط السؤال.

تصدير PDF غير جاهز

تُنفذ عمليات التصدير بشكل غير متزامن. استعلم عبر get_study_status باستخدام studyId نفسه وقيم exportKind وexportFormat وexportJobId الدقيقة التي أعادها export_study. تحقق من حالة المهمة ورابط التنزيل؛ تختلف مدة الإنشاء. انتهاء مهلة الاستعلام لا يسمح بتصدير مكرر.

النتائج تواصل التحميل أو تبدو ناقصة

تستقبل الودجات تحديثات العميل وتستعلم عن الحالة تلقائيا لمدة محدودة حيث يسمح العميل بذلك. لا يضمن هذا تدفق الرموز باستمرار. وإلا فاستخدم التحديث عند ظهوره، أو اطلب حالة Study الحالية، أو اتبع رابط Minds المعاد.

استخدم get_study_status للسؤال المباشر وget_study_run للخطة المؤكدة. احتفظ بنفس studyId؛ التحميل أو انتهاء المهلة لا يبرر إعادة التنفيذ. وضح الإجابات الجزئية ونقص تغطيتها. انتهاء الأسئلة لا يثبت أن كل Mind أجاب.

سير عمل n8n

استخدم عقدة مجتمع Minds لـ n8n لإنشاء دراسات، ومعاينة خطط البحث، واسترجاع الدراسات والملخصات المحفوظة، أو عرض عملية لوكيل ذكاء اصطناعي. قم بتثبيت n8n-nodes-minds على n8n المستضاف ذاتياً وقم بتوصيل مفتاح Minds API. الحزمة منشورة على npm؛ والتحقق من n8n قيد المراجعة، لذا فهي غير متاحة بعد على n8n Cloud. راجع البحث وابدأه بشكل منفصل في Minds.