api-gateway-mcp-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Gateway Remote MCP Server (Public Preview)

API Gateway 远程 MCP 服务器（Public Preview）

This skill converts new or existing REST APIs on Google Cloud API Gateway into remote Model Context Protocol (MCP) servers (

POST https://{default_hostname}/mcp

, Public Preview). By annotating an OpenAPI 3.x (3.0.x or 3.1.x) specification with

x-google-api-management.mcp

and

x-google-mcp-tool

, API Gateway translates MCP JSON-RPC 2.0 requests (

initialize

notifications/initialized

tools/list

tools/call

) into standard HTTP REST requests to your backend while enforcing existing authentication and quota policies.

此 skill 可将 Google Cloud API Gateway 上新建或现有的 REST API 转换为远程 Model Context Protocol (MCP) 服务器（

POST https://{default_hostname}/mcp

，Public Preview）。通过在 OpenAPI 3.x（3.0.x 或 3.1.x）规范中使用

x-google-api-management.mcp

和

x-google-mcp-tool

进行标注，API Gateway 会将 MCP JSON-RPC 2.0 请求（

initialize

、

notifications/initialized

、

tools/list

、

tools/call

）转换为发往后端的标准 HTTP REST 请求，同时执行现有的身份验证和配额策略。

Prerequisites

前置条件

Install the Google Cloud CLI and the validator dependency:
- Install the Google Cloud CLI. Then update it to the latest version with
```
gcloud components update
```
  . An old CLI can fail when it uploads an OpenAPI 3.x API config.
- Install Python 3.10 or later and
```
PyYAML
```
  for the local OpenAPI MCP validator script:
  bash
```
pip install "PyYAML>=6.0,<7.0"
```
Authenticate your environment:
- Local CLI session:
```
gcloud auth login
```
- Application Default Credentials (SDKs / ADK):
```
gcloud auth application-default login
```
Select or create a project, confirm billing, and pick a supported gateway location:
- Select an existing project (
```
gcloud config set project {project_id}
```
  ) or create one (
```
gcloud projects create {project_id}
```
  ).
- Confirm that an active billing account is linked to
```
{project_id}
```
  . API Gateway has a free monthly allowance of API calls for each billing account, but you still need an active billing account to deploy. Calls above the allowance and network data transfer out are charged. For current prices, see API Gateway pricing.
- Use
```
us-central1
```
  as the default
```
--location
```
  for gateway commands. For the other supported regions, see API Gateway deployment model.

Enable the required Google Cloud APIs:

bash

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

For API hub discovery (optional), enable the API hub API in the API hub host project:

gcloud services enable apihub.googleapis.com --project={hub_project_id}

. To query Agent Registry (optional), also run

gcloud services enable agentregistry.googleapis.com --project={project_id}

Verify the IAM roles (use the most restrictive role for each step):
- To create and update the API, API configs, and gateways: API Gateway Admin (
```
roles/apigateway.admin
```
  ) on
```
{project_id}
```
  . To run the
```
gcloud services enable
```
  commands: Service Usage Admin (
```
roles/serviceusage.serviceUsageAdmin
```
  ) on that project.
- To reference the gateway service account in an API config: Service Account User (
```
roles/iam.serviceAccountUser
```
  ) on
```
{gateway_sa_name}@{project_id}.iam.gserviceaccount.com
```
  .
- For a Cloud Run backend: grant the gateway service account the Cloud Run Invoker role (
```
roles/run.invoker
```
  ) on the service.
- To mint test ID tokens as a caller service account: Service Account Token Creator (
```
roles/iam.serviceAccountTokenCreator
```
  ) on
```
{caller_sa_email}
```
  .
- Reference: Configure the development environment.

安装 Google Cloud CLI 和验证器依赖：
- 安装 Google Cloud CLI。然后使用
```
gcloud components update
```
  将其更新至最新版本。旧版 CLI 在上传 OpenAPI 3.x API config 时可能会失败。
- 安装 Python 3.10 或更高版本，以及用于本地 OpenAPI MCP 验证器脚本的
```
PyYAML
```
  ：
  bash
