開始使用 Apigee 和 MCP

本頁內容適用於 Apigee，但不適用於 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁說明如何使用 Apigee Discovery Proxy，讓代理程式應用程式中的 Model Context Protocol (MCP) 用戶端，將您的 API 做為 MCP 工具使用。

事前準備

開始之前，請先完成下列工作：

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 確認您已佈建 Apigee 機構。MCP Discovery Proxy 適用於訂閱、即付即用和評估機構。詳情請參閱「佈建簡介」。
  7. 確認您已在專案中佈建 Apigee API 中心執行個體。 Google Cloud 詳情請參閱「在 Google Cloud 控制台中佈建 API 中心」。如要確認 API 中樞服務是否已啟用，請查看 Google Cloud 控制台中的「中樞」頁面。

    前往 API Hub

  8. 確認 Apigee 執行個體已附加至 API 中心服務。 API 中樞的 Apigee Edge for 公有雲或 Apigee Edge for 私有雲外掛程式執行個體，不支援使用 MCP Discovery Proxy。詳情請參閱「附加執行階段專案」。您可以在 Google Cloud 控制台的「設定」頁面中，前往「專案關聯」分頁標籤，查看執行階段專案的附加狀態。

    前往 API Hub

必要的角色

如要取得建立及部署 MCP Discovery Proxy 所需的權限，請要求系統管理員在您用來部署 Apigee 代理程式的服務帳戶中，授予 Apigee 管理員 (roles/apigee.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

啟用 API

啟用 Apigee API。

啟用 API 時所需的角色

如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 API

設定環境變數

在包含 Apigee 執行個體的 Google Cloud 專案中，使用下列指令設定環境變數： 

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

其中：

  • PROJECT_ID 是 Apigee 執行個體所屬專案的 ID。
  • REGION 是 Apigee 執行個體的 Google Cloud 區域。
  • RUNTIME_HOSTNAME 是 Apigee 執行階段的主機名稱。

如要確認環境變數是否設定正確，請執行下列指令並檢查輸出內容： 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

設定專案

在開發環境中設定 Google Cloud 專案： 

    gcloud auth login
    gcloud config set project $PROJECT_ID

總覽

如要使用 Apigee 將 API 公開為 MCP 工具，請使用 MCP 探索 Proxy 範本建立及部署新的 Apigee Proxy。部署 Proxy 後，您就可以建立 API 產品，將 Proxy 中的 MCP API 作業組合到 API 產品中。透過整合至 API 中心，MCP 用戶端可以探索您的 API 作業/工具 (API 產品)。

以下各節說明如何建立及部署 MCP 探索 Proxy、建立 API 產品，以及列出可用工具：

  1. 建立 OpenAPI 3.0.x 規格，說明 API 作業。
  2. 建立 MCP 探索 Proxy。
  3. (選用) 為 MCP 探索 Proxy 新增安全性政策。
  4. 部署 MCP Discovery Proxy。
  5. (選用) 初始化 MCP 伺服器。
  6. 列出可用的工具。

建立 OpenAPI 3.0.x 規格，說明您的 API 作業

建立及部署 MCP 探索 Proxy 前，您需要先建立 OpenAPI 3.0.x 規格，說明要以 MCP 工具公開的 API 作業。Apigee 中的 MCP 支援下列 OpenAPI 版本：

  • 3.0.0
  • 3.0.1
  • 3.0.2
  • 3.0.3

本快速入門導覽課程會使用 OpenAPI 3.0.x 規格範例，其中包含三項 API 作業：

  • GET /artists：傳回藝人清單。
  • POST /artists：允許使用者發布新藝人。
  • GET /artists/{username}：透過藝人的專屬使用者名稱取得相關資訊。

如要建立 OpenAPI 3.0.x 規格，請按照下列步驟操作：

  1. 在 API Proxy 套件的 oas 目錄中建立新的 mcp-quickstart-openapi.yaml 檔案。
  2. 在檔案中新增下列內容： 
    # mcp-quickstart-openapi.yaml
---
openapi: 3.0.3
info:
  title: Cymbal Group Products API
  description: This is the official API for managing the artists for Cymbal Group Products.
  version: 1.0.0
servers:
  - url: https://cymbal.products.com
    description: Cymbal Group Production Server
  - url: https://internal.products.com
    description: Cymbal Group internal Server
paths:
  /artists:
    get:
      description: Returns a list of artists
      operationId: listArtists
      parameters:
        - name: limit
          in: query
          description: Limits the number of items on a page
          schema:
            type: integer
        - name: offset
          in: query
          description: Specifies the page number of the artists to be displayed
          schema:
            type: integer
      responses:
        "200":
          description: An array of artists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Artist"
    post:
      summary: Create a new artist
      operationId: createArtist
      tags:
        - artists
      requestBody:
        description: The artist to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Artist"
      responses:
        "201":
          description: The newly created artist profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artist"
        "400":
          description: Invalid username supplied
  /artists/{username}:
    get:
      summary: Info for a specific artist
      operationId: showArtistByUsername
      tags:
        - artists
      parameters:
        - name: username
          in: path
          required: true
          description: The username of the artist to retrieve
          schema:
            type: string
      responses:
        "200":
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artist"
        "404":
          description: Artist not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            artists.read: Grants read access
            artists.write: Grants write access
  schemas:
    Artist:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the artist

主機名稱比對規定

OpenAPI 規格 servers.url 欄位中的主機名稱值，必須與部署 MCP Discovery Proxy 的 Apigee 環境的環境群組 hostname 完全相符。tools/list 和 tools/call 呼叫必須相符，才能正常運作。

下表顯示 OpenAPI 規格中的主機名稱設定，以及 Apigee 環境群組中對應的主機名稱設定：

元件 必要設定 範例值 佐證資訊
Apigee 環境群組 主機名稱必須在環境群組中設定。 cymbal.products.com、internal.products.com 環境群組可讓您使用主機名稱，將要求轉送至環境群組。
OpenAPI 規格 OpenAPI 規格的 servers.url 欄位值必須與部署 MCP Discovery Proxy 的 Apigee 環境的環境群組主機名稱完全相符。 https://cymbal.products.com 如果 servers.url 主機名稱與 MCP Discovery Proxy 部署所在 Apigee 環境對應的環境群組主機名稱不符，部署 Proxy 時就會發生錯誤。

建立 MCP 探索 Proxy

您現在已有定義 API 作業的 OpenAPI 3.0.x 規格，可以使用 MCP Discovery Proxy 範本建立新的 API Proxy。

如要建立 MCP 探索 Proxy，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「API proxies」(API Proxy) 頁面。

    前往 API Proxy

  2. 按一下「+ 建立」，開啟「建立 API Proxy」窗格。
  3. 在「Proxy template」方塊中，選取「MCP Discovery Proxy」。
  4. 在「Proxy details」部分，輸入下列詳細資料：
    • Proxy 名稱：Proxy 的名稱。
    • 說明 (選用)：代理程式的說明。例如：My first MCP Discovery Proxy。
  5. 點選「下一步」。
  6. 在「OpenAPI specs」(OpenAPI 規格) 專區中，使用檔案瀏覽器選取您在上一個步驟中建立的 OpenAPI 3.0.x 檔案。
  7. 點選「下一步」。
  8. 在「Deploy (optional)」(部署 (選用)) 區段中，您可以暫時略過 Proxy 的部署作業。點選「下一步」。
  9. 按一下 [建立]。

如要查看 Proxy 的目標和伺服器端點，請按一下「修訂版本」表格「端點摘要」欄中的「查看」。所選 Proxy 修訂版本的「修訂版本端點摘要」會顯示下列資訊：

  • Proxy 端點：在本範例中，系統會顯示基本路徑為 /mcp 的 default Proxy 端點。如果將其他主機名稱或環境群組新增至 Proxy，也會顯示在這裡。
  • 目標端點：在本範例中，default 目標連線設為 ORG_NAME.mcp.apigee.internal，其中 ORG_NAME 是 Apigee 機構的名稱。 為確保回溯相容性，系統也支援目標 mcp.apigee.internal。

(選用) 為 MCP 探索 Proxy 新增安全性政策

部署 MCP Discovery Proxy 前，您可以新增安全性政策，強制執行安全性需求。建議您使用 OAuth 權杖或 API 金鑰，確保 MCP Discovery Proxy 的存取安全。

本節說明如何將 OAuthV2 政策新增至 MCP Discovery Proxy。這可確保所有對 MCP Discovery Proxy 的要求都經過驗證和授權。如要改用 API 金鑰，請參閱「透過要求 API 金鑰確保 API 安全」一文，瞭解建議的步驟。

如要設定權杖驗證，請在 API Proxy 流程的開頭 (ProxyEndpoint Preflow 的開頭)，放置具有 VerifyAccessToken 作業的 OAuthV2 政策。如果放在這裡，系統會在進行任何其他處理作業前驗證存取權杖，如果權杖遭拒，Apigee 會停止處理作業，並將錯誤傳回給用戶端。

如要新增 VerifyAccessToken 政策，請按照下列步驟操作：

  1. 在 Proxy 詳細資料頁面中，按一下「開發」分頁標籤。
  2. 在「Proxy endpoints」下方，依序點選「default」和「PreFlow」。

  3. 在 Proxy 流程編輯器中，按一下「新增政策步驟」。

    在「Proxy Endpoints」下方列出的端點中，選取「PreFlow」。
  4. 在「Add policy step」對話方塊中，選取「Create new policy」。
  5. 在政策清單的「Security」下方，選取「OAuth v2.0」。
  6. 視需要變更政策名稱和顯示名稱。舉例來說，為了提升可讀性，您可以將「顯示名稱」和「名稱」都變更為「VerifyAccessToken」。
  7. 按一下「新增」。

部署 MCP 探索 Proxy

如要部署 MCP Discovery Proxy，請按照下列步驟操作：

  1. 按一下「Deploy」(部署)，開啟「Deploy API proxy」(部署 API Proxy) 窗格。
  2. 「修訂版本」欄位應設為「1」。如未選取，請按一下 1 選取。
  3. 在「Environment」(環境) 清單中，選取要部署 Proxy 的環境。環境必須是全面環境。
  4. 輸入您在稍早步驟中建立的「服務帳戶」。
  5. 點選「Deploy」(部署)。

按一下「Deploy」(部署) 後，Apigee 就會開始部署 Proxy，並佈建下游元件。這段時間可能需要幾分鐘，使用者介面會顯示部署作業的「Provisioning」(佈建) 狀態。

程序完成後，狀態會變更為「已部署」，Proxy 即可處理流量。

部署 Proxy 後，請確認 OpenAPI 規範 servers.url 欄位中的主機名稱值，與部署 MCP Discovery Proxy 的 Apigee 環境環境群組 hostname 完全相符。

在 API 中心探索 MCP 工具

部署 MCP Discovery Proxy 後，其 API 作業會自動擷取至 API 中心，並以 MCP 工具的形式供探索。

如要在 API 中心查看 MCP 工具，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「API Hub > APIs」(API 中心 > API) 頁面。

    前往 API Hub API

  2. 按一下「篩選器」，然後選取「樣式」>「MCP」，再按一下「套用」。
  3. 部署的 MCP Proxy 應會顯示在清單中。API 中心擷取管道會自動將 OpenAPI 規格中定義的路徑，對應至中心列出的個別 MCP 工具。

貴機構的開發人員現在可以在 API 中心使用篩選器或語意搜尋功能，透過自然語言查詢尋找相關的 MCP 工具。

初始化 MCP 伺服器

在本步驟中，您會將要求傳送至 MCP 端點，藉此初始化 MCP 伺服器，並確認伺服器是否正常運作。

如要初始化及測試 MCP 伺服器，請將下列要求傳送至 MCP 端點： 

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
          "protocolVersion": "MCP_PROTOCOL_VERSION"
        }
      }' \
  -H "Authorization: Bearer TOKEN"

