配置 Model Context Protocol

本文档介绍了如何将 API Gateway 配置为远程 Model Context Protocol (MCP) 服务器。

准备工作

配置验证

上传 OpenAPI 规范后，API Gateway 会对 MCP 配置执行以下验证：

  • 位置：x-google-mcp-tool 扩展程序只能在单个操作级别指定。
  • HTTP 方法：只有 GET、POST、PUT、PATCH 和 DELETE 操作可以作为 MCP 工具公开。
  • 工具名称：工具名称必须与 [A-Za-z0-9_.-]{1,128} 匹配，并且在整个规范中是唯一的。
  • 说明：每个工具都必须解析为非空说明（取自操作的说明、摘要或替换值）。没有可解析说明的操作会被拒绝。
  • Security：如果您为 tools/list 配置了身份验证，则必须指定在 components.securitySchemes 下定义的一个安全方案。该方案可以是 JWT 方案或 API 密钥方案。如果您使用 JWT 方案，则还必须在规范的顶级 security 要求中为其命名。

身份验证模型

API Gateway 会根据调用的 MCP 方法应用不同的身份验证规则：

  • 协议生命周期：initialize 和 notifications/initialized 方法未经身份验证。
  • 工具调用 (tools/call)：重复使用在 OpenAPI 规范中为底层操作定义的身份验证政策。它会强制执行与直接调用 REST 端点相同的 API 密钥或 JWT 要求。
  • 工具发现 (tools/list)：默认情况下，此方法未经身份验证。不过，作为一项安全最佳实践，我们强烈建议您使用 tools-list.security 为此方法启用身份验证，以保护工具发现功能。您可以使用 JWT 或 API 密钥对 tools/list 进行身份验证。

MCP 配置步骤

请按照以下步骤将您的 API 公开为 MCP 工具：

1. 确定要公开的操作

查看您的 OpenAPI 规范，并确定哪些操作应可供 AI 智能体使用。

2. 更新 OpenAPI 规范

您可以为所有符合条件的操作全局启用 MCP，也可以按操作进行配置。

全球赋能

在文档级向 x-google-api-management 添加 mcp 字段，以全局启用 MCP：

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

全局启用后，所有符合条件的操作（基于 HTTP 方法和路径）都会作为 MCP 工具公开。默认情况下，工具名称是操作的 operationId，说明是操作的说明或摘要。

按操作配置

您可以使用 x-google-mcp-tool 替换全局设置或选择性地公开操作：

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

您也可以通过设置 x-google-mcp-tool: false，在全局启用时选择退出某项操作。

默认情况下，tools/list 方法（用于枚举可用工具）未经身份验证。作为安全性最佳实践，我们强烈建议您通过在 x-google-api-management.mcp 下配置 tools-list.security 来强制执行身份验证。您可以指定 JWT 方案或 API 密钥方案。

以下示例需要 JWT：

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

以下示例需要 API 密钥。客户端必须在 x-api-key HTTP 标头中发送密钥；tools/list 不会从查询参数中读取 API 密钥。如果请求中没有有效密钥，则会收到 JSON-RPC 错误，并且不会收到工具列表。如需了解如何创建 API 密钥，请参阅使用 API 密钥。

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

4. 创建并部署 API 配置

根据带注解的规范创建 API 配置，并使用标准流程将其部署到网关。如需了解详情，请参阅将 API 部署到网关。如需在日后更改工具，请参阅更新公开的 MCP 工具。

5. 验证 MCP 支持

部署后，您可以验证网关是否正在处理 MCP 请求。

握手

发送初始化请求以确定协议版本和功能：

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

确认握手

确认初始化。网关会返回 HTTP 202 Accepted：

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

探索各类工具

列出可用工具。如果您配置了 tools-list.security，请添加匹配的凭据，例如 JWT 的 Authorization: Bearer 标头或 API 密钥的 x-api-key 标头：

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

实参如何映射到 REST 请求

传递给工具的实参会根据 OpenAPI 规范映射到底层 REST 请求：

  • 路径和查询参数：成为 arguments 对象中的顶级属性，以其 OpenAPI 参数名称作为键。
  • 请求正文：嵌套在名为 body 的单个属性下。例如，如需创建资源，您需要传递 {"body": {"fieldName": "value"}}。
  • 标头：也会成为顶级属性。网关会在后端调用中将这些信息作为标准 HTTP 标头注入。

转码后的后端请求与对后端服务的直接 REST 请求没有区别。后端服务无法通过编程方式区分直接 REST 调用和从 MCP 转码的调用。

调用工具

调用特定工具。如果底层 REST 操作需要任何身份验证令牌，请确保您添加了这些令牌：

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

更新公开的 MCP 工具

API Gateway 中的 API 配置不可变，因此您无法更改现有 API 配置中的 API 定义。因此，对于每个已部署的 API 配置，tools/list 响应都是静态的。

