Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

配置 Model Context Protocol

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

准备工作

确保您拥有适用于 API 的有效 OpenAPI 3.x 规范。MCP 不支持 OpenAPI 2.0。
确保您了解 API Gateway 的基础知识。

配置验证

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

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

身份验证模型

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

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

配置 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 来选择停用该操作。

3. 使用 `tools/list` 进行身份验证（推荐）

默认情况下，tools/list 方法（用于枚举可用工具）未经身份验证。出于安全方面的考虑，强烈建议通过在 x-google-api-management/mcp 下配置 tools-list.security 来强制执行身份验证。您必须使用 JWT 方案；此方法不支持 API 密钥。

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

4. 创建并部署 API 配置

根据带注释的规范创建 API 配置，并使用标准流程将其部署到网关。如需了解详情，请参阅将 API 部署到网关。

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"}'

探索工具

列出可用的工具：

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 调用。

调用工具

调用特定工具。如果底层 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 指标和日志。您可以通过检查请求路径（通常以 /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`	找不到工具名称。清理客户端缓存或验证部署。
工具实参无效	`-32602`	`200`	实参缺失或无效。验证 `body` 键嵌套。
正文过大	`-32000`	`200`	响应载荷超出了大小限制。
传输正文过大	无	`413`	原始 HTTP 请求正文超出了网关传输限制。
服务器错误	`-32000`	`200`	无法解析后端响应。查看日志。
未经授权 / 禁止	无	`401`/`403`	身份验证失败。响应包含指向受保护资源元数据的 `WWW-Authenticate` 标头。

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