在 Gemini 系列應用程式開發人員模式中測試、偵錯及評估

在 Google Connected Console 提交連結的應用程式送審前，請使用 Gemini 系列應用程式開發人員模式，以互動方式測試 Model Context Protocol (MCP) 伺服器、診斷結構定義或執行階段錯誤，以及評估工具品質。

本指南涵蓋下列工作：

  • 在 Gemini 啟用 Gemini 系列應用程式開發人員模式、建立自訂 MCP 應用程式，並驗證初始工具探索。
  • 偵錯失敗的工具呼叫、同步更新的結構定義，以及測試驗證。
  • 模擬使用者環境背景資訊，並設定用戶端驗證。

如需工作區版面配置和檢查器分頁的簡介，請參閱「Gemini 系列應用程式開發人員模式總覽」。

啟用 Gemini 系列應用程式開發人員模式

如果您是在 Google Connected Console 註冊 MCP 伺服器，啟用 Gemini 系列應用程式開發人員模式時，系統會自動提供已註冊的應用程式，您可以略過步驟 2。如要先在 Gemini 直接測試已部署的 HTTPS MCP 伺服器端點，再前往控制台註冊，請按照下列兩個步驟啟用 Gemini 系列應用程式開發人員模式，並將伺服器連結為自訂 MCP 應用程式。

步驟 1：啟用 Gemini 系列應用程式開發人員模式

  1. 在網路瀏覽器中開啟 Gemini。
  2. 依序點按「設定」>「Gemini 系列應用程式開發人員模式」(或直接前往 gemini.google.com/devmode)。

(選用) 步驟 2：建立及測試自訂 MCP 應用程式

如要在 Gemini 系列應用程式開發人員模式中，將 MCP 伺服器連結為自訂應用程式，請按照下列步驟操作：

  1. 在「Choose an app」對話方塊中，點選「+ Create new」。
  2. 在「Connect to an MCP server」(連線至 MCP 伺服器) 對話方塊中，於「MCP Server URL」(MCP 伺服器網址) 輸入伺服器的公開 HTTPS 端點 (網址開頭必須是 https://，例如 https://your-app-link.com/mcp)。
  3. 如果伺服器需要預先註冊的 OAuth 憑證，請依序點選「Additional settings」(其他設定) >「Show more」(顯示更多)，輸入 OAuth「Client ID」(用戶端 ID) 和「Client secret」(用戶端密鑰)，然後點選「Next」(下一步)。
  4. 在安全性與隱私權確認對話方塊中，查看 Gemini 如何與自訂 MCP 伺服器互動：
    • 執行工具：Gemini 會執行 MCP 伺服器的工具，觸發及執行可用函式來處理您的要求。
    • 資料擷取與分享：Gemini 會擷取及管理 MCP 伺服器端點公開的資源、結構定義和脈絡，並可能根據您的 Google 帳戶設定，或在與其他連結的應用程式互動時，分享其存取的資訊。
    • 信任與中斷連線：請確認您信任 MCP 伺服器，並詳閱其隱私權政策，再繼續操作。您隨時可以前往「連結的應用程式」頁面取消連結伺服器，或從 Google 帳戶連結中刪除連結。
  5. 選取「我瞭解並接受連結這個自訂應用程式的安全性和隱私權風險」，然後點按「連結」。
  6. 在「Save your custom app」(儲存自訂應用程式) 對話方塊中，輸入自訂應用程式的顯示名稱，確認伺服器的工具顯示在「Available actions」(可用動作) 清單中，然後按一下「Connect」(連結)。
  7. 在 Gemini 系列應用程式開發人員模式側邊面板中，選取「Tool schemas」(工具結構定義) 分頁標籤，查看連結應用程式中各項工具的資訊，包括參數定義、安全徽章 (「Read-only」(唯讀)、「Destructive」(破壞性)、「Auth-required」(需要驗證))、「Raw schema」(原始結構定義) 和「Response structure」(回覆結構)。
  8. 在左側對話窗格中，輸入自然語言或 @mention 提示 (例如 @MyApp show my profile)，並監控「Event Log」(事件記錄) 分頁，查看工具的運作情形。

偵錯工具呼叫

如果工具呼叫失敗或產生非預期的引數，您可以檢查診斷遙測資料、更新後端 MCP 伺服器，並熱重載結構定義，不必清除對話記錄。

如要對失敗的工具呼叫進行偵錯，請按照下列步驟操作：

  1. 選取右側窗格中的「事件記錄」分頁標籤。
  2. 在「Telemetry」(遙測) 清單中，點選失敗的事件展開詳細資料，並檢查 Tool call 要求酬載和 Tool result 回應：
    • 連線和網路錯誤：檢查錯誤訊息和延遲時間，確認端點可連線。
    • 驗證錯誤：如果事件傳回 401 或 403，請在「Authentication」(驗證) 分頁中，驗證 OAuth 權杖狀態或用戶端憑證。
    • 結構定義驗證不符：如果伺服器傳回 MCP 無效參數錯誤 (-32602)，請將 Tool call 中模型生成的 JSON 引數，與「Tool Schemas」(工具結構定義) 分頁中的參數類型、必要屬性和格式操作說明進行比較。
    • 伺服器執行階段例外狀況：檢查 Tool result 中的 JSON-RPC 錯誤代碼和訊息，診斷後端例外狀況。
  3. 如要解決問題，請更新 MCP 伺服器實作方式，或調整工具和參數說明。如需編寫清楚工具結構定義和錯誤回應的指引，請參閱「MCP 連結應用程式整合標準」。
  4. 在「工具結構定義」分頁中，按一下「同步結構定義」。Gemini 會從 MCP 伺服器重新擷取 tools/list，並更新有效的工具定義，同時保留目前的對話。
  5. 請重試查詢。在「Event Log」(事件記錄) 分頁中，確認重播的工具呼叫傳回 200 OK，並在對話預覽中顯示預期回覆。

模擬環境背景資訊和驗證

您可以直接在檢查器窗格中，測試 MCP 工具如何回應不同的使用者位置、時區、語言代碼和驗證方式。

覆寫環境背景資訊

如要模擬使用者情境，測試對日期、時間或語言代碼敏感的工具，請按照下列步驟操作：

  1. 選取右側窗格中的「環境」分頁標籤。
  2. 在「Date and Time」(日期和時間) 下方，選取「Simulated Date」(模擬日期) 和「Simulated Time」(模擬時間)，測試相對時間運算式 (例如「明天早上」或「本週六下午」)。
  3. 在「Preferences」下方，選取「Language」來模擬使用者語言代碼 (例如 en-US)。
  4. 在對話窗格中執行測試提示，使用模擬情境評估工具。
  5. 如要還原預設環境設定，請按一下「Reset」(重設)。

設定用戶端驗證

如要設定或切換 Gemini 系列應用程式開發人員模式工作階段使用的驗證方式，請按照下列步驟操作：

  1. 選取右側窗格中的「驗證」分頁標籤。
  2. 在「Client Authentication Configuration」(用戶端驗證設定) 下方，選取下列其中一種驗證模式：
    • Dynamic Client Registration：使用 OAuth 流程，自動與授權伺服器協商憑證。詳情請參閱 OAuth 2.1 導入指南。在「新增自訂應用程式連結」中輸入端點 (如適用)。
    • 手動註冊用戶端：可手動提供預先註冊的用戶端 ID 和用戶端密鑰。展開「Advanced Settings」(進階設定)，設定其他流程覆寫。
  3. 按一下「儲存」，然後等待「已儲存」訊息顯示。接著，執行測試提示，確認已驗證的工具成功。

其他資源