Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

MCP 連結的應用程式整合標準

MCP 伺服器會建立架構，將應用程式函式 (MCP 工具) 連結至連結的應用程式平台。為確保模型能更可靠地選取、呼叫及處理服務結果，MCP 設定必須嚴格遵守下列標準。

指導原則

請著重於每項函式的使用者意圖和用途，而非函式的功能。說明是向模型介紹工具用途和適用情境的主要方式。

版本管理

為支援可擴充且穩健的 MCP 部署作業，請採用結構化 URI 架構，並使用路徑式版本管理，例如 /v1、/v2。這樣做有助於維持回溯相容性，並控管新功能。此外，您也可以搭配使用供應商專屬子網域 (例如 https://gemini.mcp.company.com/mcp/v1)，精細管理流量，並根據不同 AI 模型的獨特情境和處理行為，最佳化工具定義。

MCP 通訊協定版本相容性

連結的應用程式平台支援 Model Context Protocol (MCP) 規格，最高可達版本 2025-11-25。目前不支援較新的規格版本。

開發人員責任：您有責任確保 MCP 伺服器在 initialize 握手期間，以及所有工具和結構定義定義中，嚴格遵守 Connected Apps Platform (2025-11-25) 支援的通訊協定版本。
平台回溯相容性：隨著連結的應用程式平台日後採用較新的 MCP 規格版本，我們的用戶端會與先前支援的通訊協定版本保持回溯相容性，確保現有的正式版整合功能持續運作，不會中斷。
管理升級：當您準備好採用新支援的 MCP 規格或導入結構定義變更時，請在新的版本化 URI 路徑 (例如 /mcp/v2) 上公開這些更新，同時保留現有的端點 (/mcp/v1) 處理有效流量。

應用程式版本之間可以變更 MCP 結構定義。建議您善用這項功能，並為 MCP 端點建立版本，以便逐步推出新功能，或嚴格依賴回溯相容的變更。

傳輸通訊協定規格

連結的應用程式平台嚴格支援 Streamable HTTP 傳輸 Model Context Protocol 規格 2025-03-26 以上版本。不支援 2024-11-05 規格所述的舊版 HTTP 與 SSE 傳輸。

單一 HTTP 端點。在 Google Connected Console 中提供的 MCP 端點 (例如 https://api.example.com/mcp) 是單一網址，適用的 Google 產品會透過標準 HTTP POST 傳送所有 JSON-RPC 要求 (initialize、tools/list、tools/call)。
在可串流 HTTP 中進行 SSE 串流。不支援舊版多端點 SSE 傳輸，但 Streamable HTTP 支援 text/event-stream 等伺服器傳送事件。適用 Google 產品的傳出要求包含 Accept: application/json, text/event-stream，代表伺服器可傳回標準 application/json 酬載，或直接在 HTTP POST 回應主體中使用 Content-Type: text/event-stream 串流傳送增量回應。
GET 串流和 405 Method Not Allowed。用戶端可以嘗試在端點上使用選用的 GET 串流，接收伺服器對用戶端的通知。如果伺服器無狀態或僅限要求/回應，Google 適用產品的用戶端 Proxy 會明確支援並妥善處理傳回的 HTTP 405 Method Not Allowed。

伺服器指令

連結的應用程式平台經過最佳化，可擷取伺服器指令，讓您能以其他方式無法達到的程度，控管模型行為。

按照伺服器操作說明操作。

視為「模型提示」，並提供使用情境

請遵循下列規範，提供提示給模型。

請將指令寫成高階「提示」或指南，協助 LLM 瞭解伺服器的整體用途和功能。
請說明伺服器的功能，而非列出功能或說明模型應如何使用伺服器的工具和資源。如果模型正確理解「內容」，就能根據使用者歷程，判斷出相當準確的「方式」。
假設這段文字會直接新增至模型的系統提示。請保持清晰、具指導性，並有效率地使用權杖。

互補而非重複

這個空間用於提供適用於所有工具的全域背景資訊，避免與個別工具說明重複。

伺服器操作說明範例

以下範例說明如何正確編寫伺服器指令。

建議不建議使用

建議	不建議使用
假設你是專業的 GitHub 存放區維護人員。這個伺服器可深入存取存放區中繼資料、Issue Tracker 和 PR 工作流程。這項工具可協助您維護專案健康狀態、自動分類問題，以及確保程式碼符合標準。除非另有說明，否則請假設所有動作都是在已驗證組織的環境中執行。優先找出過時的討論串或未連結的 PR，保持存放區井然有序。簡潔、具指導性，且能與模型相輔相成定義「內容」(專案健康狀態、分類)，而非「方式」提及適用於所有工具的驗證範圍	這個伺服器提供 GitHub 工具，當使用者詢問問題時，請使用 `list_issues` 工具。您可以使用 `create_pull_request` 建立 PR。請謹慎使用這些工具，協助使用者管理程式碼。呼叫工具前，請務必檢查存放區名稱。如果使用者要求摘要，請先呼叫工具，然後再摘要輸出內容不要重複列出工具名稱，不要告訴模型「如何」思考，這可能會與模型內建的推論功能衝突，模型會使用使用者情境做出正確選擇。未說明伺服器存取權的性質或特定限制)

假設你是專業的 GitHub 存放區維護人員。這個伺服器可深入存取存放區中繼資料、Issue Tracker 和 PR 工作流程。這項工具可協助您維護專案健康狀態、自動分類問題，以及確保程式碼符合標準。除非另有說明，否則請假設所有動作都是在已驗證組織的環境中執行。優先找出過時的討論串或未連結的 PR，保持存放區井然有序。

簡潔、具指導性，且能與模型相輔相成

定義「內容」(專案健康狀態、分類)，而非「方式」
提及適用於所有工具的驗證範圍

這個伺服器提供 GitHub 工具，當使用者詢問問題時，請使用 list_issues 工具。您可以使用 create_pull_request 建立 PR。請謹慎使用這些工具，協助使用者管理程式碼。呼叫工具前，請務必檢查存放區名稱。如果使用者要求摘要，請先呼叫工具，然後再摘要輸出內容

不要重複列出工具名稱，
不要告訴模型「如何」思考，這可能會與模型內建的推論功能衝突，模型會使用使用者情境做出正確選擇。
未說明伺服器存取權的性質或特定限制)

