Apigee 中的 Model Context Protocol (MCP) 總覽

本頁面適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁說明如何使用 Apigee，將 API 做為 MCP 工具公開給代理應用程式。Apigee 的 MCP 適用於訂閱、即付即用和評估組織，包括啟用資料落地的組織。從 Apigee Hybrid 1.17.0 版開始，Apigee Hybrid 也支援 MCP，執行階段資料層會在您自己的 Kubernetes 叢集內執行，而非在 Google 代管的基礎架構上執行。如要瞭解 Hybrid 專屬的安裝和設定流程，請參閱「在 Apigee Hybrid 中啟用 MCP」。

什麼是 MCP？

Model Context Protocol (MCP) 是由 Anthropic 開發的開放原始碼通訊協定，可標準化 AI 應用程式連結資料來源、工作流程和工具的方式。

AI 應用程式可使用 MCP，將 Google Cloud 和 Apigee 服務做為工具存取。在這種情況下，請務必瞭解下列 MCP 術語：

  • MCP 主機：與使用者互動的 AI 應用程式或環境，MCP 主機會使用大型語言模型 (LLM)，處理可能需要外部資料或工具的要求。
  • MCP 用戶端：MCP 主機中的元件，可協助 LLM 和 MCP 伺服器之間的通訊。它會將 LLM 的要求轉換成 MCP 伺服器可理解的內容，並將 MCP 伺服器的回覆轉換成 LLM 可理解的內容。此外，還會尋找並使用可用的 MCP 伺服器。
  • MCP 伺服器：為 LLM 提供脈絡、資料或功能的外部服務，在 LLM 和 MCP 用戶端之間扮演 Proxy 角色。

Apigee MCP 的運作方式

Google、 Google Cloud和 Apigee 的 MCP 端點會實作 MCP 伺服器規格。這樣一來，符合規範的 MCP 用戶端就能存取這些工具，執行下列操作：

  • 探索可用的端點。
  • 列出端點可用的工具。
  • 向端點進行驗證。
  • 根據定義的存取權政策呼叫工具。

只要 MCP 用戶端支援透過 HTTP/S 存取遠端 MCP 端點，就能使用這些工具。由於端點為代管，您不必安裝或管理本機 MCP 伺服器、遠端 MCP 伺服器或其他基礎架構，即可讓代理應用程式存取您的服務。

Apigee 的 MCP 支援 tools/list 和 tools/call 方法的 JSON-RPC。您可以透過參數自訂 MCP 端點，調整可偵測性、安全性、網路可用性和觀測能力。

部署模型

MCP 適用於兩種 Apigee 部署模式：

  • Apigee (SaaS)：MCP 資料層託管於 Google 代管的基礎架構。部署 MCP 探索 Proxy 後，端點即可立即使用。
  • Apigee hybrid (自行託管，從 Apigee hybrid 1.17.0 開始)：MCP 資料層會在您自己的 Kubernetes 叢集內執行。Apigee 控制層會根據 OpenAPI 規格產生 MCP 工具設定，叢集則會按照排程擷取該設定。MCP 要求流量一律不會離開叢集。請參閱「在 Apigee Hybrid 中啟用 MCP」。

Apigee Hybrid 中的 MCP 資料層架構

下圖顯示 MCP 元件在 Apigee 控制層和 Apigee 混合叢集之間的分布情形。

Apigee hybrid 架構中的 MCP：MCP 用戶端會透過 HTTPS 呼叫現有的 Apigee 輸入，並轉送至訊息處理器，然後再轉送至新的叢集內 MCP 資料層。MCP 工具設定是由 Apigee 控制層產生，並由叢集提取；Apigee 控制層不會呼叫叢集。

規劃和安全性審查時，必須考量這個架構的兩項屬性：

  • MCP 要求流量會保留在叢集內。MCP 用戶端會透過與其他 Apigee Proxy 相同的網址，連至現有的 Apigee 輸入。接著，訊息處理器會將要求轉送至同一叢集中的 MCP 資料層。在要求時，任何 MCP 要求或回應都不會跨越 Google Cloud 的邊界。
  • 設定是提取，而非推送。MCP 工具設定是由 Apigee 控制層產生，並由叢集中的元件定期擷取。Apigee 控制層絕不會啟動與叢集的連線。如要瞭解叢集輸出必須允許的確切端點，請參閱「傳出網路需求」。

Apigee MCP 的主要功能

Apigee 的 MCP 提供工具探索、安全性和管理功能。這些功能可協助您管理代理應用程式與服務的互動方式。

