Nacos-MCP-Router：为你的AI Agent构建智能服务中枢

最近在折腾几个AI驱动的自动化项目时，我遇到了一个挺有意思的痛点：手头管理着十几个不同的MCP服务，从天气查询、地图服务到数据库操作，每个服务都要单独配置到AI Agent里。每次新增或更新一个服务，就得在各个Agent的配置文件中手动修改，不仅繁琐，还容易出错。直到我发现了Nacos-MCP-Router这个项目，它像是一个专门为AI Agent设计的“服务注册中心”，把服务管理的混乱局面彻底理顺了。

简单来说，Nacos-MCP-Router在Nacos这个成熟的服务发现与配置管理平台之上，增加了一层对MCP协议的原生支持。它允许你将各种MCP服务（无论是Stdio类型还是SSE类型）统一注册到Nacos中，然后你的AI Agent（比如Cline、Cursor）只需要连接这一个Nacos-MCP-Router，就能动态发现和使用所有已注册的服务。这意味着，你的Agent不再需要知道每个服务的具体地址和配置细节，它只需要知道“服务中枢”在哪里，就能调用整个服务生态。这对于构建复杂、可扩展的AI应用来说，无疑是一个游戏规则的改变者。

这篇文章，我将从一个实践者的角度，带你从零开始搭建这套体系，并分享一些我在实际项目中踩过的坑和总结的最佳实践。无论你是正在构建企业级的AI助手，还是想让自己的开发工具链更加智能，这套方案都值得你深入了解。

1. 环境准备与Nacos部署

在开始集成MCP-Router之前，我们首先需要一个稳定运行的Nacos服务。Nacos本身是一个功能丰富的动态服务发现、配置和服务管理平台，我们这里主要利用其服务注册与发现的核心能力。

1.1 选择部署方式

Nacos提供了多种部署方式，对于个人开发或测试环境，单机模式（Standalone）是最简单快捷的选择。对于生产环境，则建议采用集群模式以保证高可用性。这里我们以Docker Compose部署单机版为例，这也是官方推荐且最不易出错的入门方式。

首先，在你的工作目录下创建两个关键文件：.env环境变量配置文件和docker-compose.yml服务编排文件。

.env 文件配置 这个文件用于集中管理敏感信息和可变配置，避免硬编码。

# Nacos 认证相关密钥
NACOS_AUTH_TOKEN=eXl5eXl5eXl5eXl5eXl5eXl5eXl5eXl5eXl5eXl5eXl5eQo=
NACOS_AUTH_IDENTITY_KEY=serverIdentity
NACOS_AUTH_IDENTITY_VALUE=securityIdentity

# 宿主机与容器端口映射
HOST_PORT_CONSOLE=8080
CONTAINER_PORT_CONSOLE=8080
HOST_PORT_MAIN=8848
CONTAINER_PORT_MAIN=8848
HOST_PORT_CLIENT_RPC=9848
CONTAINER_PORT_CLIENT_RPC=9848

注意：NACOS_AUTH_TOKEN是用于生成JWT令牌的密钥，必须是一个经过Base64编码的、长度大于32个字符的字符串。你可以使用echo -n "你的长字符串密钥" | base64命令来生成。NACOS_AUTH_IDENTITY_KEY和NACOS_AUTH_IDENTITY_VALUE用于服务端内部通信的身份校验，可按需自定义。

docker-compose.yml 文件配置 这个文件定义了Nacos服务的容器规格。