工具指南

下列指南說明最佳做法，協助您為應用程式中的各種函式或工具建立 MCP 伺服器設定。

工具命名慣例

命名工具時，請遵守下列規範：

使用直覺、人類可讀的名稱

請使用人類可讀的名稱，並確保名稱意義明確、直觀，而非模稜兩可。舉例來說，get_user_information 比 userInfo 更直觀。

請注意大小寫樣式

工具函式名稱和應用程式觸發條件必須遵守下列大小寫規則：

工具函式大小寫。請使用 snake_case 或 camelCase，代表 MCP 結構定義中定義的工具函式名稱 (例如 get_user_information 或 publishDraft)。
應用程式觸發條件控制代碼大小寫。應用程式觸發條件和提及 (例如 @MyTwoWordApp) 不區分大小寫。平台會將使用者輸入內容正規化，包括小寫 (@mytwowordapp)、PascalCase (@MyTwoWordApp) 和 camelCase (@myTwoWordApp)。
顯示名稱格式。使用 PascalCase 或標準空格註冊官方應用程式名稱，在 UI 元素中清楚顯示。
拼寫錯誤處理。雖然系統會自動處理大小寫變化，但字元拼寫錯誤 (例如 @mytwowrodapp) 則仰賴備用意圖辨識，而非直接字串比對。開發人員應鼓勵在說明文件中正確拼寫帳號代碼。

使用明確的動詞 + 名詞命名

使用具體的 verb_noun 命名，避免語意模糊不清，例如 publish_draft 優於 handle_content。

工具精細程度

請遵守下列工具精細程度規範。

將工具視為不可分割的端點

將工具視為原子端點，不含內部工具條件或多個功能，且各自有必要參數。精細的工具可讓模型以邏輯方式串連步驟，減少幻覺。

使用較扁平的結構定義

如果需要深度巢狀物件或複雜的 oneOf/anyOf 結構定義邏輯來驗證輸入內容，表示工具可能過於廣泛。

遵守預先匯總和酬載防護機制

雖然對於小型、限定範圍的酬載，通訊協定並未嚴格強制要求預先匯總資料，但在處理大型記錄集、縱向記錄和多來源資料集時，實務上強烈建議在後端預先匯總。連結的應用程式平台會強制執行防護措施，限制脈絡窗口、執行延遲時間和模型推論步驟。為遵守這些護欄，請遵循下列規範：

在後端篩選及匯總資料。將回應傳回適用的 Google 產品前，請務必先在 MCP 伺服器上篩選、預先匯總或彙整大型資料串流。
避免原始傾印。請勿將原始資料庫資料列或完整的未索引記錄，傾印到工具傳回的酬載中。

省略內部和中繼工具

在伺服器的 tools/list 回應中，只公開模型專用功能：

篩除輔助工具：省略任何不應由模型呼叫的內部、管理或中繼工具，例如伺服器健康狀態檢查、內部設定常式或開發人員公用程式輔助工具。
脈絡窗口效率：排除不必要的工具，可保持 MCP 結構定義簡潔、減少脈絡窗口詞元消耗，並防止模型工具轉送混淆。如果 MCP 伺服器公開數十種工具，或採用深度巢狀結構的「大型工具」結構定義，就會在審查期間遭到標記，需要修正。

