api-gateway-mcp-server

API Gateway 远程 MCP 服务（公开预览版）

此技能可将 Google Cloud API Gateway 上的新建或现有 REST API 转换为远程 Model Context Protocol (MCP) 服务（POST https://{default_hostname}/mcp，公开预览版）。通过使用 x-google-api-management.mcp 和 x-google-mcp-tool 注解 OpenAPI 3.x（3.0.x 或 3.1.x）规范，API Gateway 会将 MCP JSON-RPC 2.0 请求（initialize、notifications/initialized、tools/list、tools/call）转换为发送到后端的标准 HTTP REST 请求，同时执行现有的身份验证和配额策略。

署名要求

必须阅读：执行任何 gcloud、REST API 或 MCP 命令前，必须阅读使用情况署名要求。对于直接在终端中执行的命令（切勿放入生成的脚本、Terraform 或用户代码中），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:api-gateway-mcp-server)" ，并将 agent-skills/1.0 (skill:api-gateway-mcp-server) 附加到 User-Agent 标头中。

前提条件

1. 安装 Google Cloud CLI 和验证器依赖项：
   • 安装 Google Cloud CLI。然后使用 gcloud components update 将其更新到最新版本。旧版 CLI 上传 OpenAPI 3.x API 配置时可能会失败。
   • 安装 Python 3.10 或更高版本，以及用于本地 OpenAPI MCP 验证器脚本的 PyYAML：

     pip install "PyYAML>=6.0,<7.0"
     

2. 验证环境身份：
   • 本地 CLI 会话：gcloud auth login
   • 应用默认凭据（SDK / ADK）：gcloud auth application-default login
3. 选择或创建项目、确认结算，并选择受支持的网关位置：
   • 选择现有项目（gcloud config set project {project_id}）或创建项目（gcloud projects create {project_id}）。
   • 确认 {project_id} 已关联有效的结算账号。API Gateway 为每个结算账号提供每月免费的 API 调用额度，但部署仍需有效的结算账号。超出免费额度的调用以及传出的网络数据传输均会收费。当前价格请参阅 API Gateway 定价。
   • 网关命令默认使用 us-central1 作为 --location。其他受支持的区域请参阅 API Gateway 部署模型。
4. 启用所需的 Google Cloud API：

   gcloud services enable \
     apigateway.googleapis.com \
     servicemanagement.googleapis.com \
     servicecontrol.googleapis.com \
     --project={project_id}
   

   如需在 API hub 主机项目中发现 API（可选），请启用 API hub API：gcloud services enable apihub.googleapis.com --project={hub_project_id}。如需查询 Agent Registry（可选），还需运行 gcloud services enable agentregistry.googleapis.com --project={project_id}。
5. 验证 IAM 角色（每个步骤均使用限制最严格的角色）：
   • 创建和更新 API、API 配置及网关：在 {project_id} 上具有 API Gateway Admin (roles/apigateway.admin) 角色。运行 gcloud services enable 命令：在该项目上具有 Service Usage Admin (roles/serviceusage.serviceUsageAdmin) 角色。
   • 在 API 配置中引用网关服务账号：在 {gateway_sa_name}@{project_id}.iam.gserviceaccount.com 上具有 Service Account User (roles/iam.serviceAccountUser) 角色。
   • 对于 Cloud Run 后端：向网关服务账号授予该服务上的 Cloud Run Invoker (roles/run.invoker) 角色。
   • 作为调用方服务账号创建测试 ID 令牌：在 {caller_sa_email} 上具有 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 角色。
   • 参考：配置开发环境。

决策矩阵：MCP 服务配置与客户端集成

