将 REST API 暴露为 MCP 工具

MCP 服务器注册项可以由普通 REST API 提供支持，而不必连接上游 MCP 服务器。注册 API 的 OpenAPI 3.x 文档并将 type 设置为 openapi 后，AISIX 会为每个操作生成一个 MCP 工具。执行 tools/call 时，AISIX 会向 API 的基础 URL 发出 HTTP 请求并附加网关保存的凭证——MCP 调用方不会获得该凭证，API 本身也无需实现 MCP 服务器。

这样即可把现有内部服务（例如 ERP、库存系统或薪资 API）转化为 Agent 可调用的工具，并应用与其他 MCP 工具相同的治理能力：服务器审核、工具访问控制、访问策略、流量控制、安全护栏和可观测性均保持不变。

工具生成方式

AISIX 会遍历文档中的 paths，并为 get、post、put、delete 和 patch 方法的每个操作生成一个工具：

工具名称：使用操作的 operationId 并转换为小写，将 a-z、0-9、_ 和 - 以外的字符替换为 _，且最多保留 128 个字符。没有 operationId 的操作会按相同规则命名为 <method>_<path>。与所有 MCP 工具一样，对调用方暴露的名称为 <server-name>__<tool-name>。
输入 Schema：每个 path 和 query 参数都会成为属性，并保留其类型、描述、enum 值和 required 标记。JSON 请求体会成为单个 body 对象属性，并在规范要求时标记为必填。AISIX 会解析本地 $ref，包括请求体中引用的组件 Schema，使 Agent 能看到真实的数据结构。请求头和 Cookie 参数不会暴露给调用方，因为上游请求头由网关管理。
跳过的操作：如果操作的请求体没有 application/json 变体（例如 multipart/form-data 文件上传），AISIX 会跳过该操作，避免生成无法成功执行的工具。

注册时会验证文档，并在失败时返回原因。无法解析的文档、Swagger 2.0 文档（应先转换为 OpenAPI 3.x）、没有可生成工具操作的文档，以及工具名规范化后发生冲突的 operationId（例如 foo/list 和 foo.list 都会映射为 foo_list）都会被拒绝。生成的工具名会通过服务器的 tool_names 字段返回，因此可以在授予访问权限前核对工具范围。

注册 REST API

可以通过以下两种方式提供文档：

spec_content：以 JSON 或 YAML 文本提供文档本身。控制面无法访问 API 所在网络时使用此方式。
spec_url：提供由控制面在注册时仅获取一次的 URL。获取的文档会经过验证、规范化并存储；数据面不会再次获取，因此只有更新注册项后工具集才会变化。在 AISIX Cloud 中，解析到非公网地址的 URL 会被拒绝。On-Premises 部署可以在控制面设置 AISIX_CLOUD_MCP_SPEC_ALLOW_PRIVATE_URLS=true 以允许此类 URL，也可以直接粘贴文档。

文档大小上限为 1 MiB。

url 是 REST API 的基础 URL，生成的工具调用会发送到 <url><path>。

curl -sS -X POST "$AISIX_CLOUD_URL/api/mcp_servers" \
  -H "Authorization: Bearer $AISIX_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp",
    "type": "openapi",
    "url": "https://erp.internal/api/v1",
    "spec_url": "https://erp.internal/api/v1/openapi.json",
    "auth_type": "bearer",
    "secret": "erp-service-token",
    "allowed_environments": ["'$AISIX_ENV_ID'"]
  }'

响应中包含生成的 tool_names：

{
  "mcp_server": {
    "name": "erp",
    "type": "openapi",
    "url": "https://erp.internal/api/v1",
    "tool_names": ["getitem", "createorder"],
    "approval_status": "approved"
  }
}

获得 API Key 授权的调用方现在可以通过 /mcp 发现并调用 erp__getitem 和 erp__createorder，其行为与来自真实上游 MCP 服务器的工具完全相同。

在控制台中注册 MCP 服务器时选择 REST API (OpenAPI)，然后按需粘贴文档、提供 URL，或通过 Choose file… 选择本地 .json 或 .yaml 文件。选择的文件会读入编辑器，因此可以在保存前检查和调整。

审核生成的工具

每个已注册服务器的卡片会列出前几个生成的工具名，并链接到该服务器的工具页面。该页面列出全部工具及以下信息：

<server>__<tool> 形式的名称，可以复制到 API Key 的工具白名单或访问策略模式中；
工具调用的 HTTP 操作，例如 GET /items/{id}；
工具描述。

也可以通过 API 获取相同的列表：

curl -sS "$AISIX_CLOUD_URL/api/mcp_servers/$MCP_SERVER_ID/tools" \
  -H "Authorization: Bearer $AISIX_ADMIN_TOKEN"

{
  "data": [
    {
      "name": "getitem",
      "namespaced_name": "erp__getitem",
      "method": "GET",
      "path": "/items/{id}",
      "description": "Fetch one item"
    }
  ]
}

该列表根据已存储文档生成，因此始终与网关提供的工具一致。它只适用于 type: openapi 的服务器；上游 MCP 服务器的工具由上游提供，对此类服务器调用该端点会返回 400。

REST API 身份认证

上游身份认证模式可以直接使用；AISIX 会把凭证附加到每次生成的工具调用：

bearer：发送 Authorization: Bearer <secret>。
api_key：发送 secret 中的 Key，默认使用 x-api-key 请求头。REST API 通常需要自定义请求头，可以设置 api_key_header（例如 X-ERP-Key）覆盖请求头名称。该字段只适用于 auth_type: api_key 的 openapi 服务器。
oauth2：AISIX 使用配置的客户端凭证获取访问 Token，并以 Bearer 形式发送；Token 缓存行为与 MCP 上游相同。

生成的工具调用绝不会跟随重定向，因此凭证不会被重新发送到未配置的主机。

调用结果和错误

成功响应的正文会作为工具结果文本返回。非 2xx 响应会返回工具级错误结果（isError: true），其中包含 HTTP <status> 和响应正文，以便 Agent 识别并处理失败。参数错误（例如缺少必填路径参数，或路径参数包含 / 或 ..，后者会被拒绝以确保请求保持在配置路径内）也会以同样易读的方式报告。

更新文档

替换文档会重新执行验证并生成工具列表。更新时提供 spec_content 或 spec_url，也可以在控制台中使用 Replace OpenAPI document 编辑器。调用返回后，新的工具范围会立即发布。调用方拥有批准服务器的权限，因此本次替换本身即视为审核；按照服务器审核工作流，reviewed_by 和 reviewed_at 会更新为该调用方。只有 mcp_server_submissions write 权限的角色会改为暂存替换内容，现有工具会继续提供服务，直到审核者批准变更。修改 api_key_header 的行为相同。重新上传规范化后与已存储版本相同的文档不会被视为变更。

服务器的 type 在创建时固定。若要在 MCP 上游和 OpenAPI 后端之间切换，请删除原注册项并重新注册。

工具生成方式​

注册 REST API​

审核生成的工具​

REST API 身份认证​

调用结果和错误​

更新文档​