運用 API 中心簡化工具探索作業

您可以透過 REST 介面存取目錄服務，探索 Apigee 服務可用的 MCP 端點。每個 MCP 端點也支援 MCP tools/list 方法，可讓 MCP 用戶端探索該端點中的可用工具。

此外，MCP 也與 Apigee API 中心整合。部署 MCP 探索 Proxy 後，API 中心會自動擷取其 OpenAPI 規格、指派 MCP API 樣式，並將 API 作業對應至個別 MCP 工具。開發人員可以輕鬆在 API 中心篩選支援 MCP 的 API，並使用語意搜尋功能，透過自然語言查詢找出適合代理應用程式的工具。

後端要求中的工具引數位置

MCP 用戶端呼叫工具時，Apigee 會根據用戶端提供的引數，建構傳送至後端的要求。每個參數在 OpenAPI 規格中宣告的 in 值，會決定該引數在傳出要求中的位置。

OpenAPI in 值 引數在後端要求中的傳送位置
header 做為要求標頭。參數名稱會做為標頭名稱，與規格中的寫法完全相同。
cookie 在 Cookie 要求標頭中，以 name=value 組合的形式提供。如果作業宣告多個 Cookie 參數，這些參數會以 ;  (分號和空格) 分隔，並在一個 Cookie 標頭中傳送。
query 在查詢字串中。
path 替換為要求網址路徑。

無論 in 值為何，每個參數都會顯示在工具的 inputSchema 中，因此 MCP 用戶端會以相同方式提供所有參數。只有在將值放在傳送至後端的要求時，in 值才會變更。

舉例來說，下列作業會在三個位置各宣告一個參數：

paths:
  /orders:
    get:
      operationId: listOrders
      parameters:
        - name: X-Session-Id
          in: header
          schema:
            type: string
        - name: tenantId
          in: cookie
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer

提供所有三個引數的 tools/call 要求會產生下列形式的後端要求：

GET /orders?limit=25
X-Session-Id: sess-abc-123
Cookie: tenantId=tenant-xyz-789

請注意以下行為：

  • 繫結至標頭或 Cookie 的引數不會附加至查詢字串，也不會包含在要求主體中。
  • 系統會略過用戶端未提供的引數。系統不會傳送空白標頭、Cookie 或查詢參數。
  • 繫結標頭會取代後端要求中任何同名的標頭。後端要求中的其他標頭則會原封不動地傳遞。
  • 值在後端要求中會以百分比編碼 (RFC 3986)，因此包含空格或保留字元的值會以編碼形式傳送至後端。如需原始金鑰，請在該處解碼。
  • 如果作業和路徑都宣告了名稱和 in 值相同的參數，則根據 OpenAPI 規格，系統會套用作業層級宣告。
  • 即使宣告不同的 in 值，也請為同一作業的參數指定不同的名稱。OpenAPI 會根據參數的名稱和位置組合來識別參數，但 MCP 工具會為每個引數名稱採用單一值。如果規格宣告兩個同名參數，但 in 值不同，用戶端會提供一個值，並將該值傳送至後端要求中「兩個」宣告的位置：同時宣告 in: cookie 和 in: query 的 sessionId 會傳送至 Cookie 標頭和查詢字串。如果後端邏輯取決於值的來源，請檢查這項資訊。
  • 引數名稱區分大小寫，因此 UserID 和 userid 是兩個不同的引數。如果是 header 參數，請進一步確保名稱不只是大小寫不同：HTTP 標頭名稱不區分大小寫，因此如果兩個標頭參數的名稱只有大小寫不同，後端要求會解析為同一個標頭，且只有其中一個值會保留。

Cookie 是唯一一種繫結可以從要求中移除內容，而非只能新增內容的情況。其他 HTTP 標頭會攜帶獨立的名稱/值組合，每個組合都可以單獨設定，但所有 Cookie 都會共用單一 Cookie 標頭。Apigee 不會將您繫結的 Cookie 與 MCP 用戶端要求中收到的 Cookie 合併：當呼叫提供任何 Cookie 引數時，Cookie 標頭會整體替換為僅繫結的 Cookie。

因此，隨 MCP 用戶端 HTTP 要求傳送的 Cookie 是否會到達後端，取決於個別工具呼叫：

  • 如果作業未宣告任何 cookie 參數，Cookie 標頭會原封不動地轉送至後端。
  • 如果作業宣告 cookie 參數，但呼叫未提供任何參數，則 Cookie 標頭會再次轉送至後端，且不會變更。
  • 只要呼叫提供至少一個 Cookie 引數，Cookie 標頭就會替換為繫結的 Cookie。系統會捨棄用戶端要求中未宣告為 cookie 參數的 Cookie。

