OpenAPI-to-MCP 安全与限制
OpenAPI-to-MCP 路由将 API 描述转换为工具,并将工具调用发送给文档描述的 API。文档决定客户端可见的内容,工具参数影响网关向外发送的请求。将路由开放给 MCP 客户端前,应保护好这两道信任边界。
下文介绍的各项控制适用于 APISIX 3.20.0。API7 企业版 3.9.23 和 3.10.10 通过独立的 OpenAPI-to-MCP 服务处理 MCP 流量。API7 企业版可以限制 API 目标地址,但没有 APISIX 中对浏览器源、引用主机、资源用量和编码路径分隔符的控制。关于适用产品和字段定义,请参阅配置参考。
确保文档和 API 目标地址可信
OpenAPI 文档定义工具的名称、描述、输入模式和上游操作。因此,即使最终发出的 HTTP 请求有效,被篡改的文档也可能影响模型。
将路由开放给客户端前,请检查下表中的各道边界。
| 边界 | 建议配置 | 原因 |
|---|---|---|
| 文档来源 | 从你控制的来源加载 openapi_url | 文档决定公开哪些工具和操作 |
| 外部引用 | 将引用保留在文档的源内,或仅将所需主机添加到 allowed_ref_hosts | 否则,APISIX 会拒绝协议、主机或端口不同的引用 |
| API 目标地址 | 固定 base_url,或从网关控制的变量获取该值 | 如果由客户端控制此值,客户端就可以选择工具调用的发送目标 |
除非文档确实需要,否则请勿允许文档引用内部服务或元数据端点。API7 企业版解析 API 目标地址中的变量时,请使用 allowed_hosts 限制解析结果。APISIX 没有等效的目标地址允许列表。
验证浏览器源
基于浏览器的 MCP 客户端会发送 Origin 请求头。APISIX 会结合路由和请求校验该源,以保护浏览器可访问的 MCP 路由免受 DNS 重绑定攻击。此校验无法代替身份验证,未携带源的请求仍会被接受。
如果未配置 allowed_origins,且路由明确指定了主机,APISIX 仅在满足以下全部条件时接受该源。
- 源的主机与路由
host或hosts字段中列出的字面值匹配。路由中的通配符主机不构成信任依据。 - 源和请求使用相同的协议。
- 源和请求使用相同的端口。省略端口时,APISIX 对 HTTP 使用 80,对 HTTPS 使用 443。
如果路由未明确指定主机,只要源和请求均使用环回主机,且协议和端口相同,APISIX 也会接受该源。如果可信浏览器源与路由主机不同,包括在 APISIX 前终止 TLS 的部署,请配置 allowed_origins。
请明确列出可信源。允许所有源会使此校验失去对 DNS 重绑定攻击的防护作用。
限制工具调用
MCP 客户端为每次工具调用提供参数。APISIX 会限制这些参数对上游请求的影响,并保留操作路径的结构。
参数和请求头
APISIX 只转发对应 OpenAPI 操作中声明的路径、查询和请求头参数。未声明的参数会被丢弃。
路由中配置的请求头优先于工具调用提供的同名请求头,请求头名称仅大小写不同时也遵循此规则。APISIX 还会丢弃以下内容。
- 用于选择目标或定义请求体的请求头,包括
Host、Content-Length和Transfer-Encoding。 - 用于改变连接行为的请求头,包括
Connection、Upgrade和Expect。 - 无效的请求头名称及包含换行符的请求头值。
配置的请求头适用于文档公开的所有操作。请只公开可以共用这些凭据的操作。consumer-restriction 插件可以限制对 MCP 路由的访问,但无法为 单个工具授权。
API7 企业版可以移除客户端请求头中的 OpenAPI-to-MCP 前缀,然后转发这些请求头。请使用网关认证保护路由,并在插件中配置敏感的上游凭据,防止客户端覆盖。关于所需前缀、优先级和传输方式,请参阅通过 API7 网关转发动态请求头。
操作路径
APISIX 实施以下限制,防止路径参数改变预期的路径结构。
- 默认情况下,包含斜杠或反斜杠的路径参数值会被拒绝。
- 启用编码路径分隔符后,APISIX 会对分隔符进行百分号编码。对分隔符后的路径段,如果其内容为空、
.或..,APISIX 仍会拒绝。 - 受参数影响的路径段解析后不能为空、
.或..。 - 插入 URI 模板查询字符串的值会按查询数据编码。
- URI 片段不会随 HTTP 请求发送,因此会移除片段后缀。