Mcp

پیکربندی کلاینت#

این صفحه نشان می‌دهد رایج‌ترین کلاینت‌های MCP چگونه به /mcp/business وصل می‌شوند. سرور با Streamable HTTP و یک توکن bearer سخن می‌گوید، بنابراین هر کلاینتی که MCP روی HTTP را بفهمد کار می‌کند؛ کلاینت‌های فقط-stdio به یک پل کوچک نیاز دارند.

پیش از آغاز، یک اعتبارنامه با صلاحیت‌هایی که دستیار نیاز دارد بسازید و سرّ آن را یادداشت کنید.

مقادیری که لازم دارید#

مقدار	مثال	از کجا پیدا شود
URL پایه	`https://app.example.com`	URL استقرار شما
endpoint MCP	`/mcp/business`	مسیر ثابت
توکن	`12`	abc...`	تنظیمات > یکپارچه‌سازی‌های API
شعبه	`4`	فروشگاه > شعبه‌ها، یا `/api/v2/context`

کلاینت‌های Streamable HTTP#

کلاینت‌هایی که سرورهای MCP دوردست را می‌فهمند معمولاً یک URL به‌همراه سرصفحه‌ها را می‌پذیرند:

json

{
  "mcpServers": {
    "layatanahi": {
      "url": "https://app.example.com/mcp/business",
      "headers": {
        "Authorization": "Bearer 12|your-secret",
        "X-Business-Branch": "4"
      }
    }
  }
}

برخی ویرایشگرها به‌جای mcpServers از servers استفاده می‌کنند، یا یک فرم UI با فیلدهای جدا برای URL و سرصفحه‌ها دارند. مقادیر همان‌اند: URL endpoint، توکن bearer و سرصفحه اختیاری شعبه.

فایل پیکربندی را بیرون از کنترل نسخه نگه دارید، یا اگر کلاینت درون‌گذاری (interpolation) را پشتیبانی می‌کند، به متغیر محیطی مانند ${LAYATANAHI_TOKEN} ارجاع دهید.

کلاینت‌های فقط-stdio#

کلاینت‌های رومیزی که یک پروسه محلی را بلند می‌کنند به پلی نیاز دارند که stdio را به HTTP هدایت کند. پل پرکاربرد mcp-remote همین کار را می‌کند:

json

{
  "mcpServers": {
    "layatanahi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.example.com/mcp/business",
        "--header",
        "Authorization: Bearer ${LAYATANAHI_TOKEN}",
        "--header",
        "X-Business-Branch: 4"
      ],
      "env": {
        "LAYATANAHI_TOKEN": "12|your-secret"
      }
    }
  }
}

پل، شناسه نشست را نگه می‌دارد و پیام‌های JSON-RPC را پیش می‌فرستد. اگر کلاینت شما HTTP دوردست را بومی پشتیبانی می‌کند، آن را بر پل ترجیح دهید.

نکات ویژه هر محیط#

محیط	نکته
توسعه محلی	از محوطه آزمون محلی در `/mcp/business/test` استفاده کنید؛ توکن و سهمیه لازم نیست
staging	از اعتبارنامه staging استفاده کنید، هرگز داده production
production	فقط HTTPS؛ اعتبارنامه را طبق برنامه گردش دهید
پشت پروکسی	بافرینگ پاسخ را برای مسیر MCP غیرفعال کنید

محوطه آزمون محلی تنها زمانی وجود دارد که برنامه با APP_DEBUG=true در local یا testing اجرا شود. آن به تجارت #1 متصل است و خواندن به کل تجارت را می‌دهد.

تأیید اتصال#

از کلاینت بخواهید ابزارها را فهرست کند. باید products، stock، purchases، orders و sales را ببینید.
products را با per_page: 1 فراخوانی کنید. نتیجه، احراز هویت را تأیید می‌کند.
sales را بدون branch_id روی یک اعتبارنامه چندشعبه‌ای فراخوانی کنید. خطای branch_required تأیید می‌کند که تحمیل شعبه فعال است.
ابزاری را که صلاحیتش را اعطا نکرده‌اید فراخوانی کنید. باید شکست بخورد؛ اگر موفق شد، اعتبارنامه بیش از حد گسترده است.

اشکال‌زدایی در محیط محلی#

bash

php artisan mcp:inspector

بازرس ابزارها را فهرست می‌کند و اجازه می‌دهد آن‌ها را با آرگومان‌های نوع‌دار فراخوانی کنید. سریع‌ترین راه برای جدا کردن مشکل پیکربندی کلاینت از مشکل سرور همین است.

همچنین می‌توانید endpoint را با یک درخواست حداقلی JSON-RPC کاوش کنید:

bash

curl -s https://app.example.com/mcp/business \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

بهداشت توکن#

برای هر کلاینت یا دستگاه یک اعتبارنامه مستقل استفاده کنید.
توکن را در مخزن اسرار کلاینت نگه دارید، نه در پرامپت‌ها یا اسکرین‌شات‌ها.
هنگام بازنشسته شدن کلاینت، اعتبارنامه را لغو کنید.
پس از نشتی مشکوک، توکن را گردش دهید؛ توکن کهنه فوراً از کار می‌ایستد.
last_used_at را مرور کنید تا مطمئن شوید همان کلاینت از اعتبارنامه استفاده می‌کند.