由於第三種情況是由特定呼叫提供的引數所驅動，因此具有選用 Cookie 參數的操作可以在一次呼叫中傳遞 Cookie，並在下一次呼叫中捨棄 Cookie。沒有任何設定可以保留未宣告的 Cookie。如果後端依賴 Cookie，請在每個需要 Cookie 的作業中，將其宣告為 cookie 參數，這樣 Cookie 的值一律由工具呼叫提供，而非沿用用戶端要求。

安全性

Apigee 的 MCP 包含多層安全防護機制，可保護您的服務。您可以透過驗證、授權、網路邊界和內容掃描控管存取權。

驗證

Apigee 代管的 MCP 端點支援 OAuth 2.1 和 OpenID Connect (OIDC) 驗證。這能確保只有具備既定身分的代理、MCP 用戶端和使用者，才能存取 MCP 端點及呼叫 MCP 工具。受保護資源中繼資料可讓用戶端探索 OAuth 授權伺服器。

精細授權政策

您可以根據 OAuth 用戶端身分，限制 MCP 工具的存取權。舉例來說，您可以在 MCP Discovery Proxy 中設定政策，指定只有具備已知用戶端身分的指定代理，才能存取付款服務的 MCP 工具。

用戶端負責叫用工具

MCP 用戶端應用程式負責強制執行工具叫用的人工監督，例如在執行狀態變更作業前提示使用者。詳情請參閱模型情境通訊協定說明文件。

觀測能力與數據分析

如果是 Apigee 代管的端點，您可以使用 Apigee Analytics 查看 MCP 工具的詳細使用資訊。您可以透過數據分析，將 MCP 專屬流量與標準 API 流量區隔開來，並查看個別工具層級的指標，例如 tools/list (探索) 與 tools/call (執行) 要求的數量。成效指標也有助於區分 Proxy 負擔和目標回應時間，讓您更有效地找出瓶頸。

可靠性和疑難排解

為改善疑難排解流程，並進一步瞭解部署程序，Apigee 會在 UI 中顯示特定基礎架構和設定錯誤。如果部署作業因 OpenAPI 規格無效或區域基礎架構問題而失敗，UI 會提供可行的意見回饋，協助您解決問題，不必尋求支援。

搭配使用 MCP 與 Apigee

您可以將現有的 Apigee API 公開為 MCP 工具，並透過 MCP 端點存取。這些端點可以在個別主機或環境群組層級設定。舉例來說，如果您的 cymbal 組織有八個主機名稱 (例如 api.cymbal.com、partners.cymbal.com)，每個主機名稱都與不同的環境群組相關聯，則可為每個主機名稱託管專屬的 MCP 伺服器。

代管目標端點 (ORG_NAME.mcp.apigee.internal) 是使用 Apigee 組織中的專用 MCP 探索 Proxy 部署，MCP 伺服器會在此提供。

下表舉例說明客戶 (包括虛構的 Cymbal 組織) 如何使用 Apigee 設定多個 MCP 端點。

客戶 主機名稱和 MCP 基本路徑 MCP 伺服器目標端點 API Proxy 環境 / 環境群組
鈸 api.cymbal.com/mcp cymbal.mcp.apigee.internal
(Cymbal 組織的租戶專案)		 mcp-api-proxy1 prod/prod-env-group
api-internal.cymbal.com/mcp cymbal.mcp.apigee.internal
(Cymbal 組織的租戶專案)		 mcp-api-proxy2 internal/internal-env-group
api-service.cymbal.com/mcp cymbal.mcp.apigee.internal
(Cymbal 組織的租戶專案)		 mcp-api-proxy3 dev/dev-env-group

限制

