在 Apigee Hybrid 中启用 Model Context Protocol (MCP)

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面介绍了如何在运行 1.17.0 或更高版本的现有 Apigee Hybrid 集群中启用 Model Context Protocol (MCP)。完成此过程后,您的集群将运行新的集群内 MCP 数据平面,并且您的消息处理器已准备好将 MCP 工具调用路由到该平面。然后,您可以按照共享的 MCP 快速入门部署您的第一个 MCP Discovery Proxy。

如需了解 Apigee 和 Apigee Hybrid 之间共享的 MCP 概念、架构和功能详情,请参阅 Apigee 中的 MCP 概览。

此过程的作用

在 Apigee Hybrid 集群上启用 MCP 会进行以下更改:

  1. 向 apigee-watcher 身份授予对 Apigee 控制平面上的 MCP 配置的访问权限。您需要将 apigee-watcher 服务账号添加到 Apigee 组织的 controlPlaneAccess 资源上的 watcher_identities 列表中,以便 MCP 边车可以从 Apigee 控制平面拉取 MCP 配置软件包。这是一项控制平面更改,范围限定为 Apigee 组织,并且每个组织只需执行一次,无论有多少个集群为该组织提供服务。
  2. 添加新的集群内 MCP 数据平面。系统会在安装 Apigee Hybrid 的同一 Kubernetes 命名空间(默认 apigee)中创建一组新的 MCP Pod,以及运行这些 Pod 所需的支持性 Kubernetes 资源(Service、Pod 横向自动扩缩器和 RBAC)。MCP 工具调用由这些 Pod 处理。
  3. 配置消息处理器以访问 MCP 数据平面。Apigee Operator 会更新您的消息处理器 Pod 规范,以便 MP 将 MCP 工具调用路由到新的集群内 MCP 数据平面。应用此更改会触发消息处理器(由 ApigeeDeployment 控制器管理)的分阶段 Canary 版本;之前的 Pod 会继续处理流量,直到新 Pod Ready。该版本仅在启用和停用转换时触发,而不会在持续的 MCP 活动或稳态 MCP 流量中触发。请在获批的维护窗口中运行此过程,并等待发布完成后再继续。

第 1 步:修改 overrides.yaml

打开用于 Apigee Hybrid Helm 图表的 overrides.yaml 文件。在文件的顶层,添加以下内容:

enableMcpServer: true

这是启用 MCP 所需的最低配置。它使用 apigee-org 图表中的内置默认值:两个 MCP 数据平面副本,在 CPU 利用率为 70% 时自动扩缩到 10 个,MCP 数据平面容器上的资源请求为 500m CPU 和 512Mi 内存,限制为 2000m CPU 和 1Gi 内存。如需自定义副本数量、资源请求或 MCP 服务账号,请参阅本页面后面的参考:overrides.yaml 中的 MCP 字段。

下面是合并后的 overrides.yaml 的已完成示例,每种身份验证方式各一个。请使用与您现有基本安装配置方式相匹配的示例;MCP 专用行会通过注释突出显示,并且在所有三种变体中都相同。

选择与您的基本安装如何向 Google Cloud 验证 Apigee 组件相匹配的标签页。所选内容会应用于此页面上每个变体范围内的代码块。

Workload Identity (GKE)

如果您的基础安装通过 GKE Workload Identity(磁盘上没有服务账号密钥文件)向 Google Cloud 验证 Apigee 组件,请使用此变体。

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
  workloadIdentity:
    enabled: true
    gsa: apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
envs:
- name: my-env

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

基于文件的服务账号密钥

如果您的基础安装通过您分发到每个集群的服务账号密钥文件向 Google Cloud 验证 Apigee 组件,请使用此变体。

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
guardrails:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
mart:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
connectAgent:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
watcher:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json  # MCP also uses this key file
envs:
- name: my-env
  serviceAccountPaths:
    synchronizer: ./service-accounts/apigee-non-prod.json
    runtime:      ./service-accounts/apigee-non-prod.json

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

工作负载身份联合 (AKS/EKS)

如果您的基本安装在 AKS 或 EKS 上,并且通过工作负载身份联合向 Google Cloud 进行身份验证,请使用此变体。MCP 使用 apigee-watcher 已在使用的凭据配置文件(来自 watcher.serviceAccountPath),因此您无需添加任何 MCP 专属身份配置。如果您改为将凭证配置存储在 Kubernetes Secret 中,请参阅其他身份机制。

将 MCP 顶级密钥添加到现有 WIF overrides.yaml 中:

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

不设置 mcpServer.gsa 和 mcpServer.serviceAccountPath。MCP 边车使用与 apigee-watcher 相同的凭证配置文件(来自 watcher.serviceAccountPath)。

第 2 步:向观察者身份授予对控制平面上的 MCP 配置的访问权限

MCP sidecar 使用 apigee-watcher 组件的 Google Cloud 服务账号(您在第 1 步中选择的身份)从 Apigee 控制平面提取其配置包。在 MCP pod 启动之前,请将该服务账号添加到 Apigee 组织的 controlPlaneAccess 资源上的 watcher_identities 列表中。如果不授予此权限,MCP 边车对 apigee.googleapis.com 的调用(用于检索 MCP 配置引用)将返回 404 Not Found,并且 MCP 数据平面永远无法准备好处理工具流量。