version: '3.8'
services:
  nacos-standalone:
    image: nacos/nacos-server:latest
    container_name: nacos-standalone
    hostname: nacos-standalone
    environment:
      - MODE=standalone
      - NACOS_AUTH_ENABLE=true
      - NACOS_AUTH_TOKEN=${NACOS_AUTH_TOKEN}
      - NACOS_AUTH_IDENTITY_KEY=${NACOS_AUTH_IDENTITY_KEY}
      - NACOS_AUTH_IDENTITY_VALUE=${NACOS_AUTH_IDENTITY_VALUE}
    volumes:
      - ./standalone-logs/:/home/nacos/logs
      - ./init.d/custom.properties:/home/nacos/init.d/custom.properties
    ports:
      - "${HOST_PORT_CONSOLE}:${CONTAINER_PORT_CONSOLE}"
      - "${HOST_PORT_MAIN}:${CONTAINER_PORT_MAIN}"
      - "${HOST_PORT_CLIENT_RPC}:${CONTAINER_PORT_CLIENT_RPC}"
    restart: unless-stopped
    networks:
      - nacos-network

networks:
  nacos-network:
    driver: bridge

1.2 启动与初始化

配置完成后，在终端中执行以下命令启动服务：

docker-compose up -d

等待片刻，使用docker-compose logs -f查看日志，确认服务启动无误。随后，在浏览器中访问 http://localhost:8080/nacos，你将看到Nacos的控制台登录页面。

首次访问需要初始化一个管理员账户。点击“注册”并设置用户名和密码（例如，用户名nacos，密码nacos）。注册成功后，使用该账户登录，即可进入Nacos的主控制台。这里可能会遇到一个常见的“400错误”重定向问题，通常刷新页面或重新访问登录页即可解决。

登录后，你看到的界面主要分为“服务管理”、“配置管理”和“命名空间”等几个核心模块。我们后续的操作将主要集中在“服务管理”部分。

2. 理解MCP协议与Nacos-MCP-Router的角色

在深入配置之前，有必要厘清几个核心概念，这能帮助你更好地理解整个架构的设计哲学。

MCP（Model Context Protocol） 是一个由Anthropic提出的开放协议，旨在为大型语言模型（LLM）提供一个标准化的方式来与外部工具、数据和系统进行交互。你可以把它想象成LLM世界的“USB协议”——它定义了一套通用的“插口”和“通信规范”，让不同的AI Agent（“电脑”）能够即插即用地使用各种各样的外部服务（“外设”），而无需为每个服务编写特定的适配器。

一个典型的MCP服务架构包含以下组件：

  • MCP Server：提供具体功能的服务端，例如一个提供天气查询API的服务器。
  • MCP Client：通常是AI Agent（如Cline），它通过MCP协议与Server通信。
  • Transport：通信方式，常见的有Stdio（标准输入输出）和SSE（Server-Sent Events）。

那么，Nacos-MCP-Router在这里扮演什么角色呢？它本质上是一个高级的MCP Server，但同时它又充当了MCP服务的注册中心。它的工作流程可以概括为：

  1. 服务聚合：你将各类独立的MCP Server（如地图服务、数据库服务）注册到Nacos中。
  2. 协议转换与路由：Nacos-MCP-Router作为桥梁，一方面以标准MCP Server的身份对接AI Agent，另一方面它又作为Nacos的客户端，从Nacos服务列表中动态获取所有已注册的MCP服务信息。
  3. 统一暴露：当AI Agent连接到Nacos-MCP-Router后，它看到的不是一个单一服务，而是所有在Nacos中注册的MCP服务的“聚合视图”。Agent可以通过Router提供的统一工具来搜索、安装和使用这些后端服务。

这种架构带来了几个显著优势：

优势说明
集中管理所有MCP服务的生命周期（注册、发现、下线）在一个控制台完成，一目了然。
动态更新在Nacos中更新服务配置或新增服务，连接的AI Agent无需重启或修改配置即可感知。
降低复杂度AI Agent只需配置一个连接（指向Router），而非维护一长串服务列表。
提升可观测性可以利用Nacos的健康检查、监控看板等功能，掌握所有MCP服务的运行状态。

3. 注册与管理你的第一个MCP服务

理解了架构，我们开始动手实践。我们将以一个提供城市天气查询的模拟MCP服务为例，演示如何将其注册到Nacos，并最终通过Router被AI Agent调用。

