Apigee 和 MCP 使用入门

本页面适用于 Apigee，但不适用于 Apigee Hybrid。

查看 Apigee Edge 文档。

本页介绍了如何使用 Apigee Discovery 代理，使您的 API 可供代理应用中的 Model Context Protocol (MCP) 客户端用作 MCP 工具。

准备工作

在开始之前，请完成以下任务：

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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
确认您已预配 Apigee 组织。如需了解详情，请参阅预配简介。

所需的角色

如需获得创建和部署 MCP 发现代理所需的权限，请让您的管理员为您授予用于部署 Apigee 代理的服务账号的 Apigee Admin (roles/apigee.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

启用 API

Enable the Apigee, Model Armor APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

设置环境变量

在包含 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 发现代理模板创建并部署新的 Apigee 代理。部署代理后，您可以创建 API 产品，将代理中的 MCP API 操作捆绑到 API 产品中。作为 API 产品，您的 API 操作/工具可通过集成到 API Hub 中供 MCP 客户端发现。

以下部分介绍了创建和部署 MCP 发现代理、创建 API 产品以及列出可用工具的步骤：

创建描述 API 操作的 OpenAPI 3.0.x 规范。
创建 MCP 发现代理。
（可选）向 MCP 发现代理添加 Google 身份验证政策。
部署 MCP 发现代理。
（可选）创建 API 产品。
（可选）创建开发者和应用。
（可选）初始化您的 MCP 服务器。
列出可用的工具。

创建描述 API 操作的 OpenAPI 3.0.x 规范

在创建和部署 MCP 发现代理之前，您需要创建一个 OpenAPI 3.0.x 规范，用于描述您要作为 MCP 工具公开的 API 操作。本快速入门使用一个示例 OpenAPI 3.0.x 规范，其中包含三个 API 操作：

GET/artists：返回艺术家列表。
POST/artists：允许用户发布新艺术家。
GET /artists/{username}：通过艺术家的唯一用户名获取有关该艺术家的信息。

如需创建 OpenAPI 3.0.x 规范，请执行以下操作：

在 API 代理软件包的 oas 目录中创建一个新的 mcp-quickstart-openapi.yaml 文件。

将以下内容添加到该文件中：

# 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/v1
    description: Cymbal Group Production Server
  - url: https://internal.products.com/v1
    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

创建 MCP 发现代理

现在，您已拥有定义 API 操作的 OpenAPI 3.0.x 规范，接下来可以使用 MCP 发现代理模板创建新的 API 代理。

如需创建 MCP 发现代理，请执行以下操作：

在 Google Cloud 控制台中，前往 API 代理页面。
前往 API 代理
点击 + 创建，打开 创建 API 代理 窗格。
在代理模板框中，选择 MCP 发现代理。
在代理详情部分中，输入以下详细信息：
- 代理名称：代理的名称。
- 说明（可选）：代理的说明。例如 My first MCP Discovery Proxy。
点击下一步。
在 OpenAPI 规范部分，使用文件浏览器选择您在上一步中创建的 OpenAPI 3.0.x 文件。
点击下一步。
在部署（可选）部分，您可以暂时跳过代理的部署。点击下一步。
点击创建。
注意：创建代理最多可能需要 10 分钟。操作完成后，您将进入代理摘要详情页面，您可以在该页面上看到 MCP 发现代理。

您可以在修订版本表的端点摘要列中点击查看，以查看代理的目标端点和服务器端点。所选代理修订版本的修订版本端点摘要会显示以下信息：

代理端点：在此示例中，系统会显示基本路径为 /mcp 的 default 代理端点。如果向代理添加了其他主机名或环境组，这些主机名或环境组也会显示在此处。
目标端点：在此示例中，default 目标连接设置为 mcp.apigee.internal/mcp。

（可选）向 MCP 发现代理添加政策

在此步骤中，您将向 MCP 发现代理添加 Google 身份验证。通过添加 Google 身份验证政策，您可以确保对 MCP 发现代理的所有请求都经过身份验证和授权。

如需配置令牌验证，请在 API 代理流的最开始（ProxyEndpoint 预流的开始）处放置一项 OAuthV2 政策，其中包含 VerifyAccessToken。放置后，在发生任何其他处理之前都将验证访问令牌；如果令牌被拒绝，Apigee 会停止处理并将错误返回给客户端。

如需添加 VerifyAccessToken 政策，请执行以下操作：

在代理详情页面中，点击开发标签页。
在代理端点下，点击默认，然后点击 PreFlow。
在代理流编辑器中，点击 添加政策步骤。
在 Add policy step（添加政策步骤）对话框中，点击创建新政策。
在政策列表中，选择安全性下的 OAuth v2.0。
（可选）更改政策名称和显示名称。例如，为了便于阅读，您可以将显示名称和名称都更改为 VerifyAccessToken。
点击添加。

部署 MCP 发现代理

如需部署 MCP Discovery Proxy，请执行以下操作：

点击部署以打开部署 API 代理窗格。
修订版本字段应设置为 1。否则，请点击 1 以将其选中。
在环境列表中，选择要部署代理的环境。环境必须是全面环境。
输入您在之前的步骤中创建的服务账号。
点击部署。

API 代理的 XML 配置会显示在开发标签页中。

（可选）创建 API 产品

在此步骤中，您需要创建一个 API 产品，其中包含您要向开发者或代理公开的代理中的操作和端点。这是可选步骤。如果您的 MCP 端点在调用 tools/list 方法时不需要进行身份验证，您可以跳过此步骤，直接前往初始化 MCP 服务器。

如需创建 API 产品，请执行以下操作：

在 Google Cloud 控制台中，前往 API 产品页面。
前往 API 产品
点击 add 创建。系统会显示产品详情页面。在产品详情部分中，输入以下详细信息：
- 名称：API 产品的名称。例如 MCP API product。
- 显示名称：API 产品的显示名称。例如 MCP product。
- 说明：API 产品的说明。例如 API product for hostname cymbal.products.com。
- 环境：输入您部署 MCP 发现代理的环境。例如 default。
- 访问权限：选择公开。
- 配额：在本教程中，您可以跳过此字段。
- 允许的 OAuth 范围：以英文逗号分隔列表的形式输入您的操作。在本教程中，请输入 artists.get, artists.post, artists.username.get。
在操作部分中，点击 + 添加操作以打开操作窗格。
在操作窗格中：
1. 过滤或滚动以在代理列表中找到并选择您的 MCP 发现代理。
2. 在操作部分中，输入您要纳入 API 产品中的资源路径的路径和方法。在本教程中：
  - 路径：输入 /。
  - 方法：选择 POST。
3. 点击保存。

创建 API 产品后，系统会显示产品详情页面。现在，该 API 产品已准备好发布到您的开发者门户，并可供开发者和代理使用。

（可选）创建开发者和应用

在此步骤中，您将在 Apigee 组织中创建一个开发者和一个应用，并使用这些资源来测试 MCP 端点。这是可选步骤。如果您的 MCP 端点在调用 tools/list 方法时不需要进行身份验证，您可以跳过此步骤，直接前往初始化 MCP 服务器。

如需设置测试所需的资源，请执行以下操作：

前往 Google Cloud 控制台中的 Apigee API Management 页面：
Apigee API Management
选择您安装 Apigee Operator for Kubernetes 的 Apigee 组织。
创建开发者：
1. 依次选择分发 > 开发者。
2. 在开发者页面上，点击 + 创建。
3. 在添加开发者页面中，使用您希望使用的任何值填写必填字段。
4. 点击添加。
创建应用：
1. 依次选择分发> 应用。
2. 在应用页面上，点击 + 创建
3. 在创建应用页面上，使用以下值填充应用详情部分中的必填字段：
  - 应用名称：mcp-test-app
  - 开发者：选择您在上一步创建的开发者，或从列表中选择其他开发者。
4. 在应用凭据部分，点击 + 添加凭据。
5. 在凭据部分，使用以下值填写凭证详细信息部分的必填字段：
  - 凭据名称：demo-credential
  - 凭据类型：选择 API 密钥。
6. 点击创建。
7. 在产品部分中，点击 + 添加产品。
8. 选择上一步创建的 api-product-1。
9. 点击添加。
10. 点击创建。
在应用详情页面的凭据部分中，点击以显示密钥的值。
复制 Key 值。您将在后续步骤中使用此密钥对您的服务执行 API 调用。
在应用详情页面的凭证部分中，点击以显示应用密钥的值。
复制应用 Secret 值。您将在后续步骤中使用此值生成访问令牌。

初始化 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": {}
      }' \
  -H "Authorization: Bearer TOKEN"

替换以下内容：

MCP_ENDPOINT_URL：您的 MCP 端点基本 URI。例如 cymbal.products.com。
（可选）TOKEN：OAuth 2.0 访问令牌

成功的响应类似于以下内容：

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

列出 API 产品中可用的 MCP 工具

在此步骤中，您将向 tools/list 方法发送请求，以确认 MCP 端点中可用的工具列表。

注意：您可以在 API 产品级别控制 tools/list 方法的身份验证。如果访问 MCP 端点不需要进行身份验证，则 MCP 发现代理不需要成为 API 产品的一部分。不过，请注意，允许未经身份验证的访问方法可能会给您的组织带来安全风险。

向 Apigee 代理的 tools/list 方法发送请求：

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