跳到主要内容

静态配置​

在 API7 企业版中，该插件默认将 MCP 流量代理到位于 127.0.0.1:3000 的 OpenAPI-to-MCP 服务。以下静态设置仅适用于这种边车部署。APISIX 在网关内处理 MCP，不需要配置边车端口。

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

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

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

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

在 API7 企业版中，请将边车的 SSE_PORT 设置为与 plugin_attr.openapi-to-mcp.port 相同的值。连接该服务被拒绝时通常返回 502，而不是 503。APISIX 的进程内 MCP 实现不使用此边车端口。

参数​

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

  • transport

    string

    默认值：sse

    有效值：

    sse 或 streamable_http

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

    Streamable HTTP 在 API7 企业版 3.8.15 和 APISIX 3.19.0 中引入。使用 SSE 部署多个网关实例时，需要会话亲和性。

  • openapi_url

    string

    必填

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

    APISIX 接受 JSON 或 YAML 格式的 OpenAPI 3.x 文档，并解析内部引用以及绝对 HTTP 或 HTTPS 引用。对 Swagger 2.0 的支持仅为尽力而为，不会把 body 或 form-data 参数转换为工具输入。

    企业版 OpenAPI-to-MCP 服务支持 OpenAPI 3，不支持 Swagger 2.0。它处理 oneOf schema 时存在已知解析问题，可能使客户端一直停留在工具加载状态。

    生成的工具按此 URL 缓存。如需立即加载已更改的文档，请修改 URL，例如添加版本查询参数。参见配置 OpenAPI 文档缓存。

  • base_url

    string

    必填

    请求转发到的 API 服务基础 URL。内置变量支持在 API7 企业版 3.8.19 和 APISIX 3.19.0 中引入；请参阅 API7 网关变量和 APISIX 变量。在 APISIX 中请确保此 URL 由运维人员控制，因为 APISIX 未实现企业版的 allowed_hosts 限制。

  • allowed_hosts

    array[string]

    有效值：

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

    可选的主机允许列表，用于限制解析后的 base_url 可访问的目标主机。设置后，解析后的主机不在列表中的请求会被拒绝并返回 HTTP 400。该字段在 API7 企业版 3.9.13 中引入，APISIX 3.19.0 不支持。

  • headers

    object

    包含在发往上游服务的请求中的请求头。值可使用 API7 网关变量或 APISIX 变量，例如 $http_x_api_key。APISIX 会在每个 SSE 会话中解析一次变量，并为每个 Streamable HTTP 请求解析变量。原生 APISIX 不会自动转发企业版边车使用的 x-openapi2mcp-header-* 客户端请求头。

  • flatten_parameters

    boolean

    默认值：false

    是否在工具 schema 中扁平化参数。查询参数和路径参数扁平化在 API7 企业版 3.8.21 中引入，请求头参数支持在 3.9.8 中引入。APISIX 3.19.0 支持这三种参数位置。

    设置为 false 时，查询、路径和请求头参数分别嵌套在 queryParameters、pathParameters 和 headerParameters 下。设置为 true 时，这些参数直接放在 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 和 3.10.8 中引入，APISIX 3.19.0 不支持。

  • cache_ttl

    integer

    默认值：3600

    有效值：

    大于或等于 1

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

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

    该字段在 API7 企业版 3.9.21 和 3.10.8 中引入，APISIX 3.19.0 不支持。