3.1 准备一个示例MCP Server

为了演示，我们使用一个简单的Python脚本来模拟一个天气查询MCP Server。这个Server通过Stdio方式运行，监听JSON-RPC格式的请求。

创建一个名为 weather_mcp_server.py 的文件：

#!/usr/bin/env python3
import json
import sys
import random

def get_weather(city: str) -> dict:
    """模拟获取城市天气信息"""
    # 在实际应用中，这里应调用真实的天气API
    weather_conditions = ["晴", "多云", "阴", "小雨", "中雨", "大雨"]
    temperatures = {
        "北京": random.randint(15, 25),
        "上海": random.randint(18, 28),
        "广州": random.randint(22, 32),
        "深圳": random.randint(23, 33),
    }
    return {
        "city": city,
        "condition": random.choice(weather_conditions),
        "temperature": temperatures.get(city, random.randint(10, 30)),
        "humidity": f"{random.randint(40, 90)}%",
        "unit": "摄氏度"
    }

def main():
    # 简单的MCP Server实现，处理Stdio通信
    while True:
        try:
            line = sys.stdin.readline()
            if not line:
                break
            request = json.loads(line.strip())

            method = request.get("method")
            params = request.get("params", {})

            if method == "tools/list":
                # 列出本Server提供的工具
                response = {
                    "jsonrpc": "2.0",
                    "id": request.get("id"),
                    "result": {
                        "tools": [{
                            "name": "get_weather",
                            "description": "获取指定城市的当前天气信息",
                            "inputSchema": {
                                "type": "object",
                                "properties": {
                                    "city": {
                                        "type": "string",
                                        "description": "城市名称，例如：北京、上海"
                                    }
                                },
                                "required": ["city"]
                            }
                        }]
                    }
                }
            elif method == "tools/call":
                tool_name = params.get("name")
                if tool_name == "get_weather":
                    city = params.get("arguments", {}).get("city", "北京")
                    weather_info = get_weather(city)
                    response = {
                        "jsonrpc": "2.0",
                        "id": request.get("id"),
                        "result": {
                            "content": [{
                                "type": "text",
                                "text": f"{city}的天气：{weather_info['condition']}，温度{weather_info['temperature']}{weather_info['unit']}，湿度{weather_info['humidity']}"
                            }]
                        }
                    }
                else:
                    response = {"jsonrpc": "2.0", "id": request.get("id"), "error": {"code": -32601, "message": "Method not found"}}
            else:
                response = {"jsonrpc": "2.0", "id": request.get("id"), "error": {"code": -32601, "message": "Method not found"}}

            sys.stdout.write(json.dumps(response) + "\n")
            sys.stdout.flush()
        except (json.JSONDecodeError, KeyError) as e:
            error_resp = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": f"Parse error: {str(e)}"}}
            sys.stdout.write(json.dumps(error_resp) + "\n")
            sys.stdout.flush()
        except Exception as e:
            error_resp = {"jsonrpc": "2.0", "id": request.get("id") if 'request' in locals() else None, "error": {"code": -32000, "message": str(e)}}
            sys.stdout.write(json.dumps(error_resp) + "\n")
            sys.stdout.flush()

if __name__ == "__main__":
    main()

这个脚本实现了一个最简单的MCP Server，它提供了一个 get_weather 工具。确保你的环境安装了Python3，这个脚本可以直接运行。

3.2 在Nacos中注册MCP服务