此步骤每个组织只需执行一次(而不是每个集群执行一次)。如果您已为同一 Apigee 组织中的上一个集群授予访问权限,请跳过此步骤。

  1. 设置您用于 API 调用的 shell 变量。重复使用安装中的值:
    export ORG_NAME=YOUR_ORG_NAME
    export PROJECT_ID=YOUR_GCP_PROJECT_ID
    export WATCHER_SA=apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com
    export TOKEN=$(gcloud auth print-access-token)

    其中:

    • YOUR_ORG_NAME 是您的 Apigee Hybrid 组织的名称。
    • YOUR_GCP_PROJECT_ID 是托管 Apigee Hybrid 组织的 Google Cloud 项目。
    • WATCHER_SA 是 apigee-watcher 服务账号的邮箱。如果您在 overrides.yaml 中替换了 watcher.gsa,请使用该值,而不是默认值 apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com。
  2. 调用 updateControlPlaneAccess API,将观察器服务账号添加到 watcher_identities 列表:

    无数据驻留

    curl -X PATCH -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \
      -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"
    

    数据驻留

    curl -X PATCH -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \
      -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"
    

    其中,如果您的 Apigee Hybrid 安装使用数据驻留,则 CONTROL_PLANE_LOCATION 是控制平面数据的位置。如需查看可用位置的列表,请参阅可用的 Apigee API 控制平面区域。

    该调用会返回一个长时间运行的操作。请等待它运行完毕,然后再运行下面的验证步骤。

  3. 验证赠金是否已到账。调用 getControlPlaneAccess,并确认监控器服务账号显示在响应的 watcherIdentities 字段中:

    无数据驻留

    curl -X GET -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"
    

    数据驻留

    curl -X GET -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"
    

    响应应包含一个 watcherIdentities 数组,其中包含您的观察者服务账号。例如:

    {
      "synchronizerIdentities": [ ... ],
      "analyticsPublisherIdentities": [ ... ],
      "watcherIdentities": [
        "serviceAccount:apigee-watcher@YOUR_GCP_PROJECT_ID.iam.gserviceaccount.com"
      ]
    }

    如果响应中没有 watcherIdentities,或者其中不包含您的观察器服务账号,请重新运行 PATCH 命令,并检查操作状态是否存在错误,然后再继续。

第 3 步:升级 apigee-operator 图表

首先升级 Operator 图表。操作员图表拥有新 MCP 资源的架构;组织图表引用这些资源。如果升级顺序不正确,则会导致 helm upgrade 成功,但不会创建 MCP pod。

helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

该命令会在一分钟内完成。确认 Operator Deployment 已完全发布新映像(apigee-controller-manager Deployment 是一个普通的 Kubernetes 资源,而不是 ApigeeDeployment,因此 kubectl rollout status deploy 是正确的命令):

kubectl rollout status deploy -n APIGEE_NAMESPACE apigee-controller-manager --timeout=2m

预期输出:

deployment "apigee-controller-manager" successfully rolled out

第 4 步:升级 apigee-org 图表

helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

现在,两个协调循环会并行运行:

  • Apigee Operator 会创建 MCP Deployment、Service、HPA、ServiceAccount、Role 和 RoleBinding。MCP pod 会一次启动两个(取决于 Kubernetes 调度);每个 pod 中的边车容器会在启动后不久从 Apigee 控制平面执行其首次配置提取。
  • Apigee 运维人员会将 hostAliases 条目注入到消息处理器 Pod 规范中,这会触发 apigee-runtime ApigeeDeployment 的发布。

第 5 步:验证安装

验证 MCP 数据平面是否正在运行

检查操作器创建的四个与 MCP 相关的资源。资源名称包含一个派生自组织的后缀;以下示例使用 ORG_CR_SUFFIX 作为该后缀的占位符,Pod 后缀和 Service ClusterIP 在您的环境中会有所不同。

MCP pod(默认两个;在负载下自动扩缩到 10 个):

kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME                                                READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-abc12   2/2     Running   0          2m
apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-def34   2/2     Running   0          2m

每个 Pod 都必须在 READY 列中显示 2/2。每个 Pod 中的两个容器分别是:

  • apigee-mcp-server - MP pod 连接到的 MCP 数据平面容器。
  • apigee-mcp-server-config - 配置边车(apigee-watcher 二进制文件的一种模式),用于从 Apigee 控制平面提取配置软件包,并将其写入 MCP 数据平面容器读取的共享卷。

MCP ApigeeDeployment(Kubernetes 自定义资源,而非普通 Deployment):

kubectl get apigeedeployment -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME                              STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   running                 2m

预期状态为 running。此外,验证底层 Pod 是否为 2/2 Running:

kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME                                    READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH   2/2     Running   0          2m

MCP 服务:

kubectl get svc -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME                              TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                              AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   ClusterIP   10.96.42.17   <none>        80/TCP,443/TCP,15021/TCP,15000/TCP   2m

MCP HorizontalPodAutoscaler:

kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server

确认 MINPODS 与 overrides.yaml(默认值为 2)中的 mcpServer.replicaCountMin 匹配,并且 MAXPODS 与 mcpServer.replicaCountMax(默认值为 10)匹配。TARGETS、REPLICAS 和 AGE 列取决于实时指标和集群状态。

验证消息处理器 Pod 是否收到了 hostAliases 条目

每个 MP pod 都必须显示注入的条目,即使只有一个 pod 缺少该条目,该 pod 也无法路由 MCP 工具调用。列出所有 MP pod 及其 hostAliases:

kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'

预期输出:每个 MP pod 都会列出一个 hostAliases 数组,其中包含一个条目,该条目具有两个指向前一步骤中的 MCP Service ClusterIP 的主机名(第二个主机名使用小写的组织名称)。消息处理器 Pod 名称遵循模板 apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH,其中 TRUNCATED_ORG 是您的组织名称(如果组织名称较长,则会被截断以符合 Kubernetes 63 个字符的名称限制),ENV_GROUP_HASH 是每个环境的部署组哈希,REV 是当前版本修订版本号(四位数,例如 1170),POD_HASH 是每个 Pod 的随机后缀。例如:

apigee-runtime-myorg-env1-abc12-1170-def34   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]
apigee-runtime-myorg-env1-abc12-1170-ghi56   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]

如果任何 Pod 显示空的 hostAliases 值,则消息处理器 ApigeeDeployment 未完全获取更新后的 Pod 规范。通过删除当前消息处理器 Pod,强制执行新的分阶段 Canary 版本;ApigeeDeployment 控制器将根据当前规范(现在包含 hostAliases 条目)重新呈现它们:

kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime

ApigeeDeployment 控制器会在一分钟内重新创建 Pod。请注意,kubectl rollout restart deploy(普通 Kubernetes 命令)不适用于消息处理器,因为消息处理器是作为 ApigeeDeployment 自定义资源(而不是 Deployment)部署的。

安装完毕

上述三项检查共同确认您的 MCP 数据平面正在运行且可通过 MP 寻址:

  • 每个 MCP pod 都是 2/2 Running。如果未加载 Operator 颁发的 TLS 证书,并且边车尚未加载其初始 MCP 配置,则 MCP 数据平面容器在端口 15021 上的 Kubernetes 就绪性探测会失败,因此 Ready Pod 具有这两个前提条件。
  • 每个 MP pod 的规范都包含 hostAliases 条目,用于将 mcp.apigee.internal 和 ORG_NAME.mcp.apigee.internal 固定到 MCP Service ClusterIP。因此,MP pod 可以将 MCP 代理目标端点解析为集群内 MCP 数据平面。
  • MP Pod 通过注入的 hostAliases 条目将 mcp.apigee.internal 解析为 MCP Service ClusterIP。

