服务注册与分布式协调 / 系统课时

把 HTTP 接口声明成 MCP 工具

把 HTTP 接口声明成 MCP 工具

这一节把一个已经可用的库存查询 HTTP 接口登记为 MCP 能力:先确认原接口契约,再拆分 MCP Server、Tool 与 Endpoint 三层元数据,最后检查 Agent 能否从目录中看懂能力并定位到真实调用目标。

学习目标

  • 能区分 MCP Server、Tool 与 Endpoint 在存量 API 转换中的职责
  • 能为现有 HTTP 接口填写工具描述、请求方法、路径和服务引用
  • 能用原始 HTTP 请求核对 MCP 声明是否指向正确后端

从真实接口反推工具

先把真实接口当作唯一事实来源。假设已有库存服务提供 GET /api/v1/inventory/{sku},并用查询参数 warehouse 指定仓库。先直接调用后端,确认方法、路径、参数名和返回字段都稳定,再设计 MCP Tool;否则目录里的声明即使发布成功,也可能把请求转到错误路径。

bash
curl -sS "http://<HOST>:<PORT>/api/v1/inventory/SKU-42?warehouse=sh"

预期输出

json
{"sku":"SKU-42","warehouse":"sh","available":37}

<HOST> 与 <PORT> 替换为实际服务地址;库存数字会随数据变化,但字段名与类型应符合接口契约。

拆清 Server、Tool 与 Endpoint

MCP Server 表示一组可发现的能力,Tool 描述模型能调用什么以及需要哪些输入,Endpoint 则告诉协议转换层真正把 HTTP 请求发到哪里。对存量 API 来说,还要单独保留协议转换配置,把工具参数放回 path、query、header 或 body。

存量 HTTP API 转换为 MCP 工具的数据流

元数据 本例应声明的内容 作用
MCP Server inventory-mcp、对外协议、版本与说明 给 Agent 一个稳定的能力入口
Tool get_inventory、描述、inputSchema、启用状态 让模型知道何时调用以及传什么
Endpoint REF 指向现有 inventory-service 让网关找到真实后端实例
协议转换 GET、接口路径和参数位置 把工具调用还原成 HTTP 请求

已经注册在 Nacos 服务发现中的后端优先使用服务引用,而不是把单个实例 IP 写进工具定义。这样实例扩缩容时,MCP 元数据不需要跟着每个地址变化。

写出一份可审阅的声明

下面是片段示例,用来把一项工具的关键声明放在一起审阅;它不是 Nacos Admin API 的直接请求体。实际录入时,在 MCP Server 页面分别填写服务信息、Tool 输入定义、协议转换配置和后端服务引用。

json
{
  "server": {
    "name": "inventory-mcp",
    "frontProtocol": "streamable",
    "version": "1.0.0"
  },
  "tool": {
    "name": "get_inventory",
    "description": "按 SKU 和仓库查询当前可用库存",
    "inputSchema": {
      "type": "object",
      "properties": {
        "sku": {
          "type": "string",
          "description": "商品 SKU,例如 SKU-42"
        },
        "warehouse": {
          "type": "string",
          "description": "仓库代码,例如 sh"
        }
      },
      "required": ["sku", "warehouse"],
      "additionalProperties": false
    }
  },
  "endpoint": {
    "type": "REF",
    "data": {
      "namespaceId": "public",
      "groupName": "DEFAULT_GROUP",
      "serviceName": "inventory-service"
    }
  },
  "protocolConversion": {
    "requestTemplate": {
      "url": "/api/v1/inventory/{sku}",
      "method": "GET"
    },
    "responseTemplate": {
      "body": "{{.}}"
    },
    "argsPosition": {
      "sku": "path",
      "warehouse": "query"
    }
  }
}

这里最重要的不是字段堆得多,而是四处保持一致:Tool 的参数名、URL 占位符、argsPosition 的键和真实 HTTP 契约必须完全同名。sku 若在 schema 里改成 productCode,却仍让模板寻找 {sku},调用时就会在协议转换层断掉。

发布前做一致性检查

先检查目录里的 MCP Server 能看到 get_inventory,再逐项核对 Tool 描述、两个必填参数、Endpoint 服务引用和请求模板。随后用前面的 curl 直接验证后端,确保 Nacos 中填写的方法、路径和参数位置与真实接口一致。

完成后,目录承担的是“让 Agent 找到并理解能力”,Endpoint 与协议转换配置承担的是“把调用送到正确的旧接口”。只要这两层不混在一起,后续增加更多存量 API 时仍能保持清晰。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把 HTTP 接口声明成 MCP 工具

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通