工具精細程度的注意事項

以下範例說明工具命名和精細程度的注意事項。

建議不建議使用

建議	不建議使用
精細工具，名稱和參數明確每項工具的輸入結構定義都十分嚴格。如果 LLM 要建立使用者，就必須提供電子郵件地址。如要刪除，則必須提供 ID。不必再胡亂猜測。 `... @mcp.tool() def create_user(email: str, role: str = "viewer") -> str: """Register a new user. Returns the new User ID.""" # Logic is purely creation return "user_123" @mcp.tool() def delete_user(user_id: str) -> str: """Permanently remove a user by their ID.""" # Logic is purely deletion return f"User {user_id} deleted" @mcp.tool() def update_user_role(user_id: str, new_role: str) -> str: """Change an existing user's permission level.""" return f"User {user_id} is now {new_role}" ...`	工具名稱：manage_user Description: "Use this tool to create, update, delete, or retrieve users." ... @mcp.tool() def manage_user( action: Literal["create", "update", "delete", "get"], user_id: Optional[str] = None, email: Optional[str] = None, role: Optional[str] = "viewer" ) -> str: """ Use this to manage users. WARNING: logic is hidden inside Python, not visible in the schema. """ if action == "create": if not email: return "Error: Email required for creation" # Runtime error, not schema error return f"Created user {email}" elif action == "delete": if not user_id: return "Error: User ID required" return f"Deleted {user_id}" return "Action completed" """ ...

精細工具，名稱和參數明確

每項工具的輸入結構定義都十分嚴格。如果 LLM 要建立使用者，就必須提供電子郵件地址。如要刪除，則必須提供 ID。不必再胡亂猜測。

...
@mcp.tool()
def create_user(email: str, role: str = "viewer") -> str:
    """Register a new user. Returns the new User ID."""
    # Logic is purely creation
    return "user_123"

@mcp.tool()
def delete_user(user_id: str) -> str:
    """Permanently remove a user by their ID."""
    # Logic is purely deletion
    return f"User {user_id} deleted"

@mcp.tool()
def update_user_role(user_id: str, new_role: str) -> str:
    """Change an existing user's permission level."""
    return f"User {user_id} is now {new_role}"

    ...

工具名稱：manage_user

Description: "Use this tool to create, update, delete, or retrieve users."

...
@mcp.tool()
def manage_user(
    action: Literal["create", "update", "delete", "get"],
    user_id: Optional[str] = None,
    email: Optional[str] = None,
    role: Optional[str] = "viewer"
) -> str:
    """
    Use this to manage users.
    WARNING: logic is hidden inside Python, not visible in the schema.
    """
    if action == "create":
        if not email: return "Error: Email required for creation" # Runtime error, not schema error
        return f"Created user {email}"
    elif action == "delete":
        if not user_id: return "Error: User ID required"
        return f"Deleted {user_id}"
    
    return "Action completed"
    """
    ...

宣告工具註解以確保安全

在工具定義中設定通訊協定註解，傳達執行行為，並在適用的 Google 產品中觸發內建安全閘道：

執行階段確認閘道：適用的 Google 產品會使用 annotations.destructiveHint: true 和 annotations.openWorldHint: true 做為重要旗標，觸發執行階段使用者確認提示。在狀態變更、寫入或破壞性動作上宣告 destructiveHint: true，並為與開放世界或外部環境互動的工具設定 openWorldHint: true，讓介面在執行前，原生提示使用者確認。
唯讀查詢提示：在僅擷取資料而不修改後端狀態的查詢工具上設定 readOnlyHint: true。
明確註解預設值：根據 Model Context Protocol 規格，省略 readOnlyHint 會導致用戶端預設採用 readOnlyHint: false 和 destructiveHint: true，以確保安全。明確宣告所有工具的註解，可確保模型路由可預測，並確保執行安全。

工具說明

模型只能根據說明，判斷工具能否解決當前問題。撰寫說明時，請遵守下列規範：

撰寫指令，而非註解

請以指令形式撰寫工具說明，而非程式碼註解，因為註解通常是被動的。LLM 對指令的反應良好。

說明「如何」

好的說明能讓模型從「我有工具」進展到「我知道如何將這項工具融入對話」。

說明原因

區分這項工具與類似工具，例如「內部使用者請用這項工具，外部使用者請用 customer_update」。

提供連結

告訴模型引數的來源，例如「來自 order_search 工具」。

指定格式

指定單位 (公尺或英尺) 和格式 (ISO 日期、語意版本)。

避免模型自行判斷

請勿指示模型使用「最佳判斷」，或建議選用、未經引導的動作。

工具說明範例

以下範例說明撰寫工具說明時的注意事項。

建議不建議使用

建議	不建議使用
可靠資料來源「更新使用者的電子郵件地址。必須嚴格使用 `search_users` 工具傳回的 UUID「id」。請勿推論或猜測使用者 ID。 (明確將一項工具的輸出內容連結至這項工具的輸入內容。)	「更新使用者的電子郵件地址。」 (模型可能會猜測 ID，例如 12345)。
格式和限制「安排會議。「date」必須採用 ISO 8601 格式 (YYYY-MM-DD)。如果使用者說「明天」或其他相對時間，請根據目前情境計算日期。」	「安排指定日期的會議。」 (人類看起來正確 (例如「明天」)，但結構定義驗證失敗 (需要「2025-10-12」))
預期輸出內容「擷取伺服器記錄。傳回原始文字的最後 50 行。如要分析，請要求較短的時間範圍，以免超出權杖限制。」	「取得伺服器記錄。」 (模型可能會呼叫工具來取得摘要，但卻收到 5 MB 的原始 JSON 傾印，導致使用者體驗不佳)。
`@mcp.tool() def update_campaign_status(campaign_id: str, status: str) -> str: """ Promotes or pauses an advertising campaign. CRITICAL USAGE RULES: 1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'. 2. 'status': Must be exactly one of: ['active', 'paused', 'archived']. Returns: A confirmation string with the new status and timestamp. """ # Logic... ...` 這段說明就像是迷你手冊，它會處理來源 (取得 ID 的位置)、限制 (有效的列舉) 和動作。	`@mcp.tool() def update_campaign_status(id: str, status: str) -> str: """ Updates the campaign status in the database. """ # Logic...` 這會依賴變數名稱來完成所有工作。模型會猜測「status」的有效值