在部署第一个 MCP Discovery Proxy 后,您需要验证端到端 MCP 工具流量(通过 Apigee 入站流量进行的实际 MCP initialize 或 tools/list 调用),作为共享 MCP 快速入门的一部分。

如果上述三项检查中有任何一项失败,请先参阅排查 MCP 部署问题,然后再继续执行快速入门。

第 6 步:在其余集群上启用 MCP

针对给定主机名的 MCP 请求可以路由到为相应 Apigee 环境组提供服务的任何集群。如果在同一环境组中的某些集群上启用了 MCP,而其他集群上未启用 MCP,则路由到未启用 MCP 的集群的 MCP 请求会失败(通常作为 503 Service Unavailable 返回给客户端)。

在为同一环境组提供服务的每个集群上统一启用 MCP。 对于每个额外的集群,重复执行第 1、3、4 和 5 步。您无需重复第 2 步(授予观察者身份访问权限):该授权范围限定为 Apigee 组织,并应用于同一组织中的所有集群。

验证无状态 MCP 协议(1.17.4 版及更高版本)

Apigee Hybrid 1.17.4 及更高版本默认提供无状态 MCP 协议(版本 2026-07-28)。如需确认您的安装是否提供该协议,请调用仅存在于无状态协议中的 server/discover 方法。此检查需要已部署的 MCP Discovery Proxy,因此请在完成 MCP 快速入门后运行。在仅提供有状态 MCP 协议版本的版本 1.17.0 到 1.17.3 中,请跳过此检查。

请求会发送到 Apigee 环境组中的主机名,因此为该环境组提供服务的任何集群都可以响应该请求。因此,该检查会验证环境组,而不是特定集群,并且您只需针对每个环境组运行一次。如需确认每个集群是否正常运行,请使用第 5 步:验证安装中的每个集群检查。

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "server/discover",
        "params": {
          "_meta": {
            "io.modelcontextprotocol/protocolVersion": "2026-07-28",
            "io.modelcontextprotocol/clientCapabilities": {}
          }
        }
      }'

替换以下内容:

  • MCP_ENDPOINT_URL:MCP 端点的主机名,该主机名在 Apigee 环境组中注册,并由 Apigee 入站流量网关提供服务。例如 api.example.com。
  • TOKEN:OAuth 2.0 访问令牌,如果您的 MCP 代理使用 OAuthV2 政策验证令牌,则需要此令牌。如果代理改用 VerifyAPIKey 政策,请将 -H "Authorization: Bearer TOKEN" 行替换为该政策读取的标头或查询参数中的 API 密钥。如果代理接受未经身份验证的请求,请移除该行。

如果响应为 HTTP 200 且 result.supportedVersions 数组包含 2026-07-28,则环境组会提供无状态 MCP 协议。成功的响应类似于以下内容:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "SERVICE_NAME",
        "version": "1.0.0"
      }
    },
    "cacheScope": "public",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "resultType": "complete",
    "supportedVersions": [
      "2026-07-28",
      "2025-11-25",
      "2025-06-18",
      "2025-03-26",
      "2024-11-05"
    ],
    "ttlMs": 0
  }
}

在响应中,SERVICE_NAME 是回答问题的 MCP 服务的名称。cacheScope 和 ttlMs 字段是缓存提示;"ttlMs": 0 是默认值,不表示错误。

如果响应是错误,请使用它来查找原因:

  • HTTP 400(具有 error.code -32602 和 error.message Unsupported protocol version):集群运行 Apigee Hybrid 版本 1.17.0 到 1.17.3,这些版本不提供无状态协议。升级到 1.17.4 版或更高版本。
  • 任何其他错误,例如 HTTP 401 或 403(身份验证)、HTTP 404(此环境组中的 /mcp 未部署 MCP 代理)、HTTP 503(MCP 数据平面运行状况不佳)或来自格式错误的请求的其他 error.code 值:原因不是 Apigee Hybrid 版本。请参阅排查 MCP 部署问题。

如需查看无状态请求要求和错误的完整列表,请参阅支持的 MCP 协议版本。

回滚

如需在集群上停用 MCP,请在 overrides.yaml 中设置 enableMcpServer: false(或完全移除该字段),然后升级 apigee-org 图表:

helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \
  --namespace APIGEE_NAMESPACE --atomic -f overrides.yaml

enableMcpServer 字段仅由 apigee-org 图表使用,因此在停用期间无需升级 Operator 图表。Apigee Operator(未更改)从 ApigeeOrganization 自定义资源中获取配置更改,删除 MCP 资源,并从消息处理器 Pod 规范中移除 hostAliases 条目,这会触发 apigee-runtime ApigeeDeployment 的发布。在已获批准的维护窗口中回滚。

回滚后,您部署到 Apigee 环境的 MCP Discovery 代理仍会保留在 Apigee 控制平面中,但该环境组中的任何集群都不会处理 MCP 流量。取消部署 MCP Discovery Proxy 以完全停用该功能,或让其保持部署状态,以便日后在集群上重新启用 MCP。

在 MCP 数据平面和入站流量网关之间配置 mTLS

MCP 工具调用会离开 MCP 数据平面,并通过 Apigee 入站网关重新进入集群,使用与该环境组的任何其他 API 调用相同的主机别名和相同的 virtualhosts[] 条目。默认情况下,MCP 数据平面通过单向 TLS 连接到入站网关:连接已加密,但 MCP 数据平面不提供客户端证书,也不验证入站网关的证书。

从 Apigee Hybrid 1.17.4 开始,您可以使用 virtualhosts[].mcpMtls 块在每个环境组的此连接上启用双向 TLS (mTLS)。启用 mTLS 后:

  • MCP 数据平面会提供您颁发的客户端证书,因此入站流量网关会像对该环境组的任何其他 mTLS 客户端进行身份验证一样,对 MCP 数据平面进行身份验证。
  • MCP 数据平面会验证入站网关的证书是否链接到您指定的证书授权机构 (CA),以及是否涵盖所调用的主机别名。这两项检查默认处于启用状态,可以按环境组停用。

