跳到主要内容

静态配置​

默认情况下，该插件将 MCP 流量代理到位于 127.0.0.1:3000 的 OpenAPI-to-MCP 服务。

需要更新的文件取决于网关的部署方式：

对于主机或 Docker 部署，请配置以下设置：

config.yaml
plugin_attr:
  openapi-to-mcp:
    port: 4000

然后重新加载网关，使静态配置更改生效。

在 Helm 之外更改此值时，还必须更新 OpenAPI-to-MCP 服务，使其监听同一端口，否则插件将返回 503 错误。

参数​

有关所有插件均可使用的配置项，请参阅插件通用配置。

  • transport

    string

    默认值：sse

    有效值：

    sse 或 streamable_http

    客户端与服务器之间的传输方式。生产部署建议使用 streamable_http，因为它支持适用于多个网关实例的无状态通信。sse 是有状态传输，在部署多个网关时可能出现非预期行为。

    streamable_http 传输方式自 API7 企业版 3.8.15 起可用。

  • openapi_url

    string

    必填

    定义要通过 MCP 暴露的 API 结构的 OpenAPI 规范文档的 URL。

    请注意，该插件仅支持 OpenAPI Specification (OAS) 3 版本。不支持 OpenAPI v2 (Swagger)。

    此外，该插件在处理从 openapi_url 获取的 OpenAPI v3 文档中的 oneOf 架构时存在已知的解析问题。在这种情况下，MCP 客户端将在加载工具时卡住。

    OpenAPI-to-MCP 服务会以该 URL 字符串为键缓存文档，默认保留 3600 秒。如需让变更后的文档立即生效，请修改 URL（例如查询参数）。参见 OpenAPI 文档缓存。

  • base_url

    string

    必填

    请求转发到的 API 服务的基础 URL。支持在值中使用内置变量（从 API7 企业版 3.8.19 版本开始可用），例如 https://${http_baseurl}.swagger.io。

  • allowed_hosts

    array[string]

    有效值：

    精确主机名或通配符主机名，例如 api.example.com 和 *.example.com

    可选的主机 allow-list，用于限制解析后的 base_url 可访问的目标主机。设置后，解析后的主机不在列表中的请求会被拒绝并返回 HTTP 400。自 API7 Enterprise 版本 3.9.13 起可用，APISIX 中暂不可用。

  • headers

    object

    包含在发往上游服务的请求中的请求头。支持在值中使用内置变量，例如 $arg_username-$http_apikey。

  • flatten_parameters

    boolean

    默认值：false

    是否在工具 Schema 中扁平化参数。查询参数和路径参数扁平化自 API7 企业版 3.8.21 起可用；对 OpenAPI 规范中定义的请求头参数（in: header）的支持自 3.9.8 起可用。APISIX 暂不支持。

    设置为 false 时，查询参数嵌套在 queryParameters 下，路径参数嵌套在 pathParameters 下；自 API7 企业版 3.9.8 起，请求头参数嵌套在 headerParameters 下。设置为 true 时，查询参数和路径参数直接放在 properties 下；自 3.9.8 起，请求头参数也直接放在 properties 下。

    将此参数设置为 true 可降低 Schema 复杂度，简化 AI 模型交互。当查询参数、路径参数和请求头参数存在同名项时，请保持为 false 以避免冲突。