任务	所需机制	关键防护措施	详细参考
将 OpenAPI 2.0（swagger: "2.0"）迁移为 OpenAPI 3.x，或编写用于 MCP 的 OpenAPI 3.x	根级 x-google-api-management.mcp + 命名的 backends + 操作级 x-google-mcp-tool	切勿向 OpenAPI 2.0 规范添加 MCP 扩展。原因： MCP 不支持 OpenAPI 2.0。请使用 OpenAPI 3.0.x 或 3.1.x，并通过 gcloud api-gateway api-configs create 部署该规范。将所有 MCP 操作放在同一份 OpenAPI 文档中：如果 API 配置包含多份文档，API Gateway 只会提供其中一份文档里的 MCP 工具。	OpenAPI 2.0 到 3.x 迁移
优化工具名称、描述和架构，以便大模型选择工具	x-google-mcp-tool（name、description、false）+ 带描述的 requestBody 属性	每个操作都必须有 operationId，无论是否使用 MCP。每个公开的工具都必须解析为唯一名称，且名称须匹配 [A-Za-z0-9_.-]{1,128}（使用 x-google-mcp-tool.name，否则使用 operationId），并具有非空描述和非空响应正文（不支持 HTTP 204）。只有 GET、POST、PUT、PATCH 和 DELETE 操作可作为工具，且一个网关最多可提供 1,000 个工具。创建 API 配置时，API Gateway 会拒绝复杂的嵌套架构，但简单的嵌套对象正文可正常使用。在 OpenAPI 3.1 中，每个架构只能指定一个 type，因为 API Gateway 也会拒绝类型列表，例如 type: ["string", "null"]。请描述每个属性，并在部署后检查 tools/list 中每个工具的 inputSchema。	OpenAPI Agent 工具优化器
保护 tools/list 并隐藏内部/管理路由	x-google-api-management.mcp.tools-list.security（恰好一个 JWT 或 API 密钥方案；JWT 方案也要列在根级 security 中）+ x-google-mcp-tool: false	默认情况下，tools/list 无需身份验证。它接受一个 JWT 方案，或一个通过 x-api-key 标头发送的 API 密钥方案。如果 JWT tools-list.security 方案未列在根级 security 列表中，API Gateway 会拒绝该配置；此外，根级列表中的该项还会要求每个未单独设置 security 的 REST 操作都使用 JWT。如果根级列表已有 API 密钥方案，请将 JWT 添加到同一要求对象中（AND）：API Gateway 不支持包含 API 密钥的替代（OR）要求。mcp 对象（用于 tools-list）还会为每个符合条件的操作启用 MCP，因此请对 Agent 不得使用的每个操作选择退出。x-google-mcp-tool: false 只会将路由从 MCP 中隐藏；管理路由仍应保留 REST security。	OpenAPI 2.0 到 3.x 迁移
连接 Google ADK（McpToolset），并在 API hub / Agent Registry 中发现服务	McpToolset（StreamableHTTPConnectionParams）+ 将项目关联到 API hub	无需单独注册。将 API Gateway 项目关联到 API hub 后，MCP 服务会自动显示在 API hub 中，名称为 {your_api} (MCP)，并显示在 Agent Registry 中。	ADK 与 API Hub 发现
验证 /mcp JSON-RPC 生命周期并排查 -32601 / -32602 / -32000 错误	POST https://{default_hostname}/mcp，并设置 MCP-Protocol-Version: 2025-11-25	将 /mcp 保留在主机根路径：servers 基础路径（例如 /v2）仅适用于 REST 路径，而 {basepath}/mcp 会返回 HTTP 404。将 JSON 请求正文嵌套在 params.arguments.body 下（{"body": {...}}）。切勿在同一配置中同时使用 x-google-api-management.mcp 和 x-google-model-router。原因： API Gateway 不允许在同一 API 配置中同时使用 MCP 和模型路由。	MCP 验证与故障排查

执行工作流与验证循环

1. 升级并注释 OpenAPI 3.x 规范：
   • 此技能中的参考资料包含转换规则：Swagger 2.0 构造转换映射涵盖每种 Swagger 2.0 构造，完整转换示例展示了带有 Google ID token 方案的完整规范。请先查阅这些资料，再搜索其他来源。
   • 按照 OpenAPI 2.0 到 3.x 迁移和 OpenAPI Agent 工具优化器操作：将 openapi 设置为 3.0.x 或 3.1.x 版本（示例使用 3.0.4），移除不受支持的 OpenAPI 2.0 字段（x-google-allow），定义 x-google-api-management.backends（使用 jwtAudience 或 disableAuth），为 x-google-api-management.mcp.tools-list.security 配置恰好一个 JWT 或 API key 方案（同时也在根 security 列表中、与任何 API key 方案放在同一个 requirement 对象内添加 JWT 方案），编写 x-google-mcp-tool 描述，说明 何时以及为何 调用每个工具，并将管理路由排除在外（x-google-mcp-tool: false）。
   • 部署之前，向用户简要概述以下各点并征得批准：
     • OpenAPI 2.0 不支持 MCP，因此你已将规范转换为 OpenAPI 3.x。
     • 你将哪些操作公开为工具，哪些操作通过 x-google-mcp-tool: false 排除。被排除的操作仍通过 REST 提供。
     • 如果 tools/list 使用 JWT 方案，根 security 条目会要求所有未单独设置 security 的 REST 操作都使用 JWT。网关会拒绝未携带该 JWT 的 REST 调用方。
     • MCP 端点是 https://{default_hostname}/mcp；即使规范设置了 servers 基础路径，端点也位于主机根路径。
     • 适用的限制：只有 GET、POST、PUT、PATCH 和 DELETE 操作可以作为工具；一个网关最多提供 1,000 个工具；请求参数必须是基本类型；创建 API 配置时，API Gateway 会拒绝复杂嵌套架构和 OpenAPI 3.1 类型列表（例如 type: ["string", "null"]）；工具不能返回 HTTP 204；MCP 是无状态的，且仅支持 UTF-8 文本响应。
   • 即使用户只要求转换后的规范或寻求建议、不要求部署，也要告知相同的内容。
   • 在不同 API 配置中保留 x-google-api-management.metrics 中配额指标的准确名称，以免现有网关出现 HTTP 500 Failed to call Service Control Quota。