现在，我们需要将这个MCP Server的信息注册到Nacos中，这样Nacos-MCP-Router才能发现它。登录Nacos控制台（http://localhost:8080/nacos）。

  1. 进入服务管理：在左侧菜单栏点击“服务管理”。
  2. 创建服务：点击“创建服务”按钮。
  3. 填写服务详情：
    • 服务名：weather-mcp-service (建议使用英文，符合命名规范)
    • 分组：DEFAULT_GROUP (默认即可)
    • 保护阈值：0 (通常设为0，表示任何实例健康即可)
    • 元数据：这是关键步骤。我们需要添加特定的MCP配置元数据。点击“元数据”旁的“编辑”按钮，添加以下键值对：
      • mcp.type: stdio (指定服务类型为Stdio)
      • mcp.command: python3 (启动服务的命令)
      • mcp.args: /绝对路径/weather_mcp_server.py (替换为你的脚本实际路径，例如/home/user/mcp_demo/weather_mcp_server.py)
      • mcp.description: 提供城市天气查询的MCP服务 (服务描述，有助于AI Agent理解)
  4. 注册实例：在服务创建后或服务列表中找到该服务，点击“实例列表”->“注册实例”。
    • IP: 填写运行MCP Server的机器IP。如果Server就在本地，可以填127.0.0.1。
    • 端口: MCP Stdio服务通常不监听网络端口，这里可以填一个占位符，如9999。但关键是元数据。
    • 元数据（实例级）: 可以留空，或者添加一些运行环境信息，如env: dev。

点击“注册”后，你就能在服务详情页看到一个健康的服务实例了。Nacos会定期向该实例发送心跳（对于非JAVA应用，需要客户端主动发送心跳，我们的简单脚本未实现，因此状态可能显示为“不健康”。对于演示和Stdio类型的MCP服务，这通常可以接受，或者你可以实现一个简单的健康检查端点）。

4. 配置与连接Nacos-MCP-Router

核心环节来了——配置Nacos-MCP-Router，让它成为AI Agent访问所有MCP服务的统一入口。

4.1 安装Nacos-MCP-Router

Nacos-MCP-Router是一个Python工具，推荐使用 uvx（一个快速的Python包运行器）来安装和运行它。如果你没有安装uv，可以先用pip安装：pip install uv。

接下来，为你的AI Agent（以Cline为例）配置MCP Server。在Cline的配置文件中（通常是 ~/.cline/mcp.json 或类似路径），添加如下配置：

{
  "mcpServers": {
    "nacos-service-router": {
      "command": "uvx",
      "args": [
        "nacos-mcp-router@latest"
      ],
      "env": {
        "NACOS_ADDR": "localhost:8848",
        "NACOS_USERNAME": "nacos",
        "NACOS_PASSWORD": "nacos",
        "NACOS_NAMESPACE": "public",
        "NACOS_GROUP": "DEFAULT_GROUP"
      }
    }
  }
}

配置参数详解：

  • command: 执行命令，这里使用uvx来运行最新版的nacos-mcp-router包。
  • args: 传递给命令的参数。
  • env: 环境变量，用于连接Nacos服务器。
    • NACOS_ADDR: Nacos服务器的地址和端口（默认8848）。
    • NACOS_USERNAME / NACOS_PASSWORD: 你在Nacos控制台注册的账号密码。
    • NACOS_NAMESPACE: 命名空间，默认为public。如果你在Nacos中创建了其他命名空间，需要在此指定。
    • NACOS_GROUP: 服务分组，默认为DEFAULT_GROUP。

保存配置文件并重启Cline（或你的AI Agent）。Agent会自动安装nacos-mcp-router依赖并建立连接。如果一切顺利，你会在Agent的日志或界面中看到连接成功的提示。

4.2 验证与使用Router提供的工具

连接成功后，Nacos-MCP-Router会向AI Agent暴露三个核心工具，它们是Agent与整个MCP服务生态交互的入口：

  1. search_mcp_server

    • 描述：根据任务描述或关键词，在Nacos中搜索可用的MCP服务。这是执行任何任务前的第一步。
    • 使用场景：当你对Agent说“帮我查一下北京的天气”，Agent内部会先调用此工具，搜索名称或描述中包含“天气”的服务。

  2. add_mcp_server

    • 描述：安装（即动态加载）指定的MCP Server。在执行search_mcp_server找到目标服务后，Agent会调用此工具，将找到的MCP Server中的具体工具（如get_weather）加载到当前上下文中，使其可用。
    • 使用场景：Agent搜索到weather-mcp-service后，调用此工具将其“安装”进来。

  3. use_tool

    • 描述：调用某个已安装的MCP Server中的具体工具。
    • 使用场景：安装好天气服务后，Agent调用该服务的get_weather工具，并传入参数{“city”: “北京”}来获取天气信息。