可靠資料來源

「更新使用者的電子郵件地址。必須嚴格使用 search_users 工具傳回的 UUID「id」。請勿推論或猜測使用者 ID。

(明確將一項工具的輸出內容連結至這項工具的輸入內容。)

「更新使用者的電子郵件地址。」

(模型可能會猜測 ID，例如 12345)。

格式和限制

「安排會議。「date」必須採用 ISO 8601 格式 (YYYY-MM-DD)。如果使用者說「明天」或其他相對時間，請根據目前情境計算日期。」

「安排指定日期的會議。」

(人類看起來正確 (例如「明天」)，但結構定義驗證失敗 (需要「2025-10-12」))

預期輸出內容

「擷取伺服器記錄。傳回原始文字的最後 50 行。如要分析，請要求較短的時間範圍，以免超出權杖限制。」

「取得伺服器記錄。」

(模型可能會呼叫工具來取得摘要，但卻收到 5 MB 的原始 JSON 傾印，導致使用者體驗不佳)。

@mcp.tool()
def update_campaign_status(campaign_id: str, status: str) -> str:
    """
    Promotes or pauses an advertising campaign.
    
    CRITICAL USAGE RULES:
    1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'.
    2. 'status': Must be exactly one of: ['active', 'paused', 'archived'].
    
    Returns: A confirmation string with the new status and timestamp.
    """
    # Logic...

    ...

這段說明就像是迷你手冊，它會處理來源 (取得 ID 的位置)、限制 (有效的列舉) 和動作。

@mcp.tool()
def update_campaign_status(id: str, status: str) -> str:
    """
    Updates the campaign status in the database.
    """
    # Logic...

這會依賴變數名稱來完成所有工作。模型會猜測「status」的有效值

工具參數

除了工具本身，也請說明參數，確保清楚明確。

明確類型

使用強型別、特定類型 (string、integer、boolean、array)。

使用列舉處理固定值組合

如果參數只接受一組固定值 (例如 daylight、cool、warm)，請在 enum 陣列中列出這些值。這可大幅提升準確度。

清楚說明必要參數

清楚定義函式運作所需的必要參數。

套用語意結構定義比對

整合應用程式時，可能需要將工具參數的語意結構定義，與開發的類別進行比對。您會在新手上路程序中收到預期的垂直結構定義 (JSON 結構定義)。

工具參數範例

以下範例說明處理工具參數時的注意事項。