如需添加、移除、重命名或更新公开的 MCP 工具或 tools/list 安全设置，请创建新的 API 配置并将其部署到网关：

  1. 更新 OpenAPI 3.x 规范，包括操作、operationId 值、摘要、参数以及 x-google-api-management.mcp 和 x-google-mcp-tool 扩展。

  2. 使用新的 API 配置 ID 创建新的 API 配置：

    gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID \
    --openapi-spec=API_DEFINITION \
    --project=PROJECT_ID \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    替换以下内容：

    • NEW_CONFIG_ID：更新后的 API 配置的新 ID
    • API_ID：API Gateway API 的 ID
    • API_DEFINITION：更新后的 OpenAPI 3.x 规范的路径
    • PROJECT_ID：您的 Google Cloud 项目 ID
    • SERVICE_ACCOUNT_EMAIL：用于为配置了身份验证的后端签署令牌的服务账号的邮箱。如果您的后端都不需要身份验证，请省略此标志。

    如需了解详情，请参阅创建 API 配置。

  3. 更新提供 API 的每个网关，以使用新的 API 配置：

    gcloud api-gateway gateways update GATEWAY_ID \
    --api=API_ID \
    --api-config=NEW_CONFIG_ID \
    --location=GCP_REGION \
    --project=PROJECT_ID

    替换以下内容：

    • GATEWAY_ID：要更新的网关的 ID
    • GCP_REGION：网关部署到的区域

    如需了解详情，请参阅更新网关。

  4. 调用 tools/list 以检查更新后的工具集。如需查看示例请求，请参阅发现工具。

  5. 在没有网关使用之前的 API 配置后，删除被取代的 API 配置：

    gcloud api-gateway api-configs delete OLD_CONFIG_ID \
    --api=API_ID \
    --project=PROJECT_ID

    将 OLD_CONFIG_ID 替换为被取代的 API 配置的 ID。当任何网关仍在使用某个 API 配置时，请勿删除该配置；如果您的新 API 配置重命名或移除了配额指标，则仍在使用旧 API 配置的网关可能会返回 HTTP 500 错误，直到更新为止（请参阅配额适用于整个 API）。如需了解详情，请参阅删除 API 配置。

更新 MCP 工具时，请注意以下发布和客户端行为：

  • 零停机时间发布：API Gateway 可在不停机的情况下更新网关。在新 API 配置传播期间，某些请求可能会短暂到达之前的 API 配置。如果您的 API 部署在多个网关或区域中，请分别更新每个网关。
  • 客户端工具缓存：由于 API Gateway 通过无状态 HTTP 传输提供 MCP，因此网关不会发出 notifications/tools/list_changed 通知。网关更新完成后，缓存工具定义的 MCP 客户端必须再次调用 tools/list 才能发现更新后的工具。
  • API 配置限制：每个 API 最多只能有 100 个 API 配置，因此请在更新网关后删除被取代的 API 配置。请逐个创建 API 配置；如果您在第一个 API 配置完成之前为同一 API 启动第二个 API 配置，则网关可能无法使用其中一个或两个配置。如需了解详情，请参阅配额和限制。

可观测性

MCP 请求会生成标准 API Gateway 指标和日志。您可以通过检查请求路径（通常以 /mcp 结尾）或配置自定义指标，将 MCP 流量与标准 REST 流量区分开来。

排查 MCP 故障

MCP 会区分传输失败和协议失败。对于协议和应用错误，网关会返回 HTTP 200 以及 JSON-RPC 错误对象，因为非 200 响应可能会导致许多 MCP 客户端在传输层失败。

下表介绍了常见症状和解决方法：

症状 JSON-RPC 代码 HTTP Status 含义和典型修复方法
Method Not Allowed 无 405 非 POST 请求到达了 /mcp。仅支持 HTTP POST。
JSON 解析错误 -32700 400 请求正文不是有效的 JSON。
方法或 ID 缺失/无效 -32600 200 正文是有效的 JSON，但不是有效的 JSON-RPC 请求。检查必填字段（jsonrpc、method、id）。
方法不受支持 -32601 200 该方法不在支持的范围内（例如 ping）。
协议版本不受支持 -32602 200 protocolVersion 指定了网关不支持的版本。
缺少协议版本 -32602 200 initialize 参数省略了 protocolVersion，或者它不是字符串。
未知工具 -32602 200 在已部署的 API 配置中找不到工具名称。刷新客户端工具缓存，或参阅更新公开的 MCP 工具。
工具参数无效 -32602 200 参数缺失或无效。验证 body 键嵌套。
正文过大 -32000 200 响应载荷超出了大小限制。
传输正文过大 无 413 原始 HTTP 请求正文超出了网关传输限制。
服务器错误 -32000 200 无法解析后端响应。检查日志。
未经授权/禁止 无 401/403 身份验证失败。响应包含指向受保护资源元数据的 WWW-Authenticate 标头。

后端应用错误通常会显示为成功的 JSON-RPC 响应 (HTTP 200)，其中 result.isError: true 包含后端错误正文。

后续步骤