现在，你可以在Cline中尝试输入：“今天北京天气怎么样？”。Cline的底层逻辑大致会这样执行：

  1. 解析你的指令，识别出意图是“查询天气”，地点是“北京”。
  2. 自动调用search_mcp_server，在Nacos中寻找与“天气”相关的服务。
  3. 找到我们注册的weather-mcp-service。
  4. 调用add_mcp_server，将该服务的工具列表加载进来。
  5. 最后调用use_tool，执行get_weather工具并传入城市参数。
  6. 将工具返回的结果（“北京的天气：晴，温度22摄氏度，湿度65%”）组织成自然语言回复给你。

整个过程对用户是完全透明的，你只需要提出需求，Agent会自动完成服务的发现、加载和调用。

5. 高级配置与生产实践建议

掌握了基础流程后，我们来看看如何让这套系统更健壮、更适合生产环境。

5.1 管理多种类型的MCP服务

除了我们演示的Stdio类型，SSE（Server-Sent Events）类型的MCP服务也越来越常见。在Nacos中注册SSE服务时，元数据的配置有所不同：

  • 对于SSE服务：
    • mcp.type: sse
    • mcp.url: http://your-sse-server-host:port/sse-endpoint (SSE服务的完整URL)

Nacos-MCP-Router能够同时处理这两种类型的服务，并根据元数据自动选择合适的通信方式与后端服务交互。

5.2 服务健康检查与高可用

对于生产环境，服务的稳定性至关重要。Nacos提供了强大的健康检查机制。

  • 为MCP Server实现健康检查接口：建议你的MCP Server实现一个简单的HTTP健康检查端点（例如/health，返回{“status”: “UP”}），并在Nacos实例注册时，在元数据中指定检查路径：health.check.path: /health，同时将实例类型改为“临时实例”并配置正确的端口。这样Nacos会定期调用该端点来判定服务健康状态。
  • 使用集群部署：对于关键的MCP服务，可以考虑部署多个实例，并在Nacos中注册。Nacos-MCP-Router在发现服务时，可以从健康的实例列表中按策略（如随机）选择一个进行调用，从而实现简单的负载均衡和故障转移。

5.3 安全与权限控制

  • Nacos访问安全：生产环境务必修改默认的nacos/nacos账号密码，并考虑启用Nacos的命名空间（Namespace）和配置（Configuration）权限控制，为不同的团队或项目隔离服务资源。
  • MCP服务认证：如果MCP服务本身需要API Key或Token（如高德地图服务），这些敏感信息不应硬编码在Nacos的元数据或代码中。推荐的做法是：
    1. 将密钥存储在Nacos的配置管理中。
    2. 在MCP Server启动时，通过环境变量或从Nacos配置中心读取这些密钥。
    3. 在Nacos服务注册的元数据中，只存放配置的dataId和group，而不是密钥本身。

5.4 监控与运维

  • 利用Nacos控制台：密切关注服务列表中的“健康实例数”和“触发保护阈值”状态。不健康的服务实例应及时排查或下线。
  • 日志收集：确保Nacos-MCP-Router以及各个MCP Server的日志被妥善收集（例如输出到文件，并由ELK或Loki等日志系统采集），便于问题追踪。
  • 性能考量：当管理的MCP服务数量庞大时，Nacos-MCP-Router一次性拉取所有服务信息可能会成为瓶颈。关注Router的启动时间和内存占用，必要时可以按命名空间或分组进行服务拆分。

