عیب‌یابی MCP#

بیشتر شکست‌های MCP مشکل پیکربندی‌اند، نه ایراد سرور. از بیرون به درون پیش بروید: نخست endpoint را تأیید کنید، سپس توکن، بعد صلاحیت و در آخر شعبه.

تشخیص سریع#

شکست‌های احراز هویت#

401 integrationcredentialrequired#

هیچ توکنی به سرور نرسیده، یا توکن یک توکن یکپارچه‌سازی نیست.

• تأیید کنید سرصفحه Authorization: Bearer <token> است، شامل واژه Bearer.
• تأیید کنید کلاینت هنگام پل زدن از stdout به HTTP سرصفحه‌ها را حذف نمی‌کند.
• تأیید کنید /mcp/business را فرا می‌خوانید، نه /api/v2 را.

401 integrationcredentialinvalid#

اعتبارنامه لغو شده، تجارت غیرفعال است، یا توکن به کاربری جز کاربر اعتبارنامه تعلق دارد.

• وضعیت اعتبارنامه را در تنظیمات بررسی کنید.
• فعال بودن اشتراک و وضعیت تجارت را تأیید کنید.
• در مورد تردید، اعتبارنامه را گردش دهید؛ گردش همیشه یک توکن معتبر تولید می‌کند.

403 integrationmembershipinactive#

کارمند اخراج شده یا عضویتش برداشته شده است. برای یک کارمند فعال اعتبارنامه بسازید؛ راهی برای زنده کردن اعتبارنامه کهنه وجود ندارد.

شکست‌های مجوزدهی#

403 apiabilitydenied#

اعتبارنامه آن صلاحیت را ندارد، یا نقش کارمند دیگر صفحه پشت آن را نمی‌دهد.

1. تنظیمات را باز کنید و تأیید کنید صلاحیت روی اعتبارنامه علامت خورده است.
2. صفحه دسترسی کارمند را باز کنید و تأیید کنید مجوز صفحه اعطا شده است.
3. کلاینت را دوباره بارگذاری کنید؛ ارزیابی برای هر درخواست انجام می‌شود، بنابراین یک تلاش تازه پس از رفع کافی است.

403 branchscopedenied#

شعبه درخواست‌شده در مجموعه اعطاشده اعتبارنامه نیست، یا به تجارت تعلق ندارد.

• branch_scope.allowed_branch_ids را از /api/v2/context بخوانید.
• یکی از آن idها را استفاده کنید، یا آرگومان شعبه را بردارید تا پیش‌فرض به کار رود.
• idهای دیگر را به امید موفقیت یکی دوباره امتحان نکنید؛ این کار به‌عنوان رد دامنه ثبت می‌شود.

422 branch_required#

اعتبارنامه به چند شعبه محدود است و فراخوانی هیچ‌کدام را نام نبرده بود. branch_id را در آرگومان‌های ابزار یا X-Business-Branch را در پیکربندی کلاینت بفرستید.

شکست‌های محدودیت نرخ#

429 apiburstlimit_exceeded#

بیش از 60 درخواست در یک دقیقه از یک اعتبارنامه. منتظر Retry-After بمانید و سپس نرخ درخواست را کم کنید. یک دستیار که روی فراخوانی ابزار حلقه بزند به سرعت به این حد می‌رسد.

429 apiquotaexceeded#

مقدار اجازه روزانه یا ماهانه تمام شده است. scope، period، limit، used و reset_at را از بدنه بخوانید. گزینه‌ها:

• منتظر زمان بازنشانی بمانید.
• فراوانی پرس‌وجویی یا اندازه صفحه را کم کنید.
• درباره پلان بالاتر از مدیر بپرسید.
• اگر جداسازی سهمیه مهم است، یکپارچه‌سازی‌ها را میان صاحبان تقسیم کنید.

مشکلات انتقال#

نتیجه‌های ابزاری که غلط به نظر می‌رسند#

• فهرست خالی: شعبه در دوره درخواست‌شده داده ندارد، یا اعتبارنامه به شعبه دیگری دامنه شده است.
• Purchase not found: id بیرون از دامنه دید است، یا سند حذف شده است.
• مبلغ‌ها شبیه رشته‌اند: آن‌ها را اعشاری تجزیه کنید؛ برخی کلاینت‌ها اعداد JSON را رشته نمایش می‌دهند.
• نام محصولات به زبان نادرست: language_code بفرستید؛ پیش‌فرض از تنظیم زبان برنامه پیروی می‌کند.

تأیید سالم بودن سرور#

1. GET /api/v2/health نتیجه {"data":{"status":"ok"}} می‌دهد.
2. GET /api/v2/context با همان توکن، دامنه و سهمیه را می‌دهد.
3. tools/list پنج ابزار برمی‌گرداند.
4. یک فراخوانی products با per_page: 1 یک سطر برمی‌گرداند.

اگر گام 2 کار کرد و گام 4 شکست، مشکل در آرگومان‌های ابزار است نه در اتصال.

چه زمانی با پشتیبانی تماس بگیریم#

• endpoint context موفق باشد اما هر ابزار با 403 شکست بخورد، درحالی که مجوزها بررسی شده‌اند.
• ابزاری داده از شعبه‌ای بیرون از دامنه اعطاشده برگرداند.
• مصرف سهمیه بدون درخواست افزایش یابد.
• سرور برای یک ابزار به‌طور پیوسته 500 بدهد.

نام اعتبارنامه (هرگز خودِ توکن)، زمان، نام ابزار، آرگومان‌ها و کد خطای بازگردانده‌شده را شامل کنید.

صفحات مرتبط#

• سرور MCP
• احراز هویت MCP
• خطاها
• محدودیت‌های نرخ و سهمیه‌ها