您一次只能为一个环境组配置 mTLS。没有 mcpMtls 的环境组会继续使用单向 TLS,包括由同一入站流量网关提供服务的环境组,因此您可以逐步迁移。客户端证书和信任 CA 也是按环境组划分的:没有集群范围的 MCP 客户端证书,同一入站网关上的两个环境组可以提供由不同 CA 颁发的不同客户端证书。

mcpMtls 字段有意重复使用上一级 Ingress TLS 字段的名称,但角色相反,因为在此连接上,MCP 数据平面是客户端,而 Ingress 网关是服务器:

字段 低于 virtualhosts[].mcpMtls 直接位于 virtualhosts[] 下
sslCertPath,sslKeyPath MCP 数据平面向入站网关提供的客户端证书和密钥。 必须具有 clientAuth 扩展密钥用途。 入站流量网关自己的服务器证书和密钥。
sslSecret 包含该客户端证书和密钥(密钥 cert、key)的 Secret。 包含入站流量网关的服务器证书和密钥的 Secret。
caCertPath,或附加了 -cacert 的 sslSecret 名称 MCP 数据平面信任的 CA,用于入站网关的服务器证书。 入站网关信任的 CA,用于传入客户端证书,包括 MCP 数据平面的证书。

准备工作

  • 集群运行 Apigee Hybrid 1.17.4 或更高版本,apigee-operator、apigee-org 和 apigee-virtualhost 图表均已升级到该版本,并且已通过完成从第 1 步:修改 overrides.yaml 开始的步骤启用了 MCP。确保升级包含安装更新后的 Apigee CRD 步骤 (kubectl apply -k apigee-operator/etc/crds/default/ ...);仅升级 Operator Helm Chart 不会更新 CRD。在早于 1.17.4 的 CRD 上,API 服务器会静默地从 ApigeeRouteConfig 资源中丢弃 mcpMtls 块,因此该块没有任何效果,并且集群无法报告验证中描述的证书问题。
  • MCP 数据平面的客户端证书和私钥,由入站网关为此环境组信任的 CA 颁发:virtualhosts[].caCertPath 中的 CA 或同一 virtualhosts[] 条目的 INGRESS_SECRET_NAME-cacert Secret。如果证书具有扩展密钥用途扩展程序,则必须包含 clientAuth;MCP 数据平面会拒绝扩展密钥用途省略该扩展程序的证书(接受没有扩展密钥用途扩展程序的证书)。使用私有 CA:公共 CA 通常不会颁发具有 clientAuth 扩展密钥用途的证书。
  • 此环境组的为入站网关自己的 TLS 证书签名的 CA 证书(virtualhosts[].sslCertPath 或 INGRESS_SECRET_NAME 中的证书)。MCP 数据平面会根据此 CA 验证入站网关。仅当您设置 disableChainValidation: true 时,才省略此参数。
  • 除非您设置 disableSanValidation: true,否则入站流量网关的证书必须在其主题备用名称中列出环境组的主机别名。通常会,因为外部客户端会执行相同的检查。

请从以下两种方式中选择一种来提供证书。它们反映了入站流量网关自身 mTLS 配置的两个选项。

方法 1:证书文件

将包含文件路径的 mcpMtls 添加到环境组的 virtualhosts[] 条目中。Helm 只能读取 chart 目录中的文件,因此这些文件必须位于 $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/ 下(例如,位于其 certs/ 目录中,紧邻入站流量证书),并且路径相对于该目录,就像现有的 sslCertPath、sslKeyPath 和 caCertPath 字段一样。请参阅创建 TLS 证书。

virtualhosts:
- name: ENV_GROUP_NAME
  tlsMode: MUTUAL
  caCertPath: certs/INGRESS_CA_FILE        # CA the ingress gateway trusts for client certificates
  sslCertPath: certs/INGRESS_CERT_FILE
  sslKeyPath: certs/INGRESS_KEY_FILE
  mcpMtls:
    sslCertPath: certs/MCP_CLIENT_CERT_FILE  # client certificate the MCP data plane presents
    sslKeyPath: certs/MCP_CLIENT_KEY_FILE
    caCertPath: certs/MCP_TRUST_CA_FILE      # CA that signed INGRESS_CERT_FILE

方法 2:Kubernetes Secret

  1. 创建包含客户端证书和密钥的 Secret。数据键必须为 cert 和 key:
    kubectl create secret generic MCP_CLIENT_SECRET_NAME -n APIGEE_NAMESPACE \
      --from-file=cert=MCP_CLIENT_CERT_FILE \
      --from-file=key=MCP_CLIENT_KEY_FILE
  2. 创建第二个 Secret,其中包含为入站流量网关证书签名的 CA。 其名称必须是第一个 Secret 的名称,后跟 -cacert,数据键必须是 cacert。仅当您设置了 disableChainValidation: true 时,才跳过此步骤:
    kubectl create secret generic MCP_CLIENT_SECRET_NAME-cacert -n APIGEE_NAMESPACE \
      --from-file=cacert=MCP_TRUST_CA_FILE
  3. 从环境组的 virtualhosts[] 条目中引用第一个 Secret:
    virtualhosts:
    - name: ENV_GROUP_NAME
      tlsMode: MUTUAL
      sslSecret: INGRESS_SECRET_NAME
      mcpMtls:
        sslSecret: MCP_CLIENT_SECRET_NAME

请勿在一个 mcpMtls 代码块中混用这两个选项。helm upgrade 会快速失败,并提供诊断信息,指出常见错误配置的条目,包括:sslSecret 与路径字段组合;sslCertPath 没有 sslKeyPath,或 sslKeyPath 没有 sslCertPath;未提供任何形式;或引用的 Secret 缺失或缺少预期的数据键。其他不一致情况(例如,caCertPath 与 disableChainValidation: true 一起设置)在 virtualhosts[].mcpMtls 属性参考文档中进行了介绍。

应用更改

升级环境组的 apigee-virtualhost 版本:

helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f overrides.yaml

没有 MCP pod 重启,也没有其他环境组受到影响。MCP 数据平面会在下次定期刷新时(通常在几分钟内)获取新配置。如果您在同一升级中将条目从 tlsMode: SIMPLE 切换到 MUTUAL,则在此期间,对该环境组的 MCP 工具调用可能会失败,因为入站网关会在 MCP 数据平面开始提供客户端证书之前开始要求提供客户端证书。在相应环境群组的维护窗口中进行更改。

