跳到主要内容

静态配置​

默认情况下，该插件将 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 客户端将在加载工具时卡住。

    api7/openapi-to-mcp:1.0.2 默认缓存文档及生成的工具定义 3600 秒；该 URL 是缓存键的组成部分。修改 URL 可在下次加载规范时避开旧缓存，但不会自动更新已有会话中的工具。自 API7 企业版 3.9.21 起，也可以通过 cache_enabled 和 cache_ttl 按路由调整缓存。参见 OpenAPI 文档缓存。

  • base_url

    string

    必填

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

  • allowed_hosts

    array[string]

    有效值：

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

    可选的主机允许列表，用于限制解析后的 base_url 可访问的目标主机。设置后，解析后的主机不在列表中的请求会被拒绝并返回 HTTP 400。自 API7 企业版 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 以避免冲突。

  • cache_enabled

    boolean

    默认值：true

    OpenAPI-to-MCP 服务是否缓存该路由的 OpenAPI 文档及据此生成的工具。设置为 false 时，服务每次加载工具都会重新下载并解析文档，适用于仍在变化的文档。

    需要 api7/openapi-to-mcp 边车 1.0.5 或更高版本。更早版本的边车会忽略此参数，并使用其自身的 CACHE_ENABLED 设置。

    自 API7 企业版 3.9.21 起可用。

  • cache_ttl

    integer

    默认值：3600

    有效值：

    大于或等于 1

    该路由的 OpenAPI 文档及据此生成的工具在 OpenAPI-to-MCP 服务缓存中保留的秒数。

    需要 api7/openapi-to-mcp 边车 1.0.5 或更高版本。更早版本的边车会忽略此参数，并使用其自身的 CACHE_TTL 设置。

    自 API7 企业版 3.9.21 起可用。