MCP Router：构建AI智能体工具调用的核心路由与部署指南-深圳市維司達科技有限公司

1. 项目概述：一个连接AI与世界的“路由器”

最近在折腾AI应用开发的朋友，可能都遇到过类似的困境：你有一个功能强大的大语言模型（LLM），比如ChatGPT、Claude或者本地部署的开源模型，你想让它帮你查查最新的天气、控制一下家里的智能设备，或者从你的Notion里调取一份文档。结果你发现，模型本身就像一个与世隔绝的“大脑”，它知识渊博，但“手”和“眼睛”却伸不出去，无法直接操作外部的工具、API或数据源。这时候，你就需要一个可靠的“中间人”来架起这座桥梁。

mcp-router就是这样一个扮演“中间人”或“路由器”角色的项目。它的全称是Model Context Protocol Router。简单来说，MCP（Model Context Protocol）是一个新兴的、旨在标准化LLM与工具之间通信的协议。你可以把它想象成USB协议之于电脑和外设——它定义了一套标准接口，让任何符合MCP标准的“工具”（比如日历、数据库、搜索引擎客户端）都能轻松地“插”到LLM上使用。而mcp-router，则是这个生态系统中一个非常关键的基础设施组件：它负责管理、路由和调度这些工具与LLM之间的请求。

想象一下这个场景：你正在和Claude对话，你说“帮我把明天上午10点的会议记到日历里，然后从我的项目文档库中找到上季度的复盘总结发给我”。对于Claude来说，它需要调用“日历工具”来创建事件，同时调用“文档库工具”来搜索并获取文件。mcp-router在这里的作用，就是接收Claude发出的“调用日历工具”和“调用文档库工具”的指令，准确地将这些指令分发给对应的、正在运行的工具服务，并将工具返回的结果（“事件已创建”、“这是您要的文档”）整理好，回传给Claude。它让AI从“纸上谈兵”变得“能说会做”。

这个项目适合所有正在或计划构建AI智能体（AI Agent）、为现有LLM应用增加工具调用能力、或者希望统一管理多个AI工具的后端开发者。如果你对如何让AI更接地气、更实用感兴趣，那么理解mcp-router的工作原理和部署方式，将是非常有价值的一步。

2. 核心架构与设计哲学

2.1 为什么需要MCP和Router？

在mcp-router出现之前，让LLM使用工具通常有两种主流方式：一种是针对特定LLM（如OpenAI的GPTs）的专用插件体系，另一种是开发者自行定义工具描述并通过Function Calling机制调用。前者被平台绑定，缺乏通用性；后者虽然灵活，但工具的描述、调用规范千差万别，集成和维护成本很高。

MCP协议的出现，就是为了解决这种碎片化问题。它定义了一套与LLM供应商无关的工具描述、发现、调用和结果返回的标准。任何实现了MCP Server标准的工具，理论上都可以被任何支持MCP Client的LLM所使用。这极大地促进了工具生态的繁荣和互操作性。

然而，仅仅有协议还不够。在实际的复杂应用中，我们通常会面临几个挑战：

工具管理：一个应用可能需要连接数十个不同的工具（数据库、API、文件系统等）。手动为每个LLM会话配置和维护这些连接是低效的。
路由与负载：多个AI智能体或用户可能同时请求使用同一个工具（如搜索引擎）。需要一个中心节点来管理这些并发请求，避免冲突和过载。
安全与权限：不是所有工具都应该对所有LLM或所有用户开放。需要有一个层面来控制“谁可以用什么工具”。
状态与会话：某些工具调用可能是有状态的（例如，一个多步的数据查询向导）。需要管理工具与特定LLM会话之间的关联状态。

mcp-router正是为了应对这些挑战而设计的。它作为MCP生态中的“中间层”，向上对接一个或多个LLM（MCP Client），向下管理一个或多个工具（MCP Server）。它的核心设计哲学是“透明代理”和“集中管控”。对LLM来说，它就像一个提供了所有可用工具的统一接口；对工具来说，它是唯一的、可控的访问入口。

2.2 核心组件与数据流

要理解mcp-router，我们可以将其拆解为几个核心逻辑组件，并跟踪一个典型工具调用的数据流：

核心组件：