验证

  1. 确认配置已到达环境组的 MCP 数据平面的路由资源。输出必须显示 Secret 名称和您配置的两个验证标志(省略了未设置的标志):
    kubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \
      -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
    如果升级几分钟后 mcpMtls 列仍然为空,通常是因为集群中的 Apigee CRD 早于 1.17.4 且丢弃了该字段:应用更新后的 CRD(请参阅准备工作),然后重新运行 apigee-virtualhost 升级。在极少数情况下,apigee-org 图表(提供观察器映像)尚未升级到 1.17.4。
  2. 确认 MCP 数据平面已接受证书。每当 Secret 缺失、无法读取或包含不可用的材料时,边车都会记录 error 行,并保留该环境组的先前配置。启用后,应该没有任何内容:
    kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \
      | grep MCP_MTLS_
    搜索整个日志,而不是最近的窗口:当边车首次看到有故障的 Secret 时,系统会报告该 Secret,而不是在每次刷新时都报告。
  3. 检查报告为 ApigeeIssue 资源的证书问题(请参阅 MCP mTLS 问题):
    kubectl -n APIGEE_NAMESPACE get apigeeissues -l 'ais-reason in (AIS_MCP_MTLS_CLIENT_CERT_INVALID,AIS_MCP_MTLS_CLIENT_CERT_EXPIRY,AIS_MCP_MTLS_CA_CERT_INVALID,AIS_MCP_MTLS_CA_CERT_EXPIRY)'
  4. 通过环境组中已部署的 MCP Discovery 代理发送 MCP 请求,如 MCP 快速入门中所述。成功的工具调用可确认完整路径,包括与入站流量网关的 mTLS 握手。

轮替证书

  • 方法 2(Secret):就地更新 Secret,例如使用 kubectl create secret generic ... --dry-run=client -o yaml | kubectl apply -f -。 MCP 数据平面会监视这两个 Secret,并在下次刷新时加载新材料。 无需重启 Pod,也无需 helm upgrade,并且进行中的 MCP 调用不会中断。保持数据键 cert、key 和 cacert 不变。
  • 方式 1(文件):替换文件,然后运行应用更改中的同一 helm upgrade。该图表会更新其管理的 Secret,MCP 数据平面会按照选项 2 中所述获取这些 Secret。

在客户端证书或信任 CA 过期前 14 天,集群会发出严重级别为 WARNING 的 ApigeeIssue;过期后,严重级别为 ERROR。在您替换过期证书之前,系统仍会显示该证书;然后,入站流量网关会拒绝握手。

为环境组停用 mTLS

移除 mcpMtls 代码块,在同一修改中将条目的 tlsMode 重新设置为 SIMPLE(或移除 tlsMode),然后运行相同的 helm upgrade。MCP 数据平面会在下次刷新时将该环境组恢复为单向 TLS,并移除它为该组写入的证书材料。 您为选项 2 手动创建的 Secret 不会被删除;当不再需要这些 Secret 时,请自行将其移除。

证书不可用时的行为

如果 MCP 数据平面无法读取或无法使用为环境组配置的证书(缺少 Secret、缺少数据键、证书缺少 clientAuth,或 CA Secret 不是 CA),它会记录 error 行,继续使用上次成功加载的证书为该环境组提供服务,并在后续刷新时重试。如果从未为该组加载过证书,则对该组的 MCP 工具调用会失败(客户端通常会收到 503 Service Unavailable),而所有其他环境组会继续提供服务。修复 Secret 或 overrides.yaml 条目;无需重启。如需了解具体消息,请参阅排查 MCP 部署问题。

参考:overrides.yaml 中的 MCP 字段

下表列出了控制版本 1.17.0 中 MCP 行为的每个 Apigee Hybrid overrides.yaml 字段。只有 enableMcpServer 是必需的;所有其他字段都有适合大多数安装的安全默认值。

字段定义与 Apigee Hybrid 1.17.0 的 apigee-org Helm 图表默认值一致。从 MCP 数据平面到入站流量网关的连接的 mTLS 设置不在此表中:它们位于 apigee-virtualhost 图表(1.17.4 及更高版本)中的 virtualhosts[].mcpMtls 下,每个环境组都有一个。

字段 类型 默认 建议的调优
enableMcpServer 布尔值 false 必需。设置为 true 可在此集群上启用 MCP。切换此字段会触发消息处理器的分阶段 Canary 版本。请仅在维护窗口中切换,并等待发布完成后再继续。
mcpServer.replicaCountMin 整数 2 对于高可用性,请保持 2。仅当您有高 MCP 流量基准时才增加;HPA 会在 CPU 压力下自动扩容。信号:HPA 持续处于 replicaCountMax,且 CPU 利用率高于目标值。
mcpServer.replicaCountMax 整数 10 如果您观察到 HPA 在高峰期达到 10 的上限,请增加此值。信号:kubectl top pods -l app=apigee-mcp-server 显示了在高峰期接近其 CPU 限制的所有 Pod。如果未安装 metrics-server,请使用 kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server 并检查 REPLICAS 列是否达到 MAXPODS 上限。
mcpServer.targetCPUUtilizationPercentage 整数 70 对于延迟敏感型工作负载,请将该值降低到 50–60(更早扩缩)。在对费用敏感的集群中,将此值提高到 80–85,以减少副本数量。信号:p95 请求延迟时间与每个 Pod 的 CPU 相关。
mcpServer.resources.requests 资源列表 cpu: 500m, memory: 512Mi 如果 Pod 在稳定状态下频繁发生 OOMKilled 或 CPU 节流,请增加请求。信号:kubectl describe pod 显示 OOMKilled 或受限条件。
mcpServer.resources.limits 资源列表 cpu: 2000m, memory: 1Gi 当 p95 延迟时间较高但总体 QPS 较低(请求数量少、开销大)时,请先提高 CPU 限制,然后再增加副本数量。仅当您看到 OOMKill 时,才提高内存上限。
mcpServer.sidecar.resources.requests 资源列表 cpu: 200m, memory: 128Mi 很少需要调优。边车会定期编写和写入配置包;稳态 CPU 占用率极低。
mcpServer.sidecar.resources.limits 资源列表 cpu: 500m, memory: 512Mi 很少需要调优。仅当您在单个 Discovery Proxy 中部署了异常大量的 MCP 工具时,才需要增加内存。
mcpServer.terminationGracePeriodSeconds 整数 30 很少需要调优。如果长时间运行的正在进行的 MCP 请求在 Pod 排空期间需要更多时间才能完成,请增加此值。
mcpServer.annotations 地图 {} 如果集群需要,请添加额外的 Pod 注解。
mcpServer.serviceAccountPath 字符串 unset 除非您需要按组件进行身份分离,否则请勿设置。如果未设置,MCP 会使用 watcher.serviceAccountPath。MCP 不使用 envs[].serviceAccountPaths.runtime。apigee-watcher 身份已拥有 MCP 边车所需的权限。如果您替换此字段,请指定 Google Cloud 服务账号密钥 JSON 文件的路径。它与 mcpServer.gsa 相互排斥。

