服务注册与分布式协调 / 系统课时
完成内部 MCP 目录综合演练
完成内部 MCP 目录综合演练
本节把注册、版本、权限与路由能力串成一个可验收的内部 MCP 目录:自研服务自动注册,存量 HTTP API 转成工具,Agent 统一经 Router 调用,并用发布切换、实例下线和恢复演练验证治理链路。
学习目标
- 搭建同时容纳自研 MCP Server 与存量 HTTP API 的内部服务目录。
- 配置版本、命名空间和最小权限,让 Agent 只通过 Router 发现并调用工具。
- 用发布切换、实例下线和重新注册验证目录在变更与故障下的行为。
规划目录与验收拓扑
本次使用独立命名空间 mcp-prod。目录中放两个资源:自研的 inventory-mcp 提供库存查询工具;已有的 customer-http 通过 MCP 声明与协议转换暴露为 customer-directory。运行时 Agent 不直接保存这两个服务的地址,只连接 Nacos MCP Router。

验收时重点观察三条链路:资源能否进入同一目录;Router 是否只能读取已授权资源;资源版本或实例状态变化后,Agent 的新调用是否命中当前可用端点。
接入自研 MCP 服务
先用 Nacos MCP Wrapper Python 启动一个最小服务。若环境还没有依赖,先安装并立即做导入检查。
# 安装后直接导入模块,避免只看到 pip 成功却无法运行。
python -m pip install -q nacos-mcp-wrapper-python >/dev/null 2>&1 && python -c "import nacos_mcp_wrapper; print('nacos-mcp-wrapper ready')"预期输出
nacos-mcp-wrapper ready将下面代码保存为 inventory_mcp.py;实际环境通过变量注入 Nacos 地址、凭据、命名空间和实例端口,避免把生产凭据写入源码。
import os
from nacos_mcp_wrapper.server.nacos_mcp import NacosMCP
from nacos_mcp_wrapper.server.nacos_settings import NacosSettings
settings = NacosSettings()
# 运行参数从环境变量注入,避免把生产地址和凭据写死。
settings.SERVER_ADDR = os.getenv("NACOS_ADDR", "127.0.0.1:8848")
settings.NAMESPACE = os.getenv("NACOS_NAMESPACE", "mcp-prod")
settings.USERNAME = os.getenv("NACOS_USERNAME", "")
settings.PASSWORD = os.getenv("NACOS_PASSWORD", "")
port = int(os.getenv("MCP_PORT", "18001"))
# 服务名和版本进入目录,端口只标识当前运行实例。
mcp = NacosMCP(
"inventory-mcp",
nacos_settings=settings,
version="1.0.0",
port=port,
)
@mcp.tool()
def get_stock(sku: str) -> dict:
"""Return a deterministic stock record for the exercise."""
# 工具返回结构化结果,便于 Agent 继续处理库存状态。
stock = {"SKU-001": 12, "SKU-002": 0}
return {"sku": sku, "available": stock.get(sku, 0)}
if __name__ == "__main__":
print(f"inventory-mcp starting: version=1.0.0 port={port}", flush=True)
mcp.run(transport="streamable-http")预期输出
inventory-mcp starting: version=1.0.0 port=18001进程随后持续运行。进入 mcp-prod 的 MCP 列表确认出现 inventory-mcp,并检查版本为 1.0.0、工具为 get_stock、端点对应当前实例。若同一版本启动时报兼容性错误,不要直接改已有版本的工具结构;工具名、参数或协议发生不兼容变化时应提升版本号。
为了验证实例级容错,可再用不同端口启动第二个进程,但保持 MCP 名称、版本和工具定义一致。
# 第二个实例保持同名同版本,只改变运行端口。
MCP_PORT=18002 python inventory_mcp.py预期输出
inventory-mcp starting: version=1.0.0 port=18002实际日志还会包含框架输出,内容可能随依赖版本不同;验收以 Nacos 中能看到两个可用端点为准。
把存量 HTTP API 纳入目录
假设已有 customer-http 服务已经注册到 Nacos,并提供按客户 ID 查询资料的 HTTP 接口。无需重写业务服务,先在 MCP 管理中创建 customer-directory:协议选择 sse 或 streamable,后端选择已有服务 customer-http,服务版本设为 1.0.0。
随后新增工具 get_customer,把真实 HTTP 路径、方法和参数映射填写到协议转换配置,并给 customer_id 写清类型与含义。保存只是保留编辑结果;供运行时读取的版本需要发布为最新版本。数据面使用 Higress 等支持 MCP 协议转换的网关时,还要确认它已经把 Nacos 设为 MCP 管理来源。