```
pip install "PyYAML>=6.0,<7.0"
```
验证环境身份：
- 本地 CLI 会话：
```
gcloud auth login
```
- Application Default Credentials（SDK / ADK）：
```
gcloud auth application-default login
```
选择或创建项目、确认结算账号，并选择受支持的 gateway 位置：
- 选择现有项目（
```
gcloud config set project {project_id}
```
  ）或创建项目（
```
gcloud projects create {project_id}
```
  ）。
- 确认
```
{project_id}
```
  已关联有效的结算账号。每个结算账号均有免费的月度 API 调用额度，但部署时仍需有效的结算账号。超出额度的调用和出站网络数据传输会计费。有关当前价格，请参阅 API Gateway pricing。
- 对 gateway 命令使用
```
us-central1
```
  作为默认
```
--location
```
  。有关其他受支持的区域，请参阅 API Gateway deployment model。

启用所需的 Google Cloud API：

bash

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

如需使用 API hub 发现功能（可选），请在 API hub 所在项目中启用 API hub API：

gcloud services enable apihub.googleapis.com --project={hub_project_id}

。如需查询 Agent Registry（可选），还需运行

gcloud services enable agentregistry.googleapis.com --project={project_id}

。

验证 IAM 角色（每一步均使用权限范围最小的角色）：
- 要创建和更新 API、API config 与 gateway：在
```
{project_id}
```
  上授予 API Gateway Admin（
```
roles/apigateway.admin
```
  ）。要在该项目中运行
```
gcloud services enable
```
  命令：授予 Service Usage Admin（
```
roles/serviceusage.serviceUsageAdmin
```
  ）。
- 要在 API config 中引用 gateway service account：在
```
{gateway_sa_name}@{project_id}.iam.gserviceaccount.com
```
  上授予 Service Account User（
```
roles/iam.serviceAccountUser
```
  ）。
- 对于 Cloud Run 后端：在该服务上向 gateway service account 授予 Cloud Run Invoker 角色（
```
roles/run.invoker
```
  ）。
- 要以调用方 service account 签发测试 ID token：在
```
{caller_sa_email}
```
  上授予 Service Account Token Creator（
```
roles/iam.serviceAccountTokenCreator
```
  ）。
- 参考：Configure the development environment。

Decision Matrix: MCP Server Configuration and Client Integration

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

Task	Required Mechanism	Critical Guardrail	Detailed Reference
Migrate OpenAPI 2.0 ( `swagger: "2.0"` ) or author OpenAPI 3.x for MCP	Root `x-google-api-management.mcp` + named `backends` + operation-level `x-google-mcp-tool`	NEVER add MCP extensions to an OpenAPI 2.0 spec. Rationale: MCP is not supported for OpenAPI 2.0. Use OpenAPI 3.0.x or 3.1.x, and deploy the spec with `gcloud api-gateway api-configs create` . Keep all MCP operations in one OpenAPI document: if an API config has several documents, API Gateway serves the MCP tools of only one of them.	OpenAPI 2.0 to 3.x Migration
Optimize tool names, descriptions, and schemas for LLM tool selection	`x-google-mcp-tool` ( `name` , `description` , `false` ) + described `requestBody` properties	Every operation MUST have an `operationId` , with or without MCP. Every exposed tool MUST resolve to a unique name that matches `[A-Za-z0-9_.-]{1,128}` ( `x-google-mcp-tool.name` , or else the `operationId` ), a non-empty description, and a non-empty response body ( `HTTP 204` is unsupported). Only `GET` , `POST` , `PUT` , `PATCH` , and `DELETE` operations can be tools, and a gateway serves at most 1,000 tools. API Gateway rejects complex nested schemas when you create the API config, but a simple nested object body works. In OpenAPI 3.1, give each schema one `type` , because API Gateway also rejects a type list such as `type: ["string", "null"]` . Describe each property, and check each tool's `inputSchema` in `tools/list` after you deploy.	OpenAPI Agent Tool Optimizer
Secure `tools/list` and hide internal/admin routes	`x-google-api-management.mcp.tools-list.security` (exactly one JWT or API key scheme; a JWT scheme is also listed in root `security` ) + `x-google-mcp-tool: false`	`tools/list` is unauthenticated by default. It accepts one JWT scheme, or one API key scheme sent in the `x-api-key` header. API Gateway rejects a config whose JWT `tools-list.security` scheme is missing from the root `security` list, and that root entry also requires the JWT on every REST operation without its own `security` . If the root list already has an API key scheme, add the JWT to the same requirement object (AND): API Gateway does not support alternative (OR) requirements with an API key. An `mcp` object (for `tools-list` ) also enables MCP for every eligible operation, so opt out each operation that agents must not use. `x-google-mcp-tool: false` hides a route from MCP only; keep REST `security` on admin routes.	OpenAPI 2.0 to 3.x Migration
Connect Google ADK ( `McpToolset` ) and discover in API hub / Agent Registry	`McpToolset` ( `StreamableHTTPConnectionParams` ) + API hub project attachment	No separate registration step is needed. After you attach the API Gateway project to API hub, the MCP server appears in API hub as `{your_api} (MCP)` and in Agent Registry automatically.	ADK and API Hub Discovery
Verify `/mcp` JSON-RPC lifecycle and troubleshoot `-32601` / `-32602` / `-32000` errors	`POST https://{default_hostname}/mcp` with `MCP-Protocol-Version: 2025-11-25`	Keep `/mcp` at the host root: a `servers` base path (such as `/v2` ) applies to REST paths only, and `{basepath}/mcp` returns HTTP 404. Nest JSON request bodies under `params.arguments.body` ( `{"body": {...}}` ). NEVER combine `x-google-api-management.mcp` with `x-google-model-router` in one config. Rationale: API Gateway does not allow MCP and model routing in the same API config.	MCP Verification and Troubleshooting