如果未启用 Workload Identity,并且您未设置 mcpServer.serviceAccountRef 或 serviceAccountSecretProviderClass,则必须设置 mcpServer.serviceAccountPath 或 watcher.serviceAccountPath。如果您未设置任何一个,helm upgrade 将失败并显示错误 mcpServer.serviceAccountPath or watcher.serviceAccountPath is required!!。

尽可能首选 Workload Identity (GKE) 或工作负载身份联合 (AKS/EKS)。基于文件的服务账号密钥必须轮替、安全存储、分发到每个集群,并且是支持工件泄露的最常见来源(请参阅支持请求)。
mcpServer.gsa 字符串 unset 除非您需要按组件进行身份分离,否则请勿设置。如果未设置,MCP 会回退到 watcher.gsa,然后回退到 gcp.workloadIdentity.gsa。apigee-watcher 身份已拥有 MCP 边车所需的权限,因此建议重复使用该身份。仅当您的组织出于审核原因需要为 MCP 边车提供不同的身份时,才使用专用 Google Cloud 服务账号电子邮件地址进行替换。
mcpServer.serviceAccountRef 字符串 unset 高级。Apigee 命名空间中现有 Kubernetes Secret 的名称,该 Secret 包含 MCP 边车的 Google Cloud 服务账号密钥。仅当您在 Apigee Helm 图表之外管理服务账号密钥 Secret 时,才使用此选项。与 mcpServer.serviceAccountPath 和 mcpServer.gsa 相互排斥。

MCP 不使用 watcher.serviceAccountRef。如果您的基本安装将 apigee-watcher 密钥存储在具有 watcher.serviceAccountRef 的 Kubernetes Secret 中,请将此属性设置为相同的 Secret 名称。
mcpServer.podDisruptionBudget 地图 unset MCP Pod 的可选 PodDisruptionBudget。接受 minAvailable 或 maxUnavailable(整数或百分比字符串)。请设置其中一个,不要同时设置。除非您的集群具有需要明确预算的严格自愿中断政策,否则请勿设置。
mcpServer.tolerations list 未设置(回退到顶级 tolerations) MCP Pod 的标准 Kubernetes 容忍。仅在 MCP pod 必须容忍其他 Apigee 组件不容忍的污点时设置。
mcpServer.image.pullPolicy 字符串 IfNotPresent MCP 服务器容器的映像拉取政策。很少更改。
mcpServer.sidecar.image.pullPolicy 字符串 IfNotPresent MCP 边车容器的映像拉取政策。很少更改。

估算 MCP 工具容量

Apigee Hybrid 不会强制规定每个组织的 MCP 工具数量上限。相反,工具容量受限于在部署或请求时强制执行的四个硬性大小限制。能否容纳特定数量的工具取决于每个工具的大小,而工具的大小则取决于定义该工具的 OpenAPI 规范。

常规电池容量

对于大多数 OpenAPI 规范(包含各种参数数量、请求正文大小和说明长度的工具,其中大多数工具属于中小型),在默认的 tools/list 响应大小限制下,每个组织通常可以容纳 10,000 个 MCP 工具。

实际容量因 OpenAPI 规范的具体形式而异。如果组织的规范主要由具有许多参数、大型请求正文或长说明的工具组成,则在达到以下四个硬性限制之一之前,可容纳的工具数量会按比例减少。如需验证特定规范的容量,请按照下文中的估算规范的容量进行操作。

硬性限额

Apigee Hybrid 1.17.0 版中存在四种大小限制。最低的适用限额是约束条件;提高一个限额不会提高其他限额。

限制 值 范围 故障模式
OpenAPI 规范文件大小 3 MiB 每个 .yaml 文件 400(在代理验证时)
MCP 代理软件包大小(解压缩后) 50 MiB 每个 MCP 发现代理 400(在代理验证时)
tools/list 响应大小 10 MiB(默认) 每个主机名 502 - TooBigBody
每个环境组的主机名数量 100 每个环境组 400(在环境组更新时)

每个工具的大小由什么决定

每个工具的大小几乎完全由工具的 inputSchema 组成,该 派生自 OpenAPI 规范中操作的 parameters 和 requestBody。 其中最重要的三个属性是:

  • 参数数量。在 tools/list 响应中,每个参数条目会使工具的大小增加大约 100 字节。
  • 请求正文属性的数量。每个请求正文属性大约会增加 100 字节。因此,具有请求正文的操作(通常为 POST 和 PUT)比没有请求正文的操作(通常为 GET 和 DELETE)要大得多。
  • 说明长度。操作说明几乎会逐字复制到工具中,因此较长的说明会直接增加工具的大小。

响应 schema 不计入大小预算。只有 parameters 和 requestBody 才能访问 MCP 配置。因此,仅根据 OpenAPI 文件大小来估算容量往往会高估成本,因为大多数实际 OpenAPI 规范都包含不影响工具大小的响应架构定义。

估算规格所需的容量

如需估算 OpenAPI 规范的工具容量,最可靠的方法是测量具有代表性的子集:

  1. 部署一个 MCP 发现代理,该代理引用您计划发布的工具中的一小部分代表性工具(例如,50 到 100 个工具,这些工具反映了完整规范中的参数数量、请求正文大小和说明长度的组合)。
  2. 针对已部署的代理调用 tools/list,并记录响应大小(以字节为单位)和返回的工具数量。
  3. 用响应大小除以工具数量,即可得出规范中每个工具的平均大小。
  4. 将适用的 tools/list 响应大小上限(默认为 10 MiB)除以该平均值,即可估算一个主机名可容纳的此类规范工具的数量上限。

