服务注册与分布式协调 / 系统课时
通过 Router 代理工具调用
通过 Router 代理工具调用
这一课把一次工具调用拆成可观察的代理链路:先让 Router 从 Nacos MCP Registry 找到候选服务,再初始化目标 MCP Server,最后通过 use_tool 转发工具请求并拿回结果。完成后,你能判断问题究竟出在目录、连接还是目标工具。
学习目标
- 用
search_mcp_server、add_mcp_server、use_tool跑通一次 Router 代理调用 - 区分服务名、版本、端点与实例地址在调用链中的职责
- 根据调用停在哪一步快速定位 Registry、连接配置或工具参数问题
Router 代理的三段式路径
Router 模式下,Nacos MCP Router 本身就是一个 MCP Server,向客户端暴露搜索、添加和代理调用等工具;客户端不需要先拿到目标服务的固定 IP 再直连。官方手册列出的三个主要工具正是 search_mcp_server、add_mcp_server 与 use_tool。([Nacos 官网][1])

三步的职责不能混在一起:搜索决定“有哪些候选”,添加决定“怎样连接这个服务”,代理调用才决定“调用哪个工具以及传什么参数”。因此,search_mcp_server 成功并不代表目标 MCP Server 已经可调用,add_mcp_server 成功也不代表具体工具参数一定正确。
服务名、版本、端点与实例地址如何协同
| 信息 | 主要作用 | 调用方是否直接传入 |
|---|---|---|
| 服务名 | 标识一个逻辑 MCP Server,是 Router 后续定位目标的稳定键 | 是,add_mcp_server 与 use_tool 都使用 |
| 版本 | 控制 Registry 中服务与工具定义的治理版本、可见性和演进 | 通常不是 use_tool 的直接参数 |
| 端点 | 描述 Router 应使用的传输入口,例如远端 MCP 地址或本地启动配置 | 由 Registry/服务配置提供 |
| 实例地址 | 表示本次真正连接到的运行实例;在动态服务发现场景可随实例上下线变化 | 通常由发现与连接过程解析 |
关键点是:Agent 应依赖“服务名 + 工具名”表达意图,而不是把某个实例 IP 写死。版本和端点属于 Registry 的治理与连接信息;当端点背后还有 Nacos 服务发现时,Router 才需要进一步解析实际实例。对于直接 URL 或本地 stdio 服务,这一层可能会合并为直接连接,不能把“实例选择”当成所有 MCP 类型都必经的固定步骤。
执行一次完整代理调用
下面的脚本使用 MCP Python SDK 连接一个已经以 Streamable HTTP 暴露的 Router。运行前需要准备 ROUTER_URL、MCP_SERVER_NAME、MCP_TOOL_NAME;如果目标工具需要参数,再用 MCP_TOOL_PARAMS 提供 JSON 对象。目标服务必须已经登记在 Nacos MCP Registry 中。
import asyncio
import json
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from mcp.types import TextContent
ROUTER_URL = os.environ["ROUTER_URL"]
TARGET_SERVER = os.environ["MCP_SERVER_NAME"]
TARGET_TOOL = os.environ["MCP_TOOL_NAME"]
TARGET_PARAMS = json.loads(os.getenv("MCP_TOOL_PARAMS", "{}"))
TASK_DESCRIPTION = os.getenv(
"TASK_DESCRIPTION",
"调用一个已注册的 MCP 工具完成当前任务",
)
KEY_WORDS = os.getenv("TASK_KEY_WORDS", "mcp,tool")
def result_text(result) -> str:
texts = [
block.text
for block in result.content
if isinstance(block, TextContent)
]
if texts:
return "\n".join(texts)
if result.structured_content is not None:
return json.dumps(result.structured_content, ensure_ascii=False)
return "<EMPTY_RESULT>"
async def main() -> None:
async with streamable_http_client(ROUTER_URL) as (read_stream, write_stream):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
listed = await session.list_tools()
names = {tool.name for tool in listed.tools}
required = {"search_mcp_server", "add_mcp_server", "use_tool"}
print("router ready:", required.issubset(names))
searched = await session.call_tool(
"search_mcp_server",
{
"task_description": TASK_DESCRIPTION,
"key_words": KEY_WORDS,
},
)
print("search:", result_text(searched))
added = await session.call_tool(
"add_mcp_server",
{"mcp_server_name": TARGET_SERVER},
)
print("add:", result_text(added))
called = await session.call_tool(
"use_tool",
{
"mcp_server_name": TARGET_SERVER,
"mcp_tool_name": TARGET_TOOL,
"params": TARGET_PARAMS,
},
)
print("tool:", result_text(called))
if __name__ == "__main__":
asyncio.run(main())预期输出(尖括号内容取决于当前 Registry、目标服务和工具返回值):
router ready: True
search: <SEARCH_RESULT>
add: <TARGET_TOOL_LIST_AND_USAGE>
tool: <TARGET_TOOL_RESULT>MCP Python SDK 的 Streamable HTTP 客户端在建立会话后通过 list_tools() 获取工具定义,并用 call_tool(name, arguments) 发起调用;这正好可以把 Router 当作普通 MCP Server 使用。([GitHub][2])
按失败阶段定位问题
如果 search_mcp_server 没有找到预期服务,先检查 Router 使用的 Nacos 地址、命名空间、服务可见性以及搜索关键词,此时还没有进入目标服务连接阶段。
如果搜索成功但 add_mcp_server 失败,重点检查该服务在 Registry 中的传输类型、端点或本地启动配置,以及目标服务自身是否可达。add_mcp_server 的职责就是按 Nacos 中的配置初始化并建立连接,失败通常不应先去修改业务工具参数。([Nacos 官网][1])
如果添加成功而 use_tool 失败,再检查 mcp_tool_name 是否仍在当前工具列表中、参数是否满足该工具 schema,以及 Registry 中的版本或工具可见性是否刚发生变化。调用方只持有逻辑服务名时,实例替换通常不需要改 Agent 配置;真正需要重新确认的是 Router 当前解析到的服务定义和连接。