任务	必需机制	关键约束	详细参考
迁移 OpenAPI 2.0（ `swagger: "2.0"` ）或为 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 config 包含多个文档，API Gateway 只会提供其中一个文档的 MCP 工具。	OpenAPI 2.0 to 3.x Migration
优化工具名称、描述和 schema，以支持 LLM 工具选择	`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` 操作可以作为工具，且一个 gateway 最多提供 1,000 个工具。创建 API config 时，API Gateway 会拒绝复杂的嵌套 schema，但简单的嵌套对象请求体可以使用。在 OpenAPI 3.1 中，每个 schema 只能指定一个 `type` ，因为 API Gateway 同样会拒绝 `type: ["string", "null"]` 这样的类型列表。请描述每个属性，并在部署后检查 `tools/list` 中每个工具的 `inputSchema` 。	OpenAPI Agent Tool Optimizer
保护 `tools/list` 并隐藏内部或管理类路由	`x-google-api-management.mcp.tools-list.security` （恰好使用一种 JWT 或 API key 方案；如果使用 JWT 方案，根级 `security` 中也必须列出该方案）+ `x-google-mcp-tool: false`	`tools/list` 默认不进行身份验证。它接受一种 JWT 方案，或通过 `x-api-key` 请求头发送的一种 API key 方案。如果 API Gateway 配置中 JWT `tools-list.security` 方案未出现在根级 `security` 列表中，则会拒绝该配置；而根级条目还会要求所有未自行定义 `security` 的 REST 操作必须提供该 JWT。如果根级列表中已有 API key 方案，请将 JWT 添加到同一个要求对象中（AND）：API Gateway 不支持包含 API key 的替代（OR）要求。 `mcp` 对象（用于 `tools-list` ）还会为每个符合条件的操作启用 MCP，因此必须排除 Agent 不应使用的操作。 `x-google-mcp-tool: false` 只会将路由从 MCP 中隐藏；管理类路由仍应保留 REST `security` 。	OpenAPI 2.0 to 3.x Migration
连接 Google ADK（ `McpToolset` ）并在 API hub / Agent Registry 中发现服务	`McpToolset` （ `StreamableHTTPConnectionParams` ）+ API hub 项目关联	无需单独的注册步骤。将 API Gateway 项目关联到 API hub 后，MCP 服务器会自动显示在 API hub 中，名称为 `{your_api} (MCP)` ，并自动出现在 Agent Registry 中。	ADK and API Hub Discovery
验证 `/mcp` JSON-RPC 生命周期并排查 `-32601` / `-32602` / `-32000` 错误	使用 `MCP-Protocol-Version: 2025-11-25` 向 `POST https://{default_hostname}/mcp` 发送请求	请将 `/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 config 中同时使用 MCP 和模型路由。	MCP Verification and Troubleshooting

Execution Workflow and Validation Loop

执行工作流与验证循环

Upgrade and annotate the OpenAPI 3.x specification:
- The references in this skill contain the conversion rules: the Swagger 2.0 Construct Conversion Map covers each Swagger 2.0 construct, and the Complete Converted Example shows a finished spec with a Google ID token scheme. Use them before you search other sources.
- Follow OpenAPI 2.0 to 3.x Migration and OpenAPI Agent Tool Optimizer to set
```
openapi
```
  to a 3.0.x or 3.1.x version (the examples use
```
3.0.4
```
  ), remove unsupported OpenAPI 2.0 fields (
```
x-google-allow
```
  ), define
```
x-google-api-management.backends
```
  (with
```
jwtAudience
```
  or
```
disableAuth
```
  ), configure
```
x-google-api-management.mcp.tools-list.security
```
  with exactly one JWT or API key scheme (add a JWT scheme to the root
```
security
```
  list too, in the same requirement object as any API key scheme), author
```
x-google-mcp-tool
```
  descriptions stating when and why to invoke each tool, and opt out administrative routes (
```
x-google-mcp-tool: false
```
  ).
- Before you deploy, give the user a short summary that states each of these points, and get approval:
  - MCP is not supported for OpenAPI 2.0, so you converted the spec to OpenAPI 3.x.
  - Which operations you exposed as tools, and which you opted out with
```
x-google-mcp-tool: false
```
    . Opted-out operations stay on REST.
  - If
```
tools/list
```
    uses a JWT scheme, the root
```
security
```
    entry makes every REST operation without its own
```
security
```
    require the JWT. The gateway rejects REST callers without it.
  - The MCP endpoint is
```
https://{default_hostname}/mcp
```
    , at the host root even when the spec sets a
```
servers
```
    base path.
  - The limits that apply: only
```
GET
```
    ,
```
POST
```
    ,
```
PUT
```
    ,
```
PATCH
```
    , and
```
DELETE
```
    operations can be tools, a gateway serves at most 1,000 tools, request parameters must be primitive types, API Gateway rejects complex nested schemas and OpenAPI 3.1 type lists (such as
```
type: ["string", "null"]
```
    ) when you create the API config, tools cannot return
```
HTTP 204
```
    , and MCP is stateless with UTF-8 text responses only.
- Give the same points when the user only asks for the converted spec or for advice, without a deploy.
- Preserve exact quota metric names in
```
x-google-api-management.metrics
```
  across API configs so existing gateways do not fail with HTTP 500
```
Failed to call Service Control Quota
```
  .
Run the deterministic MCP OpenAPI validation loop before creating the API config:
- Execute
```
scripts/validate_mcp_openapi.py
```
  on
```
{candidate_openapi_spec}
```
  :
  bash
```
python3 scripts/validate_mcp_openapi.py --spec={candidate_openapi_spec}
```
- If
```
scripts/validate_mcp_openapi.py
```
  exits with code
```
1
```
  (
```
status: "FAIL"
```
  ), fix every reported error in
```
{candidate_openapi_spec}
```
  (such as OpenAPI 2.0 syntax,
```
x-google-allow
```
  , path-level
```
x-google-mcp-tool
```
  , undefined backend names, an operation without an
```
operationId
```
  , missing descriptions, invalid or duplicate tool names, a header parameter with the reserved
```
x-google-
```
  prefix, a
```
tools-list.security
```
  scheme that is neither an
```
oauth2
```
  JWT nor an
```
apiKey
```
  scheme, a JWT
```
tools-list.security
```
  scheme missing from the root
```
security
```
  list, alternative (OR) security requirements with an API key, or an
```
x-google-model-router
```
  operation in an MCP spec) and re-run the script until it exits with code
```
0
```
  (
```
status: "PASS"
```
  ). If it exits with code
```
2
```
  , fix the file path or YAML syntax error printed to stderr.
- Read every warning (such as an
```
HTTP 204
```
  response, a request parameter that is not a primitive type, or operations that an
```
mcp
```
  object exposes by default). Fix it, or tell the user why you keep it.

Create the API (if new), create the API config, deploy the gateway, and enable the managed service (request human approval before updating a production gateway):

bash

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}

(For a brand-new gateway, run
gcloud api-gateway gateways create {gateway_id} ...
instead of
gateways update
).

Run one
```
api-configs create
```
at a time per API. Wait for it to finish before you start the next one, because API Gateway creates only one config for an API at a time. A complex API config can take up to ten minutes to create.
If clients use API keys from other projects, enable the managed service in each of those projects too. API Gateway rejects an API key unless the API is enabled in the project that created the key.

Verify the JSON-RPC 2.0 lifecycle and connect ADK / API hub:
- Send every probe to
```
https://{default_hostname}/mcp
```
  , even when the spec sets a
```
servers
```
  base path.
- An HTML
```
404 Page not found
```
  means that the gateway may not be deployed correctly. Check that the gateway state is
```
ACTIVE
```
  and that the last create or update finished, and retry before you change the config. During a gateway update, some requests can still reach the previous API config. A JSON 404 (
```
The current request is not defined by this API.
```
  ) means that the active config does not define the path.
- If
```
tools/list
```
  requires a JWT, mint a Google ID token whose audience is in
```
x-google-auth.audiences
```
  :
```
gcloud auth print-identity-token --impersonate-service-account={caller_sa_email} --audiences={jwt_audience}
```
  . If
```
tools/list
```
  requires an API key, send it in the
```
x-api-key
```
  header.
- Run the
```
initialize
```
  ,
```
notifications/initialized
```
  ,
```
tools/list
```
  , and
```
tools/call
```
  verification probes in MCP Verification and Troubleshooting.
- Connect Google ADK (
```
McpToolset
```
  ) and verify automatic catalog discovery in Apigee API hub (
```
{your_api} (MCP)
```
  ) and Agent Registry using ADK and API Hub Discovery.

升级并标注 OpenAPI 3.x 规范：
- 此 skill 中的参考资料包含转换规则：Swagger 2.0 Construct Conversion Map 涵盖每种 Swagger 2.0 构造，Complete Converted Example 展示了一个带有 Google ID token 方案的完整转换后示例。在查找其他来源之前，请先使用这些资料。
- 按照 OpenAPI 2.0 to 3.x Migration 和 OpenAPI Agent Tool Optimizer 操作：将
```
openapi
```
  设置为 3.0.x 或 3.1.x 版本（示例使用
```
3.0.4
```
  ），移除不支持的 OpenAPI 2.0 字段（
```
x-google-allow
```
  ），定义
```
x-google-api-management.backends
```
  （使用
```
jwtAudience
```
  或
```
disableAuth
```
  ），使用恰好一种 JWT 或 API key 方案配置
```
x-google-api-management.mcp.tools-list.security
```
  （如果使用 JWT 方案，还需将其添加到根级
```
security
```
  列表中，并与任何 API key 方案放在同一个要求对象内），编写
```
x-google-mcp-tool
```
  描述以说明何时以及为何调用各个工具，并排除管理类路由（
```
x-google-mcp-tool: false
```
  ）。
- 部署之前，向用户提供一份简短摘要并获得批准：
  - MCP 不支持 OpenAPI 2.0，因此已将规范转换为 OpenAPI 3.x。
  - 列出公开为工具的操作，以及通过
```
x-google-mcp-tool: false
```
    排除的操作。被排除的操作仍保留在 REST 中。
  - 如果
```
tools/list
```
    使用 JWT 方案，根级
```
security
```
    条目会使每个未自行定义
```
security
```
    的 REST 操作都要求提供该 JWT。Gateway 会拒绝未提供该 JWT 的 REST 调用方。
  - MCP 端点为
```
https://{default_hostname}/mcp
```
    。即使规范设置了
```
servers
```
    基础路径，该端点仍位于主机根路径。
  - 适用的限制包括：只有
```
GET
```
    、
```
POST
```
    、
```
PUT
```
    、
```
PATCH
```
    和
```
DELETE
```
    操作可以作为工具；一个 gateway 最多提供 1,000 个工具；请求参数必须为原始类型；创建 API config 时，API Gateway 会拒绝复杂的嵌套 schema 和 OpenAPI 3.1 类型列表（如
```
type: ["string", "null"]
```
    ）；工具不能返回
```
HTTP 204
```
    ；MCP 无状态，且仅支持 UTF-8 文本响应。
- 即使用户只要求转换后的规范或相关建议，而不要求部署，也应提供上述相同信息。
- 在各个 API config 之间保留
```
x-google-api-management.metrics
```
  中完全一致的配额指标名称，避免现有 gateway 因 HTTP 500
```
Failed to call Service Control Quota
```
  而失败。
创建 API config 之前，运行确定性的 MCP OpenAPI 验证循环：
- 对
```
{candidate_openapi_spec}
```
  执行
```
scripts/validate_mcp_openapi.py
```
  ：
  bash
```
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
```
  、未定义的 backend 名称、缺少
```
operationId
```
  的操作、缺少描述、工具名称无效或重复、带有保留
```
x-google-
```
  前缀的 header 参数、既不是
```
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
```
  对象默认公开的操作。修复这些问题，或告知用户保留它们的原因。

创建 API（如果尚不存在）、创建 API config、部署 gateway，并启用托管服务（更新生产 gateway 前必须获得人工批准）：

bash

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}

（对于全新 gateway，请运行
gcloud api-gateway gateways create {gateway_id} ...
，而不是
gateways update
。）

每个 API 每次只能运行一个
```
api-configs create
```
。请等待其完成后，再开始下一个，因为 API Gateway 一次只能为一个 API 创建一个 config。复杂的 API config 最长可能需要十分钟才能创建完毕。
如果客户端使用来自其他项目的 API key，也必须在每个相关项目中启用托管服务。除非在创建密钥的项目中启用了该 API，否则 API Gateway 会拒绝该 API key。

验证 JSON-RPC 2.0 生命周期并连接 ADK / API hub：
- 即使规范设置了
```
servers
```
  基础路径，也必须将所有探测请求发送到
```
https://{default_hostname}/mcp
```
  。
- HTML 格式的
```
404 Page not found
```
  表示 gateway 可能未正确部署。请检查 gateway 状态是否为
```
ACTIVE
```
  ，以及最后一次创建或更新是否已完成，然后重试，再考虑修改配置。在 gateway 更新期间，部分请求仍可能到达之前的 API config。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 Verification and Troubleshooting 运行
```
initialize
```
  、
```
notifications/initialized
```
  、
```
tools/list
```
  和
```
tools/call
```
  验证探测。
- 连接 Google ADK（
```
McpToolset
```
  ），并按照 ADK and API Hub Discovery 验证在 Apigee API hub（
```
{your_api} (MCP)
```
  ）和 Agent Registry 中的自动目录发现。

Pre-Deployment Checklist

部署前检查清单

Specification version is

openapi: 3.0.x

3.1.x

(not

swagger: "2.0"

), omits

x-google-allow

, and does not contain

x-google-model-router

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

returns

status: "PASS"

(exit code

Every operation has an
```
operationId
```
, and all MCP operations are in one OpenAPI document.

x-google-api-management.mcp.tools-list.security

names exactly one scheme: an

oauth2

JWT scheme with

x-google-auth

that the root

security

list also references, or an

apiKey

scheme with

in: header

and

name: x-api-key

If
```
tools/list
```
uses a JWT scheme, the user knows that REST operations without their own
```
security
```
now require that JWT.
Administrative, health-check, and
```
HTTP 204
```
endpoints are opted out with
```
x-google-mcp-tool: false
```
, and opted-out admin paths remain protected on REST.

MCP clients call

https://{default_hostname}/mcp

(not

{basepath}/mcp

), nest

tools/call

JSON request bodies inside

params.arguments.body

, and send

MCP-Protocol-Version: 2025-11-25

规范版本为

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"

（退出代码为

）。

每个操作都有
```
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

。

Resource Cleanup

资源清理

To avoid ongoing charges when tearing down a test or staging environment, request human approval and delete the gateway, API config, API, and service account in dependency order:

bash

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}

为避免在拆除测试或预发布环境后继续产生费用，请先获得人工批准，然后按照依赖顺序删除 gateway、API config、API 和 service account：

bash

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}