建議	不建議使用
引數格式和單位 radius：半徑 (以公尺為單位)。必須是大於 0 的浮點數。 (防止單位幻覺)	radius：「圓形的半徑。」
ID 格式和背景資訊 user_id：資料庫 UUID (例如 550e8400-e29b...)。請勿在此輸入電子郵件地址。」注意：最佳做法是將所有數值 ID 欄位視為字串值。特別是如果 ID 可能超過 10 位數，內部系統可能會截斷 ID (強制放入 32 位元容器)，而模型在日後的工具呼叫中會使用這個版本。 (避免類型錯誤)	user_id: "The ID of the user."
預期傳回值「更新記錄並傳回更新後的 JSON 物件，包括新的時間戳記。」 (告訴模型，在「update」後不需要立即呼叫「get」工具來驗證變更)。	「更新記錄。」
`@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """ Searches server error logs using Lucene syntax (e.g. 'level:ERROR AND service:auth'). Args: query: A Lucene-formatted search string. limit: Max results to return. capped at 50. Returns: A formatted string of log entries with timestamps. """ ...`	`@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """Searches the logs.""" ...` LLM 不知道「查詢」支援哪些語法 (SQL？規則運算式？純文字？) 它不知道「上限」是多少。

回應和錯誤處理

根據「回覆就是下一個提示」的核心原則，工具會傳回資料酬載，回報基礎執行的結果，然後直接貼到 LLM 的脈絡視窗中。結果成功或失敗會決定後續行動：

如果成功：模型需要傳回值，才能瞭解發生什麼事，並決定下一步。
如果失敗：模型需要知道失敗原因和修正方式。當機 (500 錯誤) 會中斷對話，而描述性錯誤訊息則可讓模型自行修正。

無論工具的基礎邏輯成功或失敗，都必須設定傳回值酬載的格式，讓模型能輕鬆剖析。封裝回應酬載時，請遵循下列最佳做法。

使用 JSON

在 TextContent 中設定結構化資料的格式 (暫時限制)。由於連結的應用程式平台尚不支援 structuredContent，請手動序列化資料。即使傳回簡單的清單，json.dumps() 也是如此。

在回覆中加入網址

傳回的網址應相對簡短，且不含多個參數。建議使用網址縮短程序服務，節省權杖數量並降低幻覺風險。

自述式防幻覺酬載

原始代碼或內部 ID 應一律搭配人類可讀的顯示名稱、明確的測量單位和參考範圍。請勿傳回壓縮的字典鍵或未對應的數字代碼，以免模型必須推論上下文。

導入完善的錯誤處理機制

傳回清楚、有意義的錯誤訊息，讓模型瞭解問題所在，並通知使用者。請參閱 MCP 錯誤處理。

使用 try/except

將工具邏輯包裝在 try/except 區塊中，並傳回字串化的錯誤。

提供可採取行動的錯誤

在錯誤訊息中建議下一步 (例如「請先嘗試使用工具 X」)。

確認動作

請勿針對有副作用的工具 (建立/更新/刪除) 傳回空字串。

回應和錯誤處理範例

以下範例說明回應和錯誤處理的注意事項。

建議	不建議使用
明確序列化 `... import json @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # GOOD: Returns '{"id": "cpu", "value": 42}' -> Valid JSON return json.dumps(result, indent=2)`	`... @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # BAD: Returns "{'id': 'cpu', 'value': 42}" -> Invalid JSON return str(result)`
攔截並通知 `... @mcp.tool() def get_user_details(user_id: str) -> str: try: user = db.get_user(user_id) if not user: # GOOD: Informative error returned as content return f"Error: User with ID '{user_id}' not found. Please verify the ID using 'search_users'." return json.dumps(user) except Exception as e: return f"Error: Database connection failed ({str(e)}). Please try again later."` (工具在技術上「成功」傳回字串，但字串包含錯誤詳細資料。模型讀取這項資訊後，會發現「這個 ID 不存在」，並要求使用者提供正確的 ID。	`... @mcp.tool() def get_user_details(user_id: str) -> str: # BAD: Unhandled exception if ID not found user = db.get_user(user_id) return json.dumps(user)` (如果 `get_user` 失敗，伺服器會擲回 500。LLM 收到一般執行錯誤，但不知道原因 (ID 錯誤？資料庫停止運作？權限遭拒？)。(很可能會重試完全相同的錯誤輸入)。
空白回覆 `... @mcp.tool() def post_story(story_content: str) -> str: service_name = "story_service" api_client.post("/stories", json={"content": story_content}) # GOOD: Explicit confirmation of state change. return f"Service '{service_name}' successfully posted content. Status is now 'posted'."`	`... @mcp.tool() def post_story(storyContent: str): subprocess.post(["postsrv", "story", storyContent]) # BAD: Returns null/empty string. Model is confused.` LLM 經常會因空白回覆而混淆。可能會產生幻覺，例如「工具失敗」，或只是重複呼叫。
自述式反幻覺酬載原始代碼或內部 ID 應一律搭配人類可讀的顯示名稱、明確的測量單位和正常參考範圍。 `{"lab_code": "2345-7", "display_name": "Glucose [Mass/volume] in Blood", "value": 105, "unit": "mg/dL", "reference_range": "70-99 mg/dL"}` (這可讓模型確切瞭解值的意義，不必推測單位或參考門檻)。	原始 ID、自訂壓縮或未對應的代碼傳回原始內部 ID、自訂字典縮寫或不含標籤的數字代碼。 `{"code": "2345-7", "v": 105}` (模型會被迫猜測 105 的含義，導致產生幻覺、遺漏背景資訊或解釋不準確)。

MCP 錯誤處理

因此，請務必妥善處理錯誤。

如果是可復原的錯誤 (例如使用者 ID 無效或缺少選用參數)，請在工具回覆中傳回一般文字字串，其中包含描述性錯誤詳細資料。這樣模型就能檢查意見回饋、瞭解問題所在，並自行修正或提示使用者提供更明確的資訊。
如果發生終端錯誤 (例如頻率限制、驗證或權限失敗，或後端伺服器中斷)，請引發 McpError 並附上適當的錯誤代碼，讓平台能系統性地處理失敗。

錯誤回應主體範例 (JSON)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32302,
    "message": "User permission denied for the requested operation.",
    "data": null
  },
  "id": 1
}