2. 创建 API 配置之前，运行确定性的 MCP OpenAPI 验证流程：
   • 对 {candidate_openapi_spec} 执行 scripts/validate_mcp_openapi.py：

     python3 scripts/validate_mcp_openapi.py --spec={candidate_openapi_spec}
     

   • 如果 scripts/validate_mcp_openapi.py 以代码 1 退出（status: "FAIL"），请修复 {candidate_openapi_spec} 中报告的所有错误（例如 OpenAPI 2.0 语法、x-google-allow、路径级 x-google-mcp-tool、未定义的后端名称、缺少 operationId 的操作、缺少描述、无效或重复的工具名称、带有保留前缀 x-google- 的标头参数、既非 oauth2 JWT 也非 apiKey 方案的 tools-list.security 方案、根 security 列表中缺少 JWT tools-list.security 方案、带有 API key 的替代（OR）安全要求，或 MCP 规范中的 x-google-model-router 操作），然后重新运行脚本，直到以代码 0（status: "PASS"）退出。如果以代码 2 退出，请修复 stderr 中打印的文件路径或 YAML 语法错误。
   • 阅读每条警告（例如 HTTP 204 响应、非基本类型的请求参数，或 mcp 对象默认公开的操作）。修复问题，或向用户说明为何保留该问题。
3. 创建 API（如果是新 API）、创建 API 配置、部署网关并启用托管服务（更新生产网关前须征得人工批准）：

   gcloud api-gateway apis create {api_id} --project={project_id}
   
   gcloud api-gateway api-configs create {config_id} \
     --api={api_id} \
     --openapi-spec={candidate_openapi_spec} \
     --backend-auth-service-account={gateway_sa_name}@{project_id}.iam.gserviceaccount.com \
     --project={project_id}
   
   gcloud api-gateway gateways update {gateway_id} \
     --api={api_id} \
     --api-config={config_id} \
     --location={region} \
     --project={project_id}
   
   gcloud services enable $(gcloud api-gateway apis describe {api_id} --project={project_id} --format="value(managedService)") --project={project_id}
   

   （对于全新网关，请运行 gcloud api-gateway gateways create {gateway_id} ...，而不是 gateways update。）
   • 对每个 API，一次只运行一个 api-configs create。等待其完成后再启动下一个，因为 API Gateway 每次只能为一个 API 创建一个配置。复杂的 API 配置创建最多可能需要十分钟。
   • 如果客户端使用来自其他项目的 API key，也要在这些项目中启用托管服务。除非在创建该 API key 的项目中启用了 API，否则 API Gateway 会拒绝该密钥。
4. 验证 JSON-RPC 2.0 生命周期并连接 ADK / API hub：
   • 所有探测请求都发送到 https://{default_hostname}/mcp，即使规范设置了 servers 基础路径也是如此。
   • HTML 404 Page not found 表示网关可能未正确部署。请检查网关状态是否为 ACTIVE，以及最近一次创建或更新操作是否已完成，并在更改配置之前重试。更新网关期间，部分请求仍可能到达之前的 API 配置。JSON 404（The current request is not defined by this API.）表示当前生效的配置未定义该路径。
   • 如果 tools/list 需要 JWT，请生成受众在 x-google-auth.audiences 中的 Google ID token：gcloud auth print-identity-token --impersonate-service-account={caller_sa_email} --audiences={jwt_audience}。如果 tools/list 需要 API key，请在 x-api-key 标头中发送该密钥。
   • 按照 MCP 验证与故障排除中的说明，运行 initialize、notifications/initialized、tools/list 和 tools/call 验证探测。
   • 连接 Google ADK（McpToolset），并按照 ADK 与 API Hub 发现验证 Apigee API hub（{your_api} (MCP)）和 Agent Registry 中的自动目录发现。

部署前检查清单

• 规范版本为 openapi: 3.0.x 或 3.1.x（而非 swagger: "2.0"），不含 x-google-allow，也不包含 x-google-model-router。
• python3 scripts/validate_mcp_openapi.py --spec={candidate_openapi_spec} 返回 status: "PASS"（退出代码为 0）。
• 每个操作都有 operationId，且所有 MCP 操作都在同一份 OpenAPI 文档中。
• x-google-api-management.mcp.tools-list.security 必须恰好指定一个方案：带有 x-google-auth 且根 security 列表也引用该方案的 oauth2 JWT 方案，或 in: header 且 name: x-api-key 的 apiKey 方案。
• 如果 tools/list 使用 JWT 方案，用户需了解：没有自行配置 security 的 REST 操作现在需要该 JWT。
• 管理、健康检查和 HTTP 204 端点均通过 x-google-mcp-tool: false 选择退出，且选择退出的管理路径在 REST 上仍受保护。
• MCP 客户端调用 https://{default_hostname}/mcp（而非 {basepath}/mcp），将 tools/call JSON 请求正文嵌套在 params.arguments.body 中，并发送 MCP-Protocol-Version: 2025-11-25。

清理资源

为避免拆除测试或暂存环境后继续产生费用，请先征得人工批准，再按依赖顺序删除网关、API 配置、API 和服务账号：

gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}
gcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}
gcloud api-gateway apis delete {api_id} --project={project_id}
gcloud iam service-accounts delete {gateway_sa_name}@{project_id}.iam.gserviceaccount.com --project={project_id}