客户端连接管理器：负责维护与上游LLM（MCP Client）的连接。这通常通过SSE（Server-Sent Events）或WebSocket实现，用于接收LLM的请求和发送响应。
服务端注册表：一个动态的注册中心，记录所有已连接并可用的MCP Server（工具）的信息，包括工具名称、描述、调用方法（参数列表）等。
路由决策引擎：这是路由器的大脑。当收到一个工具调用请求时，它根据预配置的策略（如工具名称匹配、负载情况、权限规则）决定将这个请求转发给哪个具体的工具服务实例。
协议适配器：确保在LLM Client、Router和Tool Server之间传输的消息严格遵循MCP协议规范。它处理序列化、反序列化和协议版本的兼容性。
会话与状态管理：为每个LLM客户端会话维护上下文，可能包括会话ID、已使用的工具历史、以及特定工具所需的临时状态。

一次工具调用的数据流：

初始化：LLM客户端连接到mcp-router。Router向LLM客户端发送当前所有可用工具的列表（通过MCP的tools/list方法）。
请求：用户向LLM发出自然语言指令（如“查天气”）。LLM理解后，决定调用“天气查询工具”，并生成一个结构化的调用请求，通过连接发送给mcp-router。这个请求包含了工具名和调用参数（如{"location": "北京"}）。
路由：mcp-router的路由决策引擎接收到请求。它首先检查该LLM客户端是否有权限调用“天气查询工具”。如果有，它会在服务端注册表中找到对应的“天气查询”MCP Server的地址。
转发：Router将调用请求转发给“天气查询”Server。
执行：“天气查询”Server执行真正的业务逻辑（例如，调用一个第三方天气API），得到结果（如{"temperature": 22, "condition": "晴"}）。
返回：工具Server将结果返回给mcp-router。
响应：mcp-router将结果封装成MCP协议规定的格式，发送回最初发起请求的LLM客户端。
完成：LLM客户端收到结果，将其转化为自然语言回复给用户：“北京今天天气晴朗，气温22度。”

在整个过程中，LLM客户端只与mcp-router交互，无需关心工具服务部署在哪里、如何连接。工具服务也只需与mcp-router通信，无需适配不同的LLM客户端。这种解耦带来了巨大的灵活性和可维护性。

3. 部署与配置实战

理解了原理，我们来看看如何亲手搭建一个mcp-router服务。这里我们假设一个典型的开发环境：使用Docker进行容器化部署，这能最大程度保证环境一致性。

3.1 基础环境准备

首先，你需要确保你的机器上已经安装了Docker和Docker Compose。这是目前部署此类服务最便捷的方式。你可以通过运行docker --version和docker compose version来检查。

接下来，我们需要准备两个核心的配置文件：docker-compose.yml和mcp-router的配置文件（例如config.json）。

1. Docker Compose 编排文件创建一个docker-compose.yml文件，它定义了mcp-router服务以及它要连接的一两个示例工具服务（这里我们用两个官方示例工具：stdin和calculator）。

version: '3.8' services: mcp-router: image: ghcr.io/mcp-router/mcp-router:latest # 使用官方镜像 container_name: mcp-router ports: - "3000:3000" # 将容器的3000端口映射到主机，用于LLM客户端连接 volumes: - ./config.json:/app/config.json:ro # 挂载配置文件 - ./cache:/app/cache # 可选：挂载缓存目录，提升性能 restart: unless-stopped networks: - mcp-network # 示例工具：一个简单的计算器MCP Server tool-calculator: image: ghcr.io/modelcontextprotocol/servers/calculator:latest container_name: mcp-tool-calculator restart: unless-stopped networks: - mcp-network # 示例工具：一个用于调试的stdin/stdout MCP Server tool-stdin: image: ghcr.io/modelcontextprotocol/servers/stdin:latest container_name: mcp-tool-stdin restart: unless-stopped networks: - mcp-network networks: mcp-network: driver: bridge

这个配置创建了一个名为mcp-network的Docker网络，三个服务都加入其中，这样它们可以通过服务名（如tool-calculator）相互访问。

2. MCP Router 核心配置文件在同一目录下创建config.json，这是mcp-router的“大脑”，告诉它如何连接工具以及定义路由规则。

