عیب‌یابی ثبت‌نام

اگر هنگام ثبت یا پیکربندی برنامه متصل‌شده با مشکلی مواجه شدید، به جدول زیر که حاوی پیام‌های خطای رایج، دلایل، و مراحل عیب‌یابی است مراجعه کنید.

مشکل پیام خطا علت مراحل رفع مشکل / عیب‌یابی

خطای نامشخص «واکشی ابزارها»

«جزئیات سرور MCP واکشی نشد. لطفاً دوباره امتحان کنید.» (یا دکمه ابزارهای واکشی بدون پیام خطای خاصی ناموفق می‌شود).

«کنسول یکپارچه» به‌دلیل نشانی وب نامعتبر، سرور آفلاین، یا خطای شبکه نتوانست درخواست را به نقطه پایانی MCP شما تکمیل کند.

موارد زیر را تأیید کنید:

  • دوباره بررسی کنید که نشانی وب نقطه پایان MCP شما درست باشد و از https:// استفاده کند.
  • مطمئن شوید که سرور MCP شما درحال اجرا است.
  • تأیید کنید که سرور MCP شما ازطریق اینترنت عمومی قابل‌دسترسی است (Google نمی‌تواند به localhost یا نشانی‌های اینترانت خصوصی دسترسی پیدا کند).

سرور MCP دردسترس نیست

«سرور MCP دردسترس نیست»

بخش پشتی Google نتوانست با نقطه پایانی MCP شما اتصال برقرار کند.

دلایل و راه‌حل‌های رایج عبارت‌اند از:

  • محدودیت‌های دیوار آتش: مطمئن شوید که دیوار آتش یا WAF شما محدوده‌های IP برون‌مرزی Google را مسدود نمی‌کند.
  • قوانین درگاه میانای برنامه‌سازی کاربردی: درستی‌سنجی کنید که درگاه میانای برنامه‌سازی کاربردی شما درخواست‌های POST را می‌پذیرد و clientInfo Google را درطول دست‌دهی MCP initialize رد نمی‌کند.
  • عدم تطابق زیردامنه: اگر از زیردامنه اختصاصی (مانند gemini.mcp.company.com) استفاده می‌کنید، مطمئن شوید فراداده /.well-known/oauth-protected-resource آن با آن زیردامنه مطابقت داشته باشد و به دامنه پایه دیگری (mcp.company.com) اشاره نکند.

انتقال MCP پشتیبانی‌نشده (HTTP 405)

«سرور MCP درخواست را رد کرد (HTTP 405 Method Not Allowed). مطمئن شوید که نشانی وب به یک نقطه پایانی Streamable HTTP که درخواست‌های پست را می‌پذیرد هدایت می‌کند، نه یک نقطه پایانی SSE قدیمی.

نشانی وب نقطه پایانی به یک نقطه پایانی قدیمی HTTP+SSE اشاره می‌کند که فقط درخواست‌های GET را می‌پذیرد یا درخواست‌های JSON-RPC POST را رد می‌کند.

سرور MCP و نشانی وب نقطه پایانی خود را به‌روز کنید تا از MCP Streamable HTTP transport استفاده کنید که درخواست‌های POST را برای initialize و tools/list می‌پذیرد.

فایل «منبع محافظت‌شده OAuth» وجود ندارد

«فایل /.well-known/oauth-protected-resource در سرور MCP وجود ندارد»