Message 包含 MCP ErrorData 欄位的 JSON 轉儲。只要傳回正確的 code 和模型可見的 message，連結的應用程式平台就能讀取錯誤訊息，並以自然語言向使用者提供實用的說明。例如：「抱歉，找不到這個 ID 的場地。請核對一下名稱。」

MCP 允許用戶端使用 JSON-RPC 2.0 規格連線至 MCP 伺服器。JSON-RPC 會針對常見錯誤 (例如無效要求、剖析錯誤等) 傳送預先定義的錯誤。本指南說明 MCP 伺服器如何傳回自訂錯誤。

狀態代碼	訊息	用量	需要明確傳回嗎？
使用者/客戶錯誤
-32300	USER_RATE_LIMITED	使用者已達用量限制。	是
-32301	MISSING_REQUIRED_INFORMATION	輸入要求缺少必要資訊	是
-32302	USER_PERMISSION_DENIED	使用者拒絕授予工具使用權限。例如，使用者必須擁有公司帳戶、符合年齡限制、位於特定語言代碼等，或未訂閱該工具的企業方案。	是
應用程式錯誤/商業邏輯錯誤
-32400	RUNTIME_ERROR	執行伺服器程式碼時發生錯誤	是
-32401	NULL_POINTER_EXCEPTION	嘗試執行空值指標/物件	是
-32402	OUT_OF_MEMORY	伺服器程式碼記憶體不足，無法分配給物件	是
基礎架構錯誤
-32500	DEADLINE_EXCEEDED	要求處理時間超過允許的時間。可能的原因有很多，例如伺服器超載、網路問題等。	是
-32501	RESOURCE_EXHAUSTED	伺服器的記憶體不足、磁碟空間、執行緒、CPU 作業時間等資源已用盡。	是
-32502	SERVICE_UNAVAILABLE	依附服務 (例如其他微服務、資料庫、快取等) 無法使用	是
JSON-RPC 錯誤 (這些錯誤屬於 MCP 傳輸)
-32700	PARSE_ERROR	伺服器無法剖析要求	否
-32600	INVALID_REQUEST	用戶端要求格式有誤	否
-32601	METHOD_NOT_FOUND	MCP 工具名稱無效	否
-32602	INVALID_PARAMS	要求參數無效，包括缺少參數或參數類型不符	否
-32603	INTERNAL_ERROR	預設回覆	否

以下範例說明如何使用官方 Python SDK (mcp)，在伺服器中引發 MCP 錯誤。引發包含 ErrorData 酬載的 McpError，SDK 會自動將其序列化為必要的 JSON-RPC 錯誤格式，並填入錯誤狀態。

from mcp import types
from mcp.shared.exceptions import McpError

@mcp.tool()
def foo_tool() -> list[types.TextContent]:
  """Always returns an error."""
  raise McpError(
    types.ErrorData(
        code=-32302, # USER_PERMISSION_DENIED
        message="Message to show to the model."
    ),
  )

工具背景資訊

適用的 Google 產品支援 Tool Context API，可將信號傳遞至 MCP 伺服器。這個 API 適用於需要機密資訊的有效用途，例如不屬於核心工具定義的中繼資料，像是需要本地化的工具語言代碼。Tool Context API 只能透過 Google Connected Console 存取。

在 Google Connected Console 中，為應用程式註冊 current_user_location_fine 等信號後，適用的 Google 產品會在 MCP tools/call 要求中，額外加入 _meta 項目，提供要求的資料。支援的信號組合如下：

