跳到主要内容

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 企业版请求头转发

API7 企业版可以移除客户端请求头中的 OpenAPI-to-MCP 前缀,然后转发这些请求头。请使用网关认证保护路由,并在插件中配置敏感的上游凭据,防止客户端覆盖。关于所需前缀、优先级和传输方式,请参阅通过 API7 网关转发动态请求头。

操作路径​

APISIX 实施以下限制,防止路径参数改变预期的路径结构。

  • 默认情况下,包含斜杠或反斜杠的路径参数值会被拒绝。
  • 启用编码路径分隔符后,APISIX 会对分隔符进行百分号编码。对分隔符后的路径段,如果其内容为空、. 或 ..,APISIX 仍会拒绝。
  • 受参数影响的路径段解析后不能为空、. 或 ..。
  • 插入 URI 模板查询字符串的值会按查询数据编码。
  • URI 片段不会随 HTTP 请求发送,因此会移除片段后缀。

限制资源用量​

文档、展开后的模式和工具响应都可能占用网关内存。APISIX 分别限制各阶段的资源用量。

资源达到限制时的行为
主 OpenAPI 文档及其引用的文档APISIX 拒绝超过大小限制的文档
展开后的操作定义展开达到配置的复杂度上限时,其余引用会变成通用对象模式
工具响应体工具调用以 RESPONSE_TOO_LARGE 失败,APISIX 不会缓冲整个响应

请根据路由需要处理的最大可信文档和 API 响应设置限制。配置参考列出了字段、默认值和最小值。

隔离 SSE 会话​

SSE 连接会在多个请求之间保留状态,因此 APISIX 为 SSE 保存的会话信息比为 Streamable HTTP 保存的更多。

范围行为
会话身份会话归属于建立它的路由,以及经过身份验证的消费者(如果有)。来自其他路由或消费者的请求会被拒绝
目标地址和请求头APISIX 在打开流时确定 API 目标地址和配置的请求头,并在该会话中复用这些值。会话可在内存中保留最多 30 分钟。Streamable HTTP 会按请求确定这些值
网关实例会话状态保存在单个 APISIX 实例中。请配置会话亲和性,让流和消息请求到达同一实例
连接容量每个流会占用一个连接,直到关闭或达到存续时间上限。请对不可信客户端可以访问的路由应用 limit-conn

排查请求被拒绝的问题​

现象可能原因处理方法
浏览器请求返回 403 和源校验错误源未获允许,路由未明确指定匹配的主机,或协议、端口不同将可信源添加到 allowed_origins,同时考虑 TLS 终止方式和外部端口
外部引用变成通用对象目标不属于同源且未获允许,或无法获取或解析只将所需主机添加到 allowed_ref_hosts,然后检查 APISIX 警告日志和网络连通性
工具参数或请求头未转发操作没有声明该参数或请求头,请求头受到保护,或名称、值无效修正 OpenAPI 操作定义,或在路由上配置请求头
工具调用报告路径参数无效参数值包含不允许的分隔符,或形成空路径段或点路径段将值限制在单个路径段内,或仅针对兼容的上游启用编码分隔符
工具发现返回错误文档无法访问、过大、无效,或没有可用的 paths 对象检查文档 URL、响应状态、格式、大小和 APISIX 错误日志
工具响应报告 RESPONSE_TOO_LARGE上游响应超过配置的响应体大小限制缩小响应,或在评估网关内存用量后提高限制
SSE 消息报告找不到会话请求到达其他实例或路由,来自其他消费者,或会话已过期检查会话亲和性、路由选择、身份验证和会话存续时间
工具发现重复报错

APISIX 会在处理请求的工作进程中将失败的工具发现结果缓存五秒。这段时间内,同一进程收到的请求会返回相同的缓存错误,且不会重新获取文档或再次写入相同的错误日志。五秒后,下一个请求会重试工具发现。

关于如何创建路由和发送客户端请求,请参阅 OpenAPI to MCP。