提升容量

有两种机制可将工具容量提高到默认值以上:

  • 跨主机名对工具进行分片。tools/list 响应上限是按主机名计算的。在同一环境组中的多个主机名之间拆分工具会使每个主机名的余量成倍增加(受每个环境组 100 个主机名的限制)。分片不会提高每个代理软件包的限制;50 MiB 的软件包上限仍然适用于单个 MCP 发现代理上的所有主机名。
  • 提高 tools/list 响应大小限制。默认限制为每个主机名 10 MiB。您最多可以将其提高到 30 MiB。至少,这涉及在 overrides.yaml 中设置 envs.components.runtime.resources.limits.memory、envs.components.runtime.resources.requests.memory 和 envs.components.runtime.cwcAppend.bin_setenv_max_mem,然后在 apigee-org 图表上运行 helm upgrade。如需了解完整过程,包括每个环境与整个安装变体、消息处理器堆大小调整指南以及完整的 overrides.yaml 示例,请参阅在 Apigee Hybrid 中配置大型消息载荷支持。提高响应限制不会影响 50 MiB 的 MCP 代理软件包大小限制;如果您的容量受该限制约束,则此更改不会有所帮助。

安全

信任边界

MCP 数据平面在您自己的 Kubernetes 集群内运行。Google 在运行时无法访问数据平面。Apigee 控制平面会为您提供从 OpenAPI 规范派生的 MCP 配置;它不会观察 MCP 请求流量。静态配置数据存储在 Apigee 管理的 Cloud Storage 存储桶中,该存储桶的作用域限定为 Apigee 租户项目,由 MCP 边车使用其环境 Google Cloud 服务账号提取。

Apigee Operator 会在 Apigee 命名空间 (APIGEE_NAMESPACE) 中为 MCP 数据平面 ServiceAccount 预配 MCP 范围的 Kubernetes Role 和 RoleBinding。该角色授予只读权限:

  • 核心 API 组中的 get、list、watch(在 services 上)。
  • get、list、apigeeroutes 上的 watch(在 apigee.cloud.google.com API 组中)。
  • 在 1.17.4 及更高版本中:核心 API 组中 secrets 上的 get、list、watch。MCP 数据平面使用此权限来读取客户端证书和由 virtualhosts[].mcpMtls 命名的信任 CA Secret,并检测其轮替(请参阅在 MCP 数据平面和入站网关之间配置 mTLS)。该授权是只读的,但涵盖 Apigee 命名空间中的每个 Secret:Kubernetes RBAC 无法将 list 和 watch 限制为命名的 Secret。无论是否有任何环境组配置了 mcpMtls,它都会存在。

该角色不授予任何写入动词,也不授予对 ConfigMaps 或 Pod 状态的访问权限。 您的审计者可以使用以下命令直接从集群中验证确切的规则:

APIGEE_ORG_CR=$(kubectl get apigeeorganization -n APIGEE_NAMESPACE \
  -o jsonpath='{.items[0].metadata.name}')
kubectl get role,rolebinding -n APIGEE_NAMESPACE \
  --field-selector metadata.name=apigee-mcp-server-$APIGEE_ORG_CR -o yaml

apigee-mcp-server-APIGEE_ORG_CR Role 和 RoleBinding 是 MCP 范围的 RBAC 资源;其名称包含 ApigeeOrganization 自定义资源的完整名称(派生自您的 Apigee 组织名称和短哈希)。它们在资源级别不带有 app=apigee-mcp-server 标签(只有 Pod 带有),因此基于标签的查找不会返回任何结果。如果上述 field-selector 命令未返回任何内容,请使用以下命令列出命名空间中与 MCP 相关的所有 RBAC 资源:

kubectl get role,rolebinding -n APIGEE_NAMESPACE | grep apigee-mcp-server

消息处理器与 MCP 数据平面之间的 TLS

消息处理器 Pod 会拨打 https://mcp.apigee.internal/ 或 https://ORG_NAME.mcp.apigee.internal/ 处的 MCP 数据平面。这些主机名通过注入的 hostAliases 条目解析为 MCP Service ClusterIP。MCP 数据平面容器会提供由 Apigee-operator 预配的颁发者(名为 apigee-ca-issuer 的 ClusterIssuer)签名的 TLS 证书。该证书的主体备用名称包含这两个主机名。

MCP 数据平面与入站流量网关之间的 TLS

MCP 数据平面使用环境组的主机别名,将每个工具调用转发到端口 443 上的 Apigee 入站流量网关。默认情况下,此连接是单向 TLS,MCP 数据平面不会验证入站网关的证书。在 1.17.4 及更高版本中,您可以按环境组要求对此连接进行双向身份验证;请参阅在 MCP 数据平面和入站流量网关之间配置 mTLS。

限制对 MCP 服务的入站访问

在 Apigee Hybrid 1.17.0 中,MCP 数据平面不会独立对其调用方进行身份验证。它信任到达它的请求已经过在消息处理器中运行的 Apigee MCP 代理的身份验证。MCP 服务的唯一预期调用方是消息处理器。任何其他可通过 TCP 443 访问 MCP 服务 ClusterIP 的集群内工作负载都可以在不进行身份验证检查的情况下调用 MCP 工具。

使用平台的集群入站流量政策引擎(Kubernetes NetworkPolicy、Cilium、Calico、Istio AuthorizationPolicy 或等效引擎),将对 MCP Pod 的入站访问权限限制为仅限消息处理器 Pod。限制:

  • 仅允许从同一命名空间中带有标签 app=apigee-runtime 的 Pod 通过 TCP 443 访问命名空间 APIGEE_NAMESPACE 中带有标签 app=apigee-mcp-server 的 Pod。
  • 拒绝所有其他通过 TCP 443 流向带有 app=apigee-mcp-server 标签的 Pod 的入站流量。
  • 拒绝所有通过 TCP 15021 流向带有 app=apigee-mcp-server 标签的 Pod 的集群内入站流量。端口 15021 提供 kubelet 用于就绪性探测的未经身份验证的纯 HTTP /healthz/ready 端点;kubelet 直接在 Pod IP 上访问该端点,因此其他集群内工作负载不应访问 15021 上的 MCP Pod。

在完成 MCP 快速入门并在非开发环境中部署第一个 MCP Discovery 代理之前,请先应用此限制。

