服务注册与分布式协调 / 系统课时
把 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;否则目录里的声明即使发布成功,也可能把请求转到错误路径。
curl -sS "http://<HOST>:<PORT>/api/v1/inventory/SKU-42?warehouse=sh"预期输出
{"sku":"SKU-42","warehouse":"sh","available":37}<HOST> 与 <PORT> 替换为实际服务地址;库存数字会随数据变化,但字段名与类型应符合接口契约。
拆清 Server、Tool 与 Endpoint
MCP Server 表示一组可发现的能力,Tool 描述模型能调用什么以及需要哪些输入,Endpoint 则告诉协议转换层真正把 HTTP 请求发到哪里。对存量 API 来说,还要单独保留协议转换配置,把工具参数放回 path、query、header 或 body。

| 元数据 | 本例应声明的内容 | 作用 |
|---|---|---|
| MCP Server | inventory-mcp、对外协议、版本与说明 |
给 Agent 一个稳定的能力入口 |
| Tool | get_inventory、描述、inputSchema、启用状态 |
让模型知道何时调用以及传什么 |
| Endpoint | REF 指向现有 inventory-service |
让网关找到真实后端实例 |
| 协议转换 | GET、接口路径和参数位置 |
把工具调用还原成 HTTP 请求 |
已经注册在 Nacos 服务发现中的后端优先使用服务引用,而不是把单个实例 IP 写进工具定义。这样实例扩缩容时,MCP 元数据不需要跟着每个地址变化。
写出一份可审阅的声明
下面是片段示例,用来把一项工具的关键声明放在一起审阅;它不是 Nacos Admin API 的直接请求体。实际录入时,在 MCP Server 页面分别填写服务信息、Tool 输入定义、协议转换配置和后端服务引用。
{
"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 时仍能保持清晰。