Apigee 中的 MCP 有下列限制：

  • Apigee 組織中的 MCP 工具數量上限為 1,000 個。
  • MCP 基礎架構部署作業在下列區域可能受到容量限制：
    • europe-central2
    • europe-southwest1
    • europe-west9
    • me-central2

    如果看到佈建錯誤，或佈建狀態一直未變更為「已部署」，可能是因為所選區域暫時達到基礎架構容量上限。請嘗試將 Proxy 部署至其他區域的環境。

  • Apigee 的 MCP 支援下列 OpenAPI 版本：3.0.0、3.0.1、3.0.2、3.0.3.
  • 如果 MCP API 和工具部署在已啟用 VPC-SC 的 Apigee 組織中，則無法使用 Apigee API 中心的 API 洞察功能。
  • 對 MCP 錯誤回應發出 GET 呼叫會傳回 405 錯誤，因為 MCP 伺服器目前不支援伺服器傳送事件 (SSE) 串流。
  • 在 Apigee 1-17-0-apigee-6 版全面推出至所有可用區域之前，Apigee API 中心 API 深入分析不會顯示 MCP 樣式的 API 或 MCP 資源流量。
  • 如果 API 資源已有 API 作業，您就無法將 API 樣式屬性變更為 MCP。

Apigee hybrid 專屬限制

Apigee hybrid 中的 MCP 有下列限制：

  • 宣告為 in: header 或 in: cookie 的工具引數會透過查詢字串傳送。Apigee Hybrid 尚不支援後端要求中的工具引數位置所述的個別位置轉送。在此之前，宣告這兩個位置的參數會以查詢參數的形式傳送至後端，這與該功能推出前的行為相同。該表格的 in: query 和 in: path 列適用於 Apigee Hybrid。
  • MCP 工具數量受限於大小，而非固定數量。Apigee 會強制規定每個組織的 MCP 工具數量上限，Apigee hybrid 則不同，會透過四項大小限制來限制工具容量：OpenAPI 規格檔案大小、MCP Proxy 繫結大小、每個主機名稱的 tools/list 回應大小，以及每個環境群組的主機名稱數量。在預設的回應大小限制下，大多數 OpenAPI 規格通常可容納每個組織 10,000 個 MCP 工具。實際容量會因規格的具體形狀而異 (主要取決於參數和要求主體屬性的數量，以及說明長度)；回覆結構定義不計入預算。如要估算特定 OpenAPI 規格的容量，以及查看四項硬性限制和失敗模式，請參閱「估算 MCP 工具容量」。
  • 啟用或停用 MCP 會觸發 Message Processor Pod 的分階段初期測試版。啟用或停用 MCP 時，Apigee 運算子會更新訊息處理器 Pod 規格，而訊息處理器 ApigeeDeployment 控制器會透過分階段初期測試版執行變更，而非一般的 Kubernetes 滾動式重新啟動。版本只會在啟用和停用轉換時觸發，不會在進行中的 MCP 部署活動或穩定狀態的 MCP 流量中觸發。在核准的維護期間內，安排初始啟用和後續停用作業。
  • MCP Pod 資源大小由客戶管理。MCP Pod 執行時，會採用 Apigee hybrid Helm 圖表內建預設值設定的資源要求和限制。如果工作負載需要更多容量，請在 overrides.yaml 中調整 CPU 和記憶體。如要查看可用欄位，請參閱 overrides.yaml 欄位參考資料。
  • 每個 Apigee 組織和叢集各有一個 MCP 資料層。在 1.17.0 版本中，Apigee 運算子會為叢集中安裝的每個 Apigee 組織佈建一個 MCP 資料層。託管多個 Apigee 組織的叢集會為每個組織執行一個 MCP 資料層，資料層彼此獨立，不會共用設定。
  • 必須在整個環境群組中統一啟用。請為提供相同 Apigee 環境群組的所有叢集，統一啟用 MCP。如果群組中只有部分叢集啟用 MCP，則轉送至未啟用 MCP 叢集的 MCP 要求會收到 503 Service Unavailable 回應。
  • 訊息處理器 和 MCP 資料層之間的單向 TLS。1.17.0 版本在訊息處理器和 MCP 資料層之間使用單向 TLS。
  • MCP 資料層會依賴訊息處理器來取得呼叫端身分。叢集中的 MCP 資料層不會在 1.17.0 中獨立驗證呼叫端，而是信任傳送至該層的要求已由在訊息處理器中執行的 Apigee Proxy 驗證。所有應驗證的 MCP 要求，都必須透過強制執行驗證政策的 Apigee MCP Proxy 傳送 (請參閱「管理 MCP 工具存取權」)。正式版客戶應套用叢集輸入控管機制，確保只有訊息處理器 Pod (與 Apigee hybrid 安裝在相同 Kubernetes 命名空間中的 Kubernetes 標籤 app=apigee-runtime) 可透過 TCP 443 存取 MCP 服務。請使用平台支援的政策引擎 (Kubernetes NetworkPolicy、Cilium、Calico、Istio AuthorizationPolicy) 強制執行這項限制。

後續步驟