第 01 步 / 生成

生成规则

每个 operation 成为一个工具，名字取自 operationId，描述取自 summary。参数按「它要去哪里」加命名空间前缀，因此一个扁平对象 不可能悄悄和另一种绑定冲突：

Path以裸名传入（例如 id），随后按百分号编码填入路径模板
Query带前缀：名为 limit 的查询参数写作 query_limit
Header 与 Cookie同样带前缀；若配置里已经设置了该 header，则直接拒绝
Request body收进一个 body 对象，保留 schema 自身的属性与 required 列表

输入语义含糊或无法解析的 spec 会被整体拒绝，而不是「尽力猜一猜」。一个 半懂不懂的桥，正是模型调到运维根本没打算暴露的东西的方式。

第 02 步 / 配置

配置上游

上游由运维方声明，绝不接受来自请求输入的声明。注册表是一个 JSON 数组，最多 16 条：

export MCP_UPSTREAM_SERVERS_JSON='[{"id":"orders","transport":"openapi","baseUrl":"https://orders.example.test","specUrl":"https://orders.example.test/openapi.json","allowedTools":["listOrders","get*"],"readOnlyTools":["listOrders"]}]'

把 specUrl 换成内联的 spec 对象即可完全离线运行。 任何非空注册表都会自动启用外部副作用闸门。

第 03 步 / 策略

允许清单决定模型能看见什么

匹配规则是精确名、前缀 prefix*，或单个 *。默认并不宽松：

缺省或为空拒绝所有工具；上游依然可达，但对模型工具面零贡献
精确名只放行该 operation
前缀星号get* 放行 getOrder，而 createOrder 仍被围栏
只读声明只有出现在 readOnlyTools 里的名字才被标注无副作用；其余一律走外部副作用路径

第 04 步 / 边界

会被拒绝什么（下面是网关的原话，不是转述）

非 HTTPS 上游MCP upstream 'x' requires an https url.
第 17 条注册表MCP upstream registry exceeds the maximum of 16 servers.
JSON 不合法MCP_UPSTREAM_SERVERS_JSON is not valid JSON.
输入无法解析OpenAPI operation has unsupported, ambiguous, or unresolvable input semantics.
目标被拦Outbound request blocked by the gateway network policy.
响应过大OpenAPI bridge response exceeds the size limit.

目标校验发生在任何传输层之前，因此即使调用方只能控制参数取值，也无法把 生成的工具指向内网地址。

第 05 步 / 接口面

工具出现在哪里

GET /mcp/health就绪状态；未配置注册表时返回 {"status":"disabled","upstreamCount":0}
GET /mcp/tools返回 toolCount、tools 与 servers，按已认证身份收窄
POST /mcp/call启用 Agent 治理时，执行经由治理路径

启动方式沿用快速上手文档给出的命令，再加上面这个环境变量： 快速上手 里写的是把已发布镜像 ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.8.0 以 --publish 127.0.0.1:3100:3100 方式运行。

证据边界

本页如何核对

上面的工具名、参数命名空间、缺省全拒行为、匹配规则以及每一条被引用的错误 字符串，都是在 v0.8.0 标签上直接执行已发布模块得到的： apps/ai-gateway-service/src/mcpGateway/openApiRestBridge.ts 与 mcpGatewayConfig.ts，对一个三 operation 的示例 spec 运行， 并注入传输层。全程没有网络出站，也没有使用任何真实 Provider 凭据。上一节 那条容器命令是文档既有写法，本页编写时未在本机执行。

这是自托管软件的 Public Preview。以上不构成生产就绪、L5 自主或 AGI 声明， 真实 Provider 默认关闭。