current_user_location_fine (僅限 Gemini，適用於經許可的產業)
user_locale
current_user_location_coarse

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find-restaurant",
    "arguments": {"query": "restaurants near me"},
    "_meta": {
      "current_user_location_fine": {
        "latitude_degrees": 37.7749,
        "longitude_degrees": -122.4194,
        "accuracy_meters": 112.4221
      },
      "user_locale": {
        "language_code": "en",
        "region_code": "US"
      }
    }
  }
}

如要解壓縮這項資料，請按照下列步驟操作：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote_mcp")

@mcp.tool()
async def find_restaurants(query: str, ctx: Context) -> str:
   # Access context directly from _meta
   request_context = ctx.request_context
   meta_dict = ctx.request_context.meta.model_dump() if ctx.request_context.meta else {}

   location_context = meta_dict.get("current_user_location_fine", {})
   lat = location_context.get("latitude_degrees")
   lng = location_context.get("longitude_degrees")
   if lat and lng:
       return f"Finding '{query}' near ({lat}, {lng})"
   return f"Finding '{query}' (no location provided)"

使用者體驗算繪

MCP 應用程式

適用的 Google 產品支援 MCP 應用程式整合，可針對特定使用者歷程建構自訂使用者介面。請按照規格說明，瞭解一般整合操作說明。

在適用的 Google 產品上整合 MCP 應用程式時，請注意下列事項。

註冊時擷取資源

適用的 Google 產品會在工具擷取期間擷取 UI 資源，類似於工具清單和工具說明。這表示任何資源更新 (例如 JavaScript 變更) 都不會自動套用，必須重新擷取工具。

單一 UI 資源的大小不得超過 15 MB，伺服器上的 UI 資源累計大小不得超過 100 MB。

UI 資源必須使用下列其中一種支援的 MIME 類型：text/html、text/javascript、text/css 或 text/html;profile=mcp-app。推送至預先發布版時，非標準或平台專屬的 MIME 類型會無法通過驗證。

CSP 指南

適用的 Google 產品遵循官方 MCP 應用程式規範，包括 CSP [1]、[2]，並會封鎖任何違反 CSP 指令的要求。

適用的 Google 產品還需要將 blob: 和 data: 新增至 CSP (如有使用)。系統預設不會新增這些項目。開發人員可自行決定是否要將這些指令新增至 CSP。

Script-src 是例外狀況

我們只允許下列指令：unsafe-inline (預設新增)、wasm-unsafe-eval 和 data: (如果包含在 resource_domains 中)。如果 iframe 載入外部指令碼，可以將 JS 整合到 HTML 中，或使用子資源完整性 (SRI) 雜湊來解決。

方法 1：將 JS 內嵌/整合至 HTML (最簡單)
- Bundle JS Code:
  - 在為 UI 資源傳回的 HTML 酬載中，直接將 component-init.js 的內容內嵌在 <script> 標記內：
```
<script>
// Paste component-init.js content directly here
</script>
```
- 移除遠端 <script src> 標記
  - 從 HTML 文件中刪除 <script src="https://api.mycompany.com/..."> 參照。
- 重新攝入/更新工具
方法 2：使用子資源完整性 (SRI) 雜湊：

如果指令碼必須託管在外部 https://api.company.com/...，請使用這個選項。
- 計算指令碼的 SHA-256 雜湊
  - 產生 component-init.js 的 Base64 SHA-256 雜湊
- 將雜湊新增至 resourceDomains (必須包含 sha256- 前置字串，才能與 integrity 屬性相符)
- 更新 HTML <script> 標記
  - 在 HTML 小工具的指令碼標記中，新增 integrity 和 crossorigin 屬性
- 驗證 CDN/伺服器上的 CORS 標頭
  - 請確認 api.company.com 透過 Access-Control-Allow-Origin: * 提供 component-init.js (或允許 scf.usercontent.goog)，讓瀏覽器可以讀取回應主體，進行 SRI 驗證。
- 重新攝入/更新工具

MCP 工具說明的安全性指南

說明是模型瞭解工具功能的唯一依據，因此必須準確且安全，以免發生非預期的行為。撰寫工具說明時，請遵守下列規範。

說明功能，但不要指定行為。說明必須準確描述工具的功能，而非命令模型執行後續動作。
定義範圍和需求。清楚說明工具的主要目標、特定使用情境 (When)，以及所有必要的輸入 (參數/引數)。
確保真實性。說明必須如實反映工具的基礎程式碼。如果工具會執行寫入或刪除作業，請勿聲稱該工具為唯讀。

安全風險和避免方式

