服务注册与分布式协调 / 系统课时
描述端点、工具与资源
描述端点、工具与资源
这一节把 MCP Server 从“有一个目录项”补成“Agent 能理解和选择的能力描述”。你会拆分 endpoint、tool 与 resource 的职责,写清工具参数契约,并通过查询结果检查服务级元数据与能力级描述是否一致。
学习目标
- 区分服务级元数据、端点、工具契约与资源描述的职责。
- 用清晰的名称、描述和参数 Schema 提高 Agent 选工具的准确性。
- 核对 Nacos 中保存的能力描述与 MCP Server 运行时暴露内容是否一致。
把四层信息分开
MCP Server 的名称、版本和描述回答“这是什么服务”;endpoint 回答“到哪里连接”;tool 回答“可以执行什么动作、需要哪些参数”;resource 回答“可以读取什么上下文数据”。Nacos AI Registry 把 MCP Server、工具、资源和端点放进统一目录,而 MCP 客户端会进一步通过工具列表和资源列表理解具体能力。([Nacos 官网][1])

这四层不要互相代替。尤其不要把“天气服务”这种宽泛说明只写在 Server 描述里,却把工具描述留空;模型真正选择工具时,最直接看到的是工具的 name、description 和 inputSchema。([Nacos 官网][2])
写清工具契约
以 get_weather 为例,名称应稳定且表达动作;描述要说明返回什么,而不是重复名称;inputSchema 要把参数类型、必填项和语义写清。Nacos 的 MCP 工具模型包含 name、description 与 inputSchema,工具还可以通过扩展元数据控制启用状态等行为。([Nacos 官网][5])
片段示例:下面是字段建模对照稿,不是可以直接提交给 Nacos API 的完整请求体;它用于在控制台编辑时检查各层信息是否放对位置。
{
"server": {
"name": "weather-mcp",
"description": "提供城市天气查询与支持城市数据"
},
"endpoint": {
"protocol": "streamable",
"address": "<HOST>",
"port": "<PORT>"
},
"tool": {
"name": "get_weather",
"description": "根据城市标识查询当前天气",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市标识,例如 hangzhou"
}
},
"required": ["city"]
}
},
"resource": {
"uri": "weather://cities/supported",
"name": "supported_cities",
"description": "返回天气服务支持的城市标识集合",
"mimeType": "application/json"
}
}这里的 Tool Schema 使用 JSON Schema 描述输入;Resource 则用稳定 URI 标识可读取内容,并补充名称、描述和 MIME 类型。这些字段能让客户端在调用前知道“参数怎么给”和“资源是什么”。([MCP Python SDK][6])
在 Nacos 中补齐并核对
回到 weather-mcp 的详情或编辑页,把 endpoint 与真实服务保持一致,在工具区域新增 get_weather,复制同样的描述与参数约束,并开启该工具。资源能力是否能在控制台直接编辑取决于具体 Nacos 3.x 次版本;如果当前版本没有资源明细编辑区,不要自行编造未支持的字段,而应先保证运行时 MCP Server 的资源列表确实暴露 weather://cities/supported,再核对目录对象声明了相应能力。Nacos 稳定版管理模型会返回 capabilities,其中可包含 TOOL、PROMPT 和 RESOURCE。([Nacos 官网][3])
保存后,用只读查询确认工具已经进入目录。<TOKEN> 需要具备对应命名空间的读取权限。
curl -sS 'http://<HOST>:<PORT>/nacos/v3/admin/ai/mcp?namespaceId=public&mcpName=weather-mcp' -H 'Authorization: Bearer <TOKEN>' | jq '{capabilities: .data.capabilities, tools: [.data.toolSpec.tools[] | {name, description, inputSchema}]}'预期结果
{
"capabilities": [
"TOOL",
"RESOURCE"
],
"tools": [
{
"name": "get_weather",
"description": "根据城市标识查询当前天气",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市标识,例如 hangzhou"
}
},
"required": [
"city"
]
}
}
]
}能力数组的顺序可能不同,但应至少看到你实际启用的能力;工具的名称、描述和参数 Schema 应与服务端契约一致。若 toolSpec 为空,先检查目录项是否声明了 TOOL 能力、工具是否保存成功,以及当前查询的版本是否正确。([Nacos 官网][3])
让描述真正帮助 Agent 选择
工具描述要写成“什么时候用 + 做什么”,参数描述要消除单位、格式和枚举歧义。get_weather 比 weather 更像一个可执行动作,“根据城市标识查询当前天气”也比“天气工具”更能帮助模型判断调用时机。
Resource 则更适合暴露可读取、可复用的上下文,例如支持城市清单、配置说明或静态知识;不要把本应执行副作用的动作伪装成 Resource。最终以运行时 MCP Server 实际返回的工具与资源列表为准,再让 Nacos 目录中的描述保持同步,这样 Agent 才不会“发现得到、调用不对”。