Google برای اکتشاف «فراداده منبع محافظت‌شده» OAuth 2.0‏ (RFC 9728) تلاش کرد، اما ناموفق بود.
  • اگر سرور MCP شما به اصالت‌سنجی نیاز ندارد: این خطا معمولاً زمانی رخ می‌دهد که نشانی وب نقطه پایانی MCP دارای غلط املایی یا بخش مسیر گم‌شده باشد (برای مثال، https://mcp.example.com به‌جای https://mcp.example.com/mcp) و HTTP 404 یا 500 را برمی‌گرداند، که باعث می‌شود کارخواه به اکتشاف OAuth برگردد. مطمئن شوید که مسیر دقیق نقطه پایان MCP شما HTTP 200 OK را به درخواست‌های POST initialize و tools/list اصالت‌سنجی‌نشده برمی‌گرداند، و نه را در بخش آیا سرور شما به مجوز نیاز دارد؟ در اعتبارنامه دسترسی انتخاب کنید.
  • اگر سرور MCP شما به اصالت‌سنجی نیاز دارد: یک فایل JSON معتبر /.well-known/oauth-protected-resource را در سرور MCP خود میزبانی کنید که سرورهای مجوزدهی مورداعتماد شما را در آرایه authorization_servers تبلیغ می‌کند.

فراداده OAuth Authorization Server (سرور مجوز OAuth) وجود ندارد یا نامعتبر است

«فایل /.well-known/oauth-authorization-server در سرور OAuth وجود ندارد» یا «حاوی JSON نامعتبر یا ناقص است»

سرور OAuth شما سند فراداده RFC 8414 معتبری را در /.well-known/oauth-authorization-server ارائه نمی‌دهد.
  • میزبانی سند اکتشاف RFC 8414 معتبر در /.well-known/oauth-authorization-server (یا /.well-known/openid-configuration) حاوی authorization_endpoint و token_endpoint.
  • یا در بخش اطلاعات کاربری، نشانی‌های وب نقطه پایانی مجوز سفارشی و نقطه پایانی کد سفارشی را به‌صورت دستی وارد کنید.

درستی‌سنجی دامنه ناموفق است

گواهی دامنه «درستی‌سنجی نشد» یا «درستی‌سنجی ناموفق بود» را با پیام نکته‌ابزار (مثل HTTP 404، تغییر مسیر غیرمجاز، یا عدم تطابق کد) نشان می‌دهد.

Google نتوانست کد چالش شما را در https://<domain>/.well-known/google-connected-apps تأیید کند.
  • فایل پیدا نشد (HTTP 404): مطمئن شوید محتوای google-connected-apps.json بارگیری‌شده در https://<domain>/.well-known/google-connected-apps (بدون افزونه .json در مسیر نشانی وب) منتشر شده باشد.
  • هدایت‌ها مجاز نیست: بار داده درستی‌سنجی را مستقیماً با HTTP 200 OK ارائه دهید؛ /.well-known/google-connected-apps را به نشانی وب دیگری هدایت نکنید.
  • عدم تطابق کد: مطمئن شوید که پاسخ JSON حاوی "verification_tokens": ["<YOUR_TOKEN>"] با کد دقیقی باشد که برای حساب توسعه‌دهنده شما تولید شده است.

ناموفق بودن Dynamic Client Registration (DCR) یا CIMD

«ثبت کارخواه پویا (RFC 7591) ناموفق بود»، «سرور OAuth از ثبت کارخواه پویا (RFC 7591) پشتیبانی نمی‌کند»، یا «ثبت سند فراداده شناسه کارخواه (CIMD) ناموفق بود»

ثبت خودکار کارخواه OAuth ناموفق بود یا ارائه‌دهنده OAuth شما از آن پشتیبانی نمی‌کند، یا URIهای هدایت Google رد شدند.
  • مطمئن شوید سرور OAuth شما هر شش «شناسه URI هدایت Google» مختص برنامه را که در بخش اعتبارنامه‌های احراز هویت سرور (https://oauth-redirect.googleusercontent.com/r/<app-id>-<sanitized-domain> و غیره) نشان داده شده است در فهرست مجاز قرار دهد. توجه داشته باشید که بسیاری‌از سرورهای OAuth 2.1 شناسه‌های URI هدایت با نویسه عام (*) را رد می‌کنند.
  • اگر ارائه‌دهنده OAuth شما از CIMD یا RFC 7591 DCR پشتیبانی نمی‌کند، پیش‌ثبت‌نام‌شده (برای OAuth واگذارشده به کاربر) یا ماشین‌به‌ماشین (اعتبارنامه‌های کارخواه OAuth) را در اعتبارنامه‌های دسترسی انتخاب کنید و شناسه کارخواه و رمز کارخواه ثابتی ارائه دهید.

بالاپر ورود به سیستم OAuth مسدود شده یا خالی است

«بالاپر اصالت‌سنجی توسط مرورگرتان مسدود شد» یا پنجره ورود به سیستم OAuth درطول همگام‌سازی یا آزمایش ابزار به‌درستی نمایش داده نمی‌شود.

مسدودکننده‌های بالاپر مرورگر یا سرصفحه‌های سخت‌گیرانه X-Frame-Options / Content-Security-Policy در صفحه ورود به سیستم شما مانع از جریان بالاپر شده است.
  • به بالاپرها برای کنسول در مرورگرتان اجازه فعالیت دهید و دوباره امتحان کنید.
  • در اعتبارنامه‌های دسترسی در بخش اصالت‌سنجی با اعتبارنامه‌های توسعه‌دهنده، از اصالت‌سنجی ازطریق بالاپر به اصالت‌سنجی ازطریق «هدایت» (جایگزین) بروید تا جریان اصالت‌سنجی به‌صورت تمام‌صفحه در همان زبانه باز شود.

دستورالعمل‌های سرور MCP وجود ندارد

پیام هشدار: «سرور MCP شما دستورالعملی ندارد. توصیه می‌کنیم دستورالعمل به طرح‌واره سرورتان اضافه کنید.»

سرور MCP شما فیلد instructions را در پاسخ initialize خود برنگرداند.
  • هنگام مقداردهی اولیه سرور MCP، دستورالعمل‌های سیستم را به‌طور صریح تعریف کنید (پارامتر instructions در تعریف سرور).
  • برای پیاده‌سازی‌های HTTP بدون حالت یا سفارشی، مطمئن شوید که فیلد instructions در بار JSON-RPC برای روش initialize گنجانده شده باشد، سپس ابزارهای همگام‌سازی مجدد را انتخاب کنید.

حد مجاز اندازه منبع واسط کاربر یا نوع MIME پشتیبانی‌نشده

کارت خطای مشکلات مربوط به واکشی: «حجم تجمعی منبع نمی‌تواند از ۱۰۰ مگابایت بیشتر باشد.» یا «نوع MIME‏ «<type>» برای منبع «<uri>» پشتیبانی نمی‌شود.»

سرور MCP شما منابع میانای کاربری را برگرداند که اندازه کل آن‌ها از حد مجاز فراتر رفته است یا از نوع MIME پشتیبانی‌نشده استفاده می‌کنند.
  • اندازه تجمعی همه منابع میانای کاربر مانیفست را که سرورتان برمی‌گرداند کاهش دهید تا از حد مجاز فراتر نرود.
  • مطمئن شوید همه منابع واسط کاربر از یکی از انواع MIME پشتیبانی‌شده استفاده می‌کنند: text/html، text/html;profile=mcp-app، text/javascript، یا text/css.

بارگذاری نماد گیر کرده است یا «خطای غیرمنتظره» رخ داده است

هنگام بارگذاری نماد برنامه در جزئیات برنامه، بارگذاری روی نشانگر بارگیری ثابت می‌ماند یا «خطای غیرمنتظره‌ای روی داده است. لطفاً دوباره امتحان کنید» (اغلب با کد 4E696748).

معمولاً به‌دلیل جلسه مرورگر قدیمی، افزونه‌های مرورگر متناقض، یا حالت اصالت‌سنجی ذخیره‌شده در حافظه پنهان ایجاد می‌شود.

مراحل زیر را به‌ترتیب امتحان کنید:

  1. از نمایه مرورگر جدید استفاده کنید: پنجره جدیدی را بااستفاده از نمایه مرورگر تمیز باز کنید.
  2. از حالت ناشناس / خصوصی استفاده کنید: در پنجره مرور خصوصی به سیستم «کنسول یکپارچه Google» وارد شوید و نماد را بارگذاری کنید.
  3. پاک کردن حافظه نهان: قبل‌از امتحان مجدد، حافظه نهان و کوکی‌های مرورگرتان را پاک کنید و مطمئن شوید نمادتان PNG یا JPEG معتبر ۵۱۲ پیکسل × ۵۱۲ پیکسل و کمتر از ۱ مگابایت باشد.