風險區域	建議	務必避免這種做法
提示詞注入	請使用客觀、陳述性的語言，清楚說明工具的用途和功能。	使用命令式指令覆寫模型行為或變更系統流程 (例如「你必須說…」、「跑步後，你必須…」)。只有在定義結構化參數限制或使用規則時，才能使用「必須」或「重要」等命令式字詞。
	工具說明文字請使用標準純文字格式。	使用吸引注意力的格式，例如過度使用大寫和 `VERY IMPORTANT:` 或 `CRITICAL` 等標記。
	請只著重於工具的功能和預期行為。	加入角色扮演指示或忽略先前指示的指令。
工具遮蔽和劫持	說明應具體，且僅限於工具實際相關的功能。	工具說明過於廣泛、模糊，或聲稱單一工具可執行多項不相關的功能。
	選擇不重複、具描述性且合理的工具名稱。	使用與可信工具名稱略有不同的名稱，或使用通用名稱 (例如 `do_everything_tool`、`assistant_tool`)。
	請勿在說明中提及其他應用程式或外部平台工具的名稱。	明確參照其他工具，或建立新規則，規定其他工具的使用時機或方式。
	允許模型的規劃工具根據使用者情境，選取最合適的工具。	加入反競爭用語或任何類型的搜尋引擎最佳化 (SEO) 提示，指示模型優先推薦您的工具，而非類似工具。
操控觸發條件	說明不會參照或回應一般對話記錄詞組。	建立條件式邏輯，根據常見且無害的使用者詞組 (例如「謝謝」、「總結來說」) 觸發有害動作。
濫用參數	請只定義工具函式所需的參數，並使用輸入資料專屬的名稱 (例如 `file_id`、`search_term`)。	定義函式參數時，請使用與 Agent 內部狀態相同的名稱 (例如 `system_prompt`、`conversation_history`、`full_context`)。
資料竊取	隱私保護設計：不透明 ID 和主機代管驗證。使用非機密 ID，而非原始 PII。所有資料處理作業都必須在授權的安全範圍內進行，且不得在公開說明中提及資料會傳送至外部。工具執行時，會透過 OAuth 握手程序自動繼承權限。任何機密資訊都應先經過清理，再傳送至適用的 Google 產品。	以任何違反適用 Google 產品服務條款的身分，向使用者、個人或業務資料或實體要求 PII、受保護的健康資訊或任何其他個人和/或機密資訊。提及或要求將任何使用者資料 (查詢、位置、情境) 傳送至未經授權的第三方網址、記錄服務或外部系統。

功能和命名最佳做法

除了確保工具說明安全無虞，您也必須確保模型能可靠地選取並執行工具，不會混淆。請遵循下列功能和命名最佳做法：

參數準確度。請確保說明中的所有參數名稱和類型，與工具的實際實作完全相符。
命名合理。工具名稱應清楚明確地提示其功能。避免使用過於籠統的名稱，例如「execute」。名稱也必須與更廣泛的工具生態系統一致。

附錄：基礎架構和網路許可清單

如果代管基礎架構、API 閘道或防火牆會依來源 IP 位址限制傳入連線，請將下列 Google 傳出 CIDR 區塊加入許可清單：

108.177.64.0/20
142.250.88.0/22
172.217.80.0/20
192.178.20.0/22
192.179.0.0/20
74.125.232.0/24
136.121.40.0/21

請確認您的環境允許來自這些 IP 範圍的流量，透過 HTTPS 通訊埠 443 傳輸，這樣適用的 Google 產品才能連上遠端 MCP 伺服器，進行 MCP 初始化、工具探索和要求執行。

MCP 連結的應用程式整合標準 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

指導原則

版本管理

MCP 通訊協定版本相容性

傳輸通訊協定規格

伺服器指令

視為「模型提示」，並提供使用情境

互補而非重複

伺服器操作說明範例

工具指南

工具命名慣例

使用直覺、人類可讀的名稱

請注意大小寫樣式

使用明確的動詞 + 名詞命名

工具精細程度

將工具視為不可分割的端點

使用較扁平的結構定義

遵守預先匯總和酬載防護機制

省略內部和中繼工具

工具精細程度的注意事項

宣告工具註解以確保安全

工具說明

撰寫指令，而非註解

說明「如何」

說明原因

提供連結

指定格式

避免模型自行判斷

工具說明範例

工具參數

明確類型

使用列舉處理固定值組合

清楚說明必要參數

套用語意結構定義比對

工具參數範例

回應和錯誤處理

使用 JSON

在回覆中加入網址

自述式防幻覺酬載

導入完善的錯誤處理機制

使用 try/except

提供可採取行動的錯誤

確認動作

回應和錯誤處理範例

MCP 錯誤處理

工具背景資訊

使用者體驗算繪

MCP 應用程式

註冊時擷取資源

CSP 指南

MCP 工具說明的安全性指南

附錄：基礎架構和網路許可清單

MCP 連結的應用程式整合標準