配置新鲜度协定

当 MCP 边车成功完成配置拉取后,MCP 数据平面容器会加载提取的软件包,并继续提供该软件包,直到下一次成功拉取。如果后续拉取失败(Apigee 控制平面无法访问、Cloud Storage 无法访问、观察者服务账号的 IAM 权限被移除,或拉取流水线的任何其他阶段出错),边车会无限期地继续提供最后一个已知良好的软件包。1.17.0 中没有内置的过时上限:Pod 保持 Ready 状态,MCP 工具流量继续针对过时的软件包提供服务。配置已停止刷新的信号是 ERROR 级别的边车日志行,其中包含 consecutive_failures 计数器(请参阅排查 MCP 部署问题,了解边车在每个故障阶段发出的特定消息)。

对于受监管的生产环境,请参阅有关此计数器重复递增的页面。最低可行提醒:当任何 MCP 边车容器发出 ERROR 级日志行,且 consecutive_failures 达到您根据过时容忍度设置的阈值时,发出提醒。值上升表示边车已停止刷新配置;与此同时,边车会继续提供上次成功的软件包。

如果边车已停止刷新配置,请从边车日志中调查故障模式;请参阅排查 MCP 部署问题。退回 MCP pod 无法解决底层提取问题,因为新创建的 pod 会命中相同的提取路径。

出站网络要求

MCP 边车(每个 MCP pod 内的配置容器)需要对 TCP 443 上的以下端点进行出站网络访问。根据您的 Apigee 组织是否使用数据驻留,选择相应的标签页;所需的端点会有所不同。

无数据驻留

端点 用于:
apigee.googleapis.com 每次刷新配置时,从 Apigee 控制平面检索组织的当前 MCP 配置引用。
storage.googleapis.com 从 Google Cloud Storage 下载组织的 MCP 配置。

数据驻留

如果您的 Apigee 组织使用数据驻留,则 MCP Sidecar 会访问您的区域级 Apigee 控制平面端点(即其他 Apigee Hybrid 组件使用的端点,通过 overrides.yaml 中的 contractProvider 图表值进行配置)。将 CONTROL_PLANE_LOCATION 替换为您组织的控制平面位置(例如 us、eu)。

端点 用于:
CONTROL_PLANE_LOCATION-apigee.googleapis.com 每次刷新配置时,从区域级 Apigee 控制平面端点检索组织的当前 MCP 配置引用。
storage.googleapis.com 从 Google Cloud Storage 下载组织的 MCP 配置。该存储桶位于您组织所在的区域;Cloud Storage 会自动路由到该存储桶。

此外,边车必须能够为 Pod 运行所用的环境凭据(通过 Workload Identity 或基于文件的服务账号密钥)获取 Google Cloud 访问令牌。具体的令牌交换端点取决于您的身份验证路径,并且与集群中其他 Apigee Hybrid 组件已使用的端点相同。如果从该命名空间到 Google Cloud API 的现有 Apigee Hybrid 流量成功,则 MCP 边车的令牌交换也会成功。

此外,边车需要对 Kubernetes API 服务器进行集群内访问(通过标准集群内服务地址),以发布其活跃性和就绪状态。此流量绝不会离开您的集群。

问题排查

如需查看完整的诊断核对清单,请参阅排查 MCP 部署问题,其中包含适用于 Apigee Hybrid 的集群端诊断核对清单。

常见安装失败问题

症状 原因和解决方法
helm upgrade 完成,但未显示任何 MCP 资源。 组织图表在 Operator 图表之前升级。先运行 helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/,然后重新运行 helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/。
MCP pod 卡在 ContainerCreating 或 1/2 Ready 状态。 两个常见原因:尚未颁发 MCP 的 cert-manager Certificate,或者容器映像拉取失败。在受影响的 Pod 上运行 kubectl describe pod,了解确切原因。
Sidecar (apigee-mcp-server-config) 日志会在每次轮询时报告 no MCP config from CP yet; skipping tick, pod stays Ready via seed。 如果尚未为您的组织部署 MCP 发现代理,则预计会处于稳定状态。Apigee 控制平面返回一个空的配置引用,并且 MCP 数据平面仅在端口 15021 上加载了 Kubernetes 就绪性监听器;MCP 请求端口 8443 还没有监听器,对 https://mcp.apigee.internal/mcp 的请求会收到连接被拒绝。如需转换为服务状态,请按照 MCP 快速入门将 MCP Discovery Proxy 部署到此集群所服务的环境组中的环境。
Sidecar 日志会报告 CP fetch failed,其中包含嵌入式 HTTP 403 或 PermissionDenied。 Apigee 观察器 Google Cloud 服务账号在 Apigee 租户项目中失去了 roles/apigee.runtimeAgent 角色(该角色授予边车所需的 apigee.runtimeconfigs.get 权限)。基础 Apigee Hybrid 安装会自动授予此角色;如果此角色已被 IAM 自动化扫描移除,请在 apigee-watcher Google Cloud 服务账号中重新应用此角色。
Sidecar 日志报告 CP fetch failed 错误,并显示 context deadline exceeded、DNS 错误或 TLS 错误。 边车无法从集群内部访问 apigee.googleapis.com 或 storage.googleapis.com。根据上述出站网络要求中列出的三个端点验证出站流量。
消息处理器 Pod 在 helm upgrade 后未重启。 验证每个 MP pod 上是否存在 hostAliases 条目: kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'。 如果任何 Pod 显示为空,请通过删除 Pod (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime) 强制进行全新渲染。ApigeeDeployment 控制器将根据当前规范(包括 hostAliases 条目)重新创建该 Pod。请勿使用 kubectl rollout restart deploy;它不适用于 ApigeeDeployment。
在 MCP 工具流量开始流经快速入门后,MP Pod 日志会显示拨打 https://mcp.apigee.internal/ 或 https://ORG_NAME.mcp.apigee.internal/ 时出现 TLS 握手错误。 MCP 数据平面容器提供的证书的主体备用名称 (SAN) 不包含 MP 拨号的主机名。验证证书:kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server,然后kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml。证书的 dnsNames 必须同时包含 mcp.apigee.internal 和小写的 ORG_NAME.mcp.apigee.internal。如果未显示,请删除 MCP Certificate 资源,并让 cert-manager 重新颁发。

后续步骤