可以直接从网关侧验证转换后的 SSE 入口。下面的 <HOST>、<PORT> 和响应中的 <ID> 都以实际环境为准。
# 这里只验证协议转换入口;实际 HOST 和 PORT 以网关地址为准。
curl -N --max-time 12 "http://<HOST>:<PORT>/mcp/customer-directory/sse"预期输出
event: endpoint
data: /mcp/customer-directory?sessionId=<ID>若没有 endpoint 事件,先查 customer-directory 是否已经发布为最新版本,再查网关是否读取了正确命名空间,最后确认 customer-http 至少有一个健康实例。
配置权限并让 Agent 走 Router
生产目录不要让 Agent 使用发布者账号。至少拆成两类身份:发布者对 mcp-prod 有写权限,用于创建和更新 MCP 资源;Router 运行身份只授予该命名空间的读权限。若启用了 AI 资源可见性控制,再把可见范围收紧到 Agent 需要调用的 MCP Server,避免“能登录就能搜到全部工具”。
启动 Router 时让它指向同一命名空间。示例使用 Streamable HTTP 对外提供 Router,本机端口固定为 8000;生产环境可换成受管进程或容器。
# Router 使用只读运行身份,发布账号不要复用到 Agent 侧。
export NACOS_ADDR=127.0.0.1:8848
export NACOS_NAMESPACE=mcp-prod
export NACOS_USERNAME=router-reader
export NACOS_PASSWORD='<PASSWORD>'
export TRANSPORT_TYPE=streamable_http
export PORT=8000
printf 'router target=%s namespace=%s port=%s\n' "$NACOS_ADDR" "$NACOS_NAMESPACE" "$PORT"
uvx nacos-mcp-router@latest预期输出
router target=127.0.0.1:8848 namespace=mcp-prod port=8000随后 Router 持续运行;实际启动日志会随版本变化,不作为验收条件。只要进程保持运行,并且 Agent 能连接 http://<HOST>:8000/mcp,就可以继续验收。
让 Agent 只加载 Router,并按顺序调用 Router 的三个能力:先用 search_mcp_server 按任务描述找到 inventory-mcp 或 customer-directory,再用 add_mcp_server 建立目标连接,最后通过 use_tool 调用真实工具。这样 Agent 不需要固化每个后端的地址,目录中的版本、端点和可见性变化也不会散落到 Agent 配置里。
验证发布切换与故障恢复
先为 inventory-mcp 准备 1.1.0,保持兼容的工具输入输出,只修改实现或增加经过评审的新能力,并将它发布为最新版本。随后重新执行 Router 搜索和安装流程,确认新会话读取到 1.1.0。如果新版本有回归,不要修改已经发布的 1.1.0 结构;以 1.0.0 的稳定实现为基线生成修复版本,例如 1.1.1,再发布为最新版本。
实例故障按“单实例下线”和“全部下线后恢复”两级验证。先停止端口 18001 的进程,保留 18002;Agent 再次调用 get_stock 应仍能成功。然后停止第二个实例,调用应明确失败,而不是返回伪造业务结果。完成全部下线后,用下面命令终止最后一个目标进程并重新启动一个实例,等待它重新注册后再次调用。
# <ID> 替换为最后一个待下线实例的实际 PID,随后重启一个端点。
kill -TERM <ID>
MCP_PORT=18001 python inventory_mcp.py预期输出
inventory-mcp starting: version=1.0.0 port=18001<ID> 是待下线进程的实际 PID。故障恢复的验收点不是“Router 永远不报错”,而是目录能及时反映可用端点:有健康实例时继续路由,无健康实例时失败可见,实例重新注册后新调用能够恢复。
最终检查四项结果:两个来源不同的服务都出现在 mcp-prod;Router 账号只有运行时读取权限;Agent 通过 Router 能调用两个目录项;版本切换、单实例下线和重新注册都能得到与预期一致的可观察结果。