6. 故障排查与常见问题

在实际集成过程中，你可能会遇到一些问题。这里列出一些我遇到过的典型情况及其解决方法。

问题一：AI Agent连接Nacos-MCP-Router失败，提示“无法安装服务器”或超时。

  • 检查网络：确认AI Agent所在机器能访问NACOS_ADDR指定的地址和端口（如localhost:8848）。可以尝试用telnet或curl命令测试连通性。
  • 检查认证信息：确认NACOS_USERNAME和NACOS_PASSWORD与Nacos控制台的账号密码完全一致，注意大小写。
  • 查看Router日志：运行uvx nacos-mcp-router命令直接测试，查看命令行输出的错误信息。常见错误是Nacos地址错误或认证失败。

问题二：能连接Router，但search_mcp_server找不到已注册的服务。

  • 检查命名空间和分组：确认NACOS_NAMESPACE和NACOS_GROUP与Nacos中服务所在的命名空间和分组匹配。默认都是public和DEFAULT_GROUP。
  • 检查服务元数据：在Nacos控制台，进入服务详情，查看“元数据”是否正确填写了mcp.type等关键字段。字段名必须准确。
  • 确认服务健康：检查服务实例是否为“健康”状态。对于未实现健康检查的Stdio服务，可以暂时忽略健康状态，但需要确认实例在线。

问题三：找到服务并add_mcp_server成功，但use_tool调用失败。

  • 检查MCP Server本身：直接在命令行运行你的MCP Server脚本（如python3 weather_mcp_server.py），手动输入JSON-RPC格式的请求，测试其是否能正常响应。这是隔离问题的最有效方法。
  • 检查工具描述：一个极易忽略的点是，MCP Server在tools/list响应中返回的每个工具，其description字段以及输入参数的description字段都不能为空。Nacos-MCP-Router对此有强制校验，缺少描述会导致调用失败。
  • 查看Router转发日志：在Router的启动命令中添加环境变量RUST_LOG=debug（如果Router是Rust编写）或查看其详细日志，观察它向后端MCP Server发送的请求和接收的响应，定位通信问题。

问题四：Stdio类型的MCP Server进程意外退出。

  • 进程守护：对于生产环境，不要直接通过命令行运行Python脚本。使用像systemd、supervisord或pm2这样的进程管理工具来守护你的MCP Server进程，确保其崩溃后能自动重启。
  • 资源限制：在Docker Compose或Kubernetes部署中，为MCP Server容器设置合理的资源限制（CPU、内存），防止因资源耗尽导致进程被杀死。

从最初的手动管理十几个服务的配置文件，到如今通过Nacos控制台轻松管理一个不断增长的服务池，Nacos-MCP-Router确实让AI Agent的扩展和维护变得优雅了许多。它带来的最大改变是思维模式的转变——从“为每个Agent配置服务”变成了“让服务在中心注册，被Agent发现”。这种模式特别适合微服务架构下的AI应用开发，服务提供者和消费者实现了松耦合。

我在一个内部知识库问答系统中应用了这套方案，将文档检索、代码搜索、日志查询等能力都封装成独立的MCP服务注册到Nacos。开发新功能时，我们只需要开发新的MCP Server并注册，前端的AI助手就能自动获得新能力，迭代速度大大提升。如果你也在构建需要整合多种外部能力的AI应用，不妨试试这个组合，它可能会为你打开一扇新的大门。

# MCP
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

我用 Qwen3.8-Max 做了一个采购合同风险审查工具：从能分析，到能定位、复核和交付

avatar DeepSeek技术社区
cover

我用 Qwen3.8-MAX 搭了一个教研纪要 Agent，一次集体备课几秒出七段、分歧还不被和稀泥

avatar DeepSeek技术社区
cover

OpenCode Go 与 Command Code 的性价比分析 2026.08.31更新

avatar DeepSeek技术社区