{ "logLevel": "info", "client": { "type": "sse", "port": 3000, "path": "/sse" }, "servers": [ { "name": "calculator", "description": "A simple arithmetic calculator", "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-stdin", "calculator"] } }, { "name": "stdin", "description": "A debug server that echoes input", "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-stdin"] } } ], "routing": { "defaultPolicy": "allow", "rules": [ { "clientIdPattern": ".*", // 匹配所有客户端 "serverNamePattern": ".*", // 匹配所有工具 "policy": "allow" } ] } }

这个配置做了以下几件事：

client: 定义LLM客户端如何连接。这里使用SSE（Server-Sent Events）在3000端口的/sse路径上提供服务。
servers: 定义工具列表。每个工具需要指定name、description和关键的transport（传输方式）。注意：在Docker Compose环境中，由于工具运行在独立容器，这里的stdio方式可能不适用。更常见的做法是使用http或https传输，指向工具容器的内部地址和端口。上述配置更适用于本地进程管理。我们稍后会调整。
routing: 定义路由策略。这里是一个简单的允许所有请求的规则。

注意：上面配置文件中的transport部分是为了说明结构。在实际Docker Compose部署中，工具通常作为独立的HTTP服务运行。你需要查阅每个MCP Server工具的文档，获取其内部的HTTP服务端口和端点，然后将transport类型改为"type": "http"，并配置"url": "http://tool-calculator:端口号"（使用Docker服务名）。这是初次配置时最常见的困惑点。

3.2 调整配置以适配容器网络

让我们修正配置，使其更适合Docker Compose环境。假设我们从文档得知，calculator服务器在容器内监听8080端口，并提供/mcp端点。

更新后的config.json片段：

{ ... // logLevel, client 部分不变 "servers": [ { "name": "calculator", "description": "A simple arithmetic calculator", "transport": { "type": "http", "url": "http://tool-calculator:8080", "endpoint": "/mcp" } }, { "name": "stdin", "description": "A debug server", "transport": { "type": "http", "url": "http://tool-stdin:8080", // 假设stdin工具也运行在8080 "endpoint": "/mcp" } } ], ... // routing 部分不变 }

同时，需要更新docker-compose.yml，确保示例工具暴露了端口，并且mcp-router配置中使用的URL正确。

# docker-compose.yml 中工具服务部分更新 tool-calculator: image: ghcr.io/modelcontextprotocol/servers/calculator:latest container_name: mcp-tool-calculator expose: - "8080" # 在容器网络内暴露端口 # 注意：通常MCP Server镜像会通过环境变量或命令指定端口，请根据具体镜像文档调整 environment: - PORT=8080 restart: unless-stopped networks: - mcp-network

3.3 启动服务与验证

配置完成后，在包含docker-compose.yml的目录下，执行启动命令：

docker compose up -d

-d参数表示在后台运行。使用docker compose logs -f mcp-router可以实时查看路由器的日志，排查启动问题。

如果一切顺利，mcp-router服务将在本机的3000端口运行。现在，我们需要一个MCP客户端来测试它。一个快速测试的方法是使用MCP官方提供的CLI测试工具，或者使用一个支持MCP的LLM客户端（如Claude Desktop的最新版本，如果其配置了MCP支持）。

使用简单HTTP请求测试连接：你可以通过curl模拟一个SSE连接初始化，来验证路由器是否在线并能返回工具列表。

curl -N -H "Accept: text/event-stream" http://localhost:3000/sse

你应该能看到一系列SSE事件流，其中包含initialized事件以及后续的tools/list响应，里面列出了calculator和stdin工具。

更实际的测试是配置一个真正的LLM客户端。例如，在Claude Desktop的配置文件中（位置因系统而异），你可以添加MCP服务器配置，指向http://localhost:3000/sse。配置成功后，在Claude的对话界面，你应该能看到新增的工具图标或能在对话中直接使用计算器等工具。

4. 高级配置与生产级考量

基础部署跑通后，要用于实际生产或更复杂的开发环境，还需要考虑以下几个关键方面。

4.1 安全与权限精细化控制

默认的允许所有策略显然不安全。mcp-router的路由规则 (routing.rules) 提供了基于正则表达式的灵活控制。

场景一：隔离不同LLM客户端的工具访问权限假设你有两个LLM客户端：一个内部使用的管理助手（Client ID:admin-assistant），一个对外提供的客服机器人（Client ID:customer-bot）。你希望管理员能使用所有工具（包括数据库操作工具db-admin），而客服机器人只能使用知识库查询工具kb-query和计算器。

{ "routing": { "defaultPolicy": "deny", // 默认拒绝，白名单模式更安全 "rules": [ { "clientIdPattern": "^admin-assistant$", "serverNamePattern": ".*", // 管理员可以使用所有工具 "policy": "allow" }, { "clientIdPattern": "^customer-bot$", "serverNamePattern": "^(kb-query|calculator)$", // 客服只能使用特定工具 "policy": "allow" } ] } }

场景二：限制工具调用频率（防滥用）虽然mcp-router核心可能不直接提供限流功能，但你可以通过在它前面部署一个API网关（如Nginx, Kong）或在其配置中集成中间件（如果项目支持）来实现。例如，在Nginx中可以为/sse路径配置限流：

http { limit_req_zone $binary_remote_addr zone=mcp_limit:10m rate=10r/s; server { listen 80; location /sse { limit_req zone=mcp_limit burst=20 nodelay; proxy_pass http://mcp-router:3000; proxy_set_header Host $host; proxy_buffering off; # SSE需要禁用缓冲 proxy_cache off; } } }

4.2 连接稳定性与高可用

对于生产环境，服务不能轻易宕机。

健康检查与自动重启：在docker-compose.yml中为服务添加健康检查。

services: mcp-router: image: ghcr.io/mcp-router/mcp-router:latest healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3000/health"] # 假设有健康检查端点 interval: 30s timeout: 10s retries: 3 start_period: 40s restart: always # 或 unless-stopped

多实例与负载均衡：对于高并发场景，可以部署多个mcp-router实例，前面用负载均衡器（如Nginx, HAProxy）分发来自LLM客户端的SSE连接。注意：由于SSE连接是长连接且有状态（会话），简单的轮询负载均衡可能不合适，需要考虑会话保持（session persistence）或将会话状态外置到Redis等共享存储中（如果mcp-router本身支持无状态设计）。

工具服务的容错：在config.json中，可以为工具服务器配置重试逻辑和超时时间（如果mcp-router支持）。

{ "servers": [ { "name": "critical-api", "transport": { "type": "http", "url": "http://critical-api:8080", "endpoint": "/mcp", "timeoutMs": 5000, // 5秒超时 "retry": { "attempts": 3, "backoffFactor": 2 } } } ] }

4.3 监控、日志与可观测性

清晰的日志和监控是运维的基石。

结构化日志：确保config.json中的logLevel设置为info或debug（生产环境建议info）。日志应输出到标准输出（stdout），由Docker收集，再通过Fluentd、Logstash等工具转发到ELK或Loki等日志中心。
指标暴露：查看mcp-router是否支持暴露Prometheus格式的指标（通常在/metrics端点）。这些指标可能包括：活跃连接数、工具调用次数、调用耗时、错误次数等。这些数据对于监控系统健康、定位性能瓶颈至关重要。
分布式追踪：在微服务架构中，一个LLM请求可能触发多个工具调用。集成OpenTelemetry等追踪标准，为每个请求分配唯一的Trace ID，并贯穿LLM Client、mcp-router和各个Tool Server，可以让你清晰地可视化整个调用链，快速定位延迟或错误发生在哪个环节。

5. 常见问题与故障排查实录

在实际部署和使用mcp-router的过程中，你几乎一定会遇到下面这些问题。这里记录了我踩过的坑和解决方案。

5.1 连接建立失败：LLM客户端无法发现工具

现象：LLM客户端（如Claude Desktop）成功连接到了mcp-router的SSE端点，但在客户端界面看不到任何可用工具，或者工具列表为空。

排查思路：

检查路由器日志：这是第一步，也是信息量最大的一步。运行docker compose logs -f mcp-router，观察启动过程有无报错，以及当客户端连接时，是否有处理tools/list请求的日志。
- 如果日志显示无法连接某个Tool Server：检查config.json中该工具的transport.url是否正确。在Docker Compose中，应使用服务名而非localhost。确认工具容器是否健康运行 (docker compose ps)，并且端口是否在容器网络内暴露。
- 如果日志显示协议错误或版本不兼容：确认mcp-router的版本与Tool Server的MCP协议版本是否兼容。有时需要为工具指定正确的传输参数。

验证工具服务器本身是否正常：进入工具容器内部，或通过端口映射，直接测试工具服务器的MCP端点。

# 临时将工具的端口映射到主机，假设是calculator # 修改docker-compose.yml中tool-calculator的ports部分，添加 - "18080:8080" # 然后重启服务 docker compose up -d # 使用curl测试工具服务器是否响应MCP协议 curl -X POST http://localhost:18080/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

你应该能收到一个包含工具列表的JSON响应。如果没有，说明工具服务器自身配置或启动有问题。

检查客户端配置：确认LLM客户端配置的MCP服务器地址完全正确，包括协议(http/https)、主机、端口和路径(/sse)。对于Claude Desktop，配置文件通常需要重启应用才能生效。

5.2 工具调用超时或无响应

现象：LLM客户端可以列出工具，但当尝试调用某个工具时，请求一直挂起，最终超时。

排查思路：

观察路由器日志：查看在转发调用请求和等待工具响应时的日志。如果日志显示转发后长时间没有收到工具响应，问题很可能在下游工具服务器。
检查工具服务器负载与性能：工具服务器可能因为处理逻辑复杂、依赖的外部API慢、或者资源（CPU/内存）不足而导致响应缓慢。使用docker stats查看容器资源使用情况。检查工具服务器自身的日志。
调整超时设置：如果确认是某些工具本身较慢，且属于正常情况，可以在mcp-router的配置中适当增加该工具传输层的timeoutMs值，避免过早断开。
网络问题：在容器网络中，偶尔也会有网络延迟或丢包。确保Docker网络驱动稳定，避免使用某些有问题的虚拟网络驱动。

5.3 权限问题：客户端被禁止调用工具

现象：客户端调用工具时，收到“权限拒绝”或“工具未找到”的错误，尽管在工具列表中能看到它。

排查思路：

仔细核对路由规则：回顾config.json中的routing.rules。defaultPolicy是deny吗？你的客户端ID是否匹配了某条allow规则？规则中的正则表达式是否写对了？一个常见的错误是正则表达式过于严格或宽松。
确认客户端ID：LLM客户端在连接时可能会发送一个客户端标识。你需要知道你的客户端使用的是哪个ID。查看mcp-router的连接日志，通常会在客户端建立连接时打印出客户端信息。然后在路由规则中使用正确的ID进行匹配。
规则顺序：有些路由引擎会按顺序匹配规则，第一条匹配的规则生效。确保你的允许规则放在拒绝规则之前（或之后，取决于你的设计逻辑）。

5.4 配置热重载与动态更新

需求：在不停机的情况下，新增一个工具服务器，或者修改某个工具的配置。

现状与方案：目前mcp-router可能不支持配置的热重载。这意味着修改config.json后，需要重启mcp-router容器 (docker compose restart mcp-router)。重启会导致所有现有的LLM客户端连接中断，对于生产环境不友好。

变通方案：

蓝绿部署：部署一个新的mcp-router实例（新配置），并将其接入负载均衡器。然后将流量从旧实例逐步切换到新实例。最后下线旧实例。
使用外部服务发现：如果mcp-router支持，可以将工具服务器的配置信息（如URL）存储在外部系统（如Consul, Etcd）中。mcp-router动态地从这些系统获取配置。这样，更新工具服务器信息只需修改服务发现系统中的数据，而无需重启路由器。你需要查阅mcp-router的高级文档或源码，看是否支持此类集成。

5.5 性能瓶颈分析与优化

当工具调用量增大时，可能会遇到性能问题。

瓶颈定位：使用监控指标。如果mcp-router的CPU/内存使用率高，可能是其本身成为瓶颈。如果mcp-router资源使用正常，但整体延迟高，则瓶颈可能在工具服务器或网络。
优化建议：
- 连接池：如果mcp-router到每个工具服务器使用的是HTTP短连接，频繁建立连接开销很大。确保HTTP传输配置了连接池。
- 异步与非阻塞：mcp-router应该使用异步I/O模型（如Node.js, Go, Rust实现）来处理大量并发的SSE连接和工具调用，避免阻塞。
- 工具服务器扩容：对于负载高的工具，考虑部署多个实例，并在mcp-router配置中配置多个端点或使用一个负载均衡器地址。
- 缓存：对于某些读多写少、数据变化不频繁的工具调用结果，可以在mcp-router层面或客户端层面引入缓存，减少对工具服务器的直接调用。