更改下列內容：

  • MCP_ENDPOINT_URL：您的 MCP 端點基準 URI。例如：cymbal.products.com。
  • MCP_PROTOCOL_VERSION：MCP 通訊協定版本。例如，2025-11-25。詳情請參閱 MCP 規格中的「版本交涉」。
  • (選用) TOKEN：OAuth 2.0 存取權杖

成功的回應會與下列內容相似：

{
"id":1,
"jsonrpc":"2.0",
"result":
  {
    "capabilities":
    {
      "tools":
      {
        "listChanged":false
      }
    },
    "protocolVersion":"2025-11-25",
    "serverInfo":
      {
        "name":"cymbal.products.com",
        "version":"1.0.0"
      }
    }
  }

列出可用的 MCP 工具

在這個步驟中，您會向 tools/list 方法傳送要求，確認 MCP 端點中可用的工具清單。

向 Apigee 代理的 tools/list 方法傳送要求：

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: MCP_PROTOCOL_VERSION" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
      }' \
  -H "Authorization: Bearer TOKEN"

更改下列內容：

  • MCP_ENDPOINT_URL：您的 MCP 端點基準 URI。例如：cymbal.products.com。
  • MCP_PROTOCOL_VERSION：MCP 通訊協定版本。例如：2025-11-25。詳情請參閱 MCP 規格中的通訊協定版本標頭。
  • (選用) TOKEN：OAuth 2.0 存取權杖

這個方法會傳回 MCP 端點支援的所有工具。成功的回應會與下列內容相似：

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "description": "Returns a list of artists",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "listArtists"
      },
      {
        "description": "Create a new artist",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "createArtist"
      },
      {
        "description": "Info for a specific artist",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "showArtistByUsername"
      }
    ]
  }
}

端點初始化後，開發人員和代理程式就能使用 API 產品探索 MCP 工具。

監控與數據分析功能

您可以使用 Apigee Analytics 監控 MCP 流量，並查看工具層級指標。 Apigee Analytics 可讓您篩選指標，區分標準 API 流量和 MCP 專屬流量，並查看 tools/list 與 tools/call 要求的用量。詳情請參閱「在 Apigee 中監控及分析 MCP 流量」。

後續步驟