1. 从单体到模块化MCP Server 拆分到底解决什么问题如果你正在做 AI 工具中枢大概率遇到过这种局面一开始所有工具都塞在一个server.py里注册表、路由、鉴权、模型调用全混在一起。工具从 3 个涨到 30 个之后改一个天气查询工具的参数校验结果把代码检索工具的调用链弄崩了。这就是典型的单体 MCP Server 困境。MCP Server 模块化拆分说白了就是把「协议处理」「工具注册」「资源访问」「模型通道」这几件事拆成边界清晰的独立模块让每个模块只对自己那摊事负责。它适合谁适合正在把内部工具链接入 AI Agent 的开发者尤其是需要同时对接多个模型供应商、工具数量还在持续增长的团队。我试过最直接的对比单体架构下新增一个工具平均要动 4 个文件、跑一遍全量回归拆成模块后新增工具只写一个tools/xxx_tool.py加一行注册核心路由代码零改动。可扩展性和可维护性的差距在工具数量超过 10 个之后就非常明显了。这篇文章不讲空泛的架构图而是给你一套能直接跑的拆分方案模块边界怎么划、工具怎么注册、路由怎么配以及如何用 TaoToken 的统一 Key 把多模型调用收敛到一个 API 通道最后完成一次端到端验证。核心检索词就三个MCP Server 模块化拆分、可扩展 AI 工具中枢、统一 Key 多模型接入。先说清楚模块边界划分的原则这是整个拆分的地基。我的经验是按「变化频率」和「依赖方向」两个维度切变化频率高的放外层。工具的具体实现天天改模型供应商可能随时换这些都属于易变部分应该独立成模块。变化频率低的核心协议解析、请求生命周期管理放在内层稳定模块。依赖方向必须单向。工具模块可以依赖核心模块暴露的接口但核心模块绝不能反向 import 具体工具。一旦出现循环依赖模块化就名存实亡了。判断标准很简单删掉任意一个工具模块核心模块应该还能正常启动。落到具体目录我推荐这样的结构mcp_server/ ├── core/ # 稳定层协议、路由、生命周期 │ ├── protocol.py # MCP 协议解析与响应格式化 │ ├── router.py # 请求路由与工具分发 │ └── registry.py # 模块与工具注册中心 ├── modules/ # 业务层按领域拆分 │ ├── tools/ # 工具模块 │ │ ├── code_search.py │ │ └── weather.py │ └── resources/ # 资源模块 │ └── file_access.py ├── providers/ # 模型通道层统一走 TaoToken │ └── llm_client.py └── config/ └── settings.toml这个结构的关键在于providers单独成层。很多人把模型调用散落在各个工具里结果换一个模型要改十几处。把 LLM 客户端收敛成一层所有工具通过统一接口调用后面接 TaoToken 就只需要改这一层。模块边界划好之后每个模块对外只暴露两样东西路由声明和错误处理器。内部实现随便你怎么写核心层不关心。这就是高内聚低耦合的落地方式也是后面工具注册和路由配置能自动化运转的前提。2. TaoToken 前置准备统一 Key 与 API 通道配置模块化拆分解决的是代码结构问题但多模型接入还有另一个痛点每个模型供应商一套 Key、一套 Base URL、一套鉴权格式。工具模块越多散落的凭证管理越乱。这一步我们用 TaoToken 把模型通道统一起来让所有工具模块通过一个 Key 访问多个模型。TaoToken 在这里扮演的角色是统一 API 通道你拿到一个 Key配置一个 Base URL就能在工具模块里调用不同模型不用为每个供应商单独维护客户端。对模块化架构来说这正好契合providers层的设计——通道层只认一个入口工具层完全不感知底层是哪个模型。先拿 Key。访问控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建时建议按用途分 Key比如mcp-dev、mcp-prod各一个方便后续按 Key 做用量隔离和吊销。Key 只在创建时完整显示一次复制后立刻存进环境变量别硬编码进代码。拿到 Key 之后把 Base URL 和 Key 写进环境变量。这是模块化项目里最省事的做法配置和代码分离export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意 Base URL 用https://taotoken.net/api不带任何查询参数。很多 401 报错就是因为把带 UTM 的官网地址误填进了 Base URL这个坑后面排障章节会细说。接下来在providers/llm_client.py里封装统一客户端。这一层是模块化的关键工具模块只调用LLMClient.chat()不关心底层通道import os from openai import OpenAI class LLMClient: def __init__(self): self.client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) def chat(self, model: str, messages: list, **kwargs): resp self.client.chat.completions.create( modelmodel, messagesmessages, **kwargs, ) return resp.choices[0].message.content这里用 OpenAI 兼容的 SDK 就能对接因为 TaoToken 的 API 通道遵循兼容格式。Model ID 通过参数传入工具模块想用哪个模型就传哪个通道层不做硬编码。这样设计的好处是以后新增模型工具代码一行不用改。如果你需要确认当前可用的 Model ID 列表可以直接在模型对话页面测试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite在页面上选模型、发一条测试消息能正常返回就说明 Key 和通道都没问题。这一步建议在写工具代码之前先做避免后面调试时把通道问题和代码问题混在一起排查。配置阶段还有一件事把settings.toml里的模型通道参数抽出来别写死在代码里。模块化项目最忌讳配置散落各处集中管理后续换环境才不痛苦[provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet-4-5 timeout 60api_key_env存的是环境变量名而不是 Key 本身这样配置文件可以安全提交到仓库。工具模块读取配置时通过os.environ[config.provider.api_key_env]取值既统一又安全。前置准备做到这里通道层就绪可以进入模块注册和路由配置了。3. 可复制配置工具注册与路由的模块化实现这一节是全文的技术核心给你一套能直接复制的模块注册与路由配置。模块化拆分能不能落地就看工具注册是否自动化、路由是否解耦。先定义模块基类。所有工具模块继承它核心层只依赖这个抽象不依赖任何具体工具# core/module.py from abc import ABC, abstractmethod class BaseModule(ABC): name: str base abstractmethod def get_routes(self) - list: 返回 [(method, path, handler), ...] ... def get_error_handlers(self) - list: return []然后是注册中心。它维护一个工具名到处理函数的映射核心层通过它分发请求# core/registry.py class ModuleRegistry: def __init__(self): self._routes {} self._modules {} def register(self, module): self._modules[module.name] module for method, path, handler in module.get_routes(): self._routes[(method, path)] handler def resolve(self, method, path): return self._routes.get((method, path))核心路由只做一件事查表分发。它不知道也不关心具体工具怎么实现# core/router.py class Router: def __init__(self, registry): self.registry registry async def dispatch(self, method, path, payload): handler self.registry.resolve(method, path) if handler is None: return {error: {code: MCP-404, message: fno route: {path}}} return await handler(payload)现在写一个具体工具模块。注意它只依赖BaseModule和LLMClient不碰核心路由# modules/tools/code_search.py from core.module import BaseModule from providers.llm_client import LLMClient class CodeSearchModule(BaseModule): name code_search def __init__(self, llm: LLMClient): self.llm llm def get_routes(self): return [ (POST, /tools/code_search, self.handle), ] async def handle(self, payload): query payload.get(query, ) result self.llm.chat( modelclaude-sonnet-4-5, messages[{role: user, content: f检索代码{query}}], ) return {status: ok, result: result}启动时把所有模块注册进去新增工具只需要在列表里加一行# main.py from core.registry import ModuleRegistry from core.router import Router from providers.llm_client import LLMClient from modules.tools.code_search import CodeSearchModule llm LLMClient() registry ModuleRegistry() registry.register(CodeSearchModule(llm)) router Router(registry)这套配置的可扩展性体现在新增一个天气工具你只写modules/tools/weather.py然后在main.py加一行registry.register(WeatherModule(llm))。核心路由、注册中心、通道层全部零改动。这就是模块化拆分带来的实际收益。如果你用的是 Claude Code 这类客户端接入配置三件套要写全缺一不可{ mcpServers: { ai-hub: { command: python, args: [main.py], env: { TAOTOKEN_API_KEY: sk-你的key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }Base URL、Key、Model ID 三件套里Base URL 和 Key 走环境变量注入Model ID 在工具模块调用时指定。这样配置的好处是同一个 MCP Server 进程里不同工具可以用不同模型但共享同一个通道凭证。路由配置还有一个容易忽略的点错误处理器也要按模块注册。工具模块自己定义错误类型和对应的响应格式核心层统一捕获。这样某个工具抛异常不会污染其他模块的响应结构。把get_error_handlers()返回的列表在注册时一并挂到核心错误处理器上模块的自治性就完整了。4. 端到端验证一次完整调用与成功结果配置写完必须验证否则你不知道是通道问题还是代码问题。这一节走一遍完整的端到端调用从启动服务到拿到模型返回。先做最小验证不启动 MCP Server直接测通道层能不能通。这一步能把 TaoToken 配置问题和业务代码问题彻底分开# verify_channel.py from providers.llm_client import LLMClient llm LLMClient() out llm.chat( modelclaude-sonnet-4-5, messages[{role: user, content: 只回复两个字通了}], ) print(out)运行python verify_channel.py如果打印出「通了」说明 Key、Base URL、Model ID 三件套全部正确。如果这一步就报错直接跳到第 5 节排障别往下走。通道验证通过后启动 MCP Server 并测试路由分发。用一个简单的 HTTP 请求模拟工具调用curl -X POST http://127.0.0.1:8080/tools/code_search \ -H Content-Type: application/json \ -d {query: 如何做模块化拆分}预期返回结构{ status: ok, result: 模块化拆分的核心是按变化频率划分边界…… }看到status: ok且result有实际内容说明整条链路通了请求进入核心路由 → 查表分发到CodeSearchModule→ 模块调用LLMClient→ 通道层走 TaoToken → 模型返回 → 逐层回传。再验证模块化的关键特性新增模块不影响已有模块。临时加一个 echo 工具只回显不调模型# modules/tools/echo.py from core.module import BaseModule class EchoModule(BaseModule): name echo def get_routes(self): return [(POST, /tools/echo, self.handle)] async def handle(self, payload): return {status: ok, result: payload.get(text, )}注册后重启请求/tools/echo能正常返回同时/tools/code_search依然工作。这就证明了模块之间互不干扰可扩展性达标。如果你要验证更复杂的多模型场景可以在同一个 Server 里让两个工具用不同 Model ID都走同一个 TaoToken 通道。比如代码检索用claude-sonnet-4-5文本摘要用另一个模型观察两者是否都能正常返回。这一步能验证通道层对多模型的支持是否到位。验证阶段建议记录三个指标首次请求延迟、连续 10 次请求的成功率、模块注册后的启动时间。模块化架构下启动时间应该随模块数量线性增长而不是指数增长如果发现启动明显变慢多半是模块间出现了隐式依赖回到第 1 节的边界原则检查。端到端跑通之后你就有了一套可工作的模块化 MCP Server。接下来把它接入实际客户端比如在 Claude Code 里通过 MCP 配置调用这些工具。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite文档里有不同客户端的接入示例照着改 Base URL 和 Key 即可。验证通过再进入生产使用别跳过这一步直接上量。5. 常见报错排查401、local proxy failed 与 choices 解析模块化项目调试时报错往往横跨通道层、路由层、工具层定位困难。这一节按真实报错逐个拆解帮你快速定位问题出在哪一层。401 Unauthorized。这是最高频的报错几乎都出在通道层。排查顺序先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的存在用echo $TAOTOKEN_API_KEY看有没有值再确认 Key 没有多余空格或换行复制时很容易带上最后确认 Key 没有过期或被吊销。如果环境变量对但依然 401检查代码里是不是硬编码了旧 Key 覆盖了环境变量。local proxy failed / connection refused。这个报错通常不是 TaoToken 的问题而是本地网络或 Base URL 配置错误。先确认TAOTOKEN_BASE_URL填的是https://taotoken.net/api不是官网首页地址。很多人把带?utm_source...的完整官网链接填进 Base URL导致请求路径拼接错误。Base URL 只到/api后面的路径由 SDK 自己拼。reading choices of undefined。这个报错说明响应结构和你代码里取值的路径对不上。常见原因是resp.choices[0]里choices为空或者返回的是错误对象而不是正常响应。排查方法在LLMClient.chat()里先打印完整resp看实际返回结构。如果是错误响应resp里会有error字段先处理错误再取choices。防御性写法resp self.client.chat.completions.create(...) if not resp.choices: raise RuntimeError(fempty choices: {resp}) return resp.choices[0].message.contentOAuth / authentication failed。如果你用的是 Claude Code 或类似客户端报 OAuth 相关错误通常是客户端的鉴权配置和 MCP Server 的通道配置冲突了。检查客户端配置里的env是否正确注入了TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL。三件套缺任何一个都会导致鉴权失败。特别注意客户端配置里的环境变量不会自动继承你 shell 里的变量必须在配置里显式写。模块注册后路由 404。这个报错出在路由层不是通道层。排查确认模块的get_routes()返回的 path 和请求 path 完全一致包括大小写和斜杠确认模块真的被registry.register()调用了确认注册发生在服务启动之前。模块化架构下 404 基本都是注册遗漏不是路由逻辑问题。工具调用超时。如果通道验证通过但工具调用超时多半是工具模块内部逻辑阻塞了事件循环。检查工具处理函数里有没有同步的耗时操作比如同步文件读写、同步 HTTP 请求直接跑在 async 函数里。这类操作要用run_in_executor包起来否则会卡住整个 Server。排障的核心思路是分层定位先测通道层verify_channel.py再测路由层curl 直连最后测工具层具体业务逻辑。哪一层先失败问题就在哪一层。别一上来就改业务代码那样只会把问题搅得更乱。如果排障过程中需要确认 Key 状态或重新生成回到控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite控制台能看到每个 Key 的创建时间和最近使用情况方便判断是不是 Key 本身的问题。排障完成后建议把验证脚本保留在仓库里下次环境变更时直接跑一遍比手动排查快得多。6. 长期编码与 Agent 场景把模块化中枢用起来模块化拆分做完、端到端验证通过之后这套 MCP Server 真正的价值在于长期使用。如果你打算把它作为日常编码和 Agent 任务的工具中枢有几个实践建议。第一把工具按使用频率分层。高频工具代码检索、文件访问保持轻量启动即加载低频工具报表生成、批量处理做成按需加载减少启动开销。模块化架构天然支持这种分层因为每个模块独立加载策略可以按模块配置。第二模型通道层加一层缓存和重试。工具调用模型时相同请求可以缓存结果减少重复消耗网络抖动时自动重试避免单次失败影响 Agent 任务。这些逻辑都收敛在providers层不影响工具模块。第三为 Agent 场景准备 Coding Plan。如果你要让 Agent 长时间自主执行编码任务按量计费可能不好控制成本包月方案更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteCoding Plan 适合需要持续调用模型、任务周期长的场景。模块化 MCP Server 配合包月通道Agent 可以放心跑长任务不用担心单次调用成本失控。第四给每个工具模块写清楚输入输出契约。Agent 调用工具时依赖工具描述来决定用哪个工具描述模糊会导致 Agent 选错工具。每个模块的get_routes()旁边配上参数 schema 和用途说明Agent 的调用准确率会明显提升。第五定期清理不再使用的模块。模块化的好处是删除模块很干净但前提是你真的去删。每季度过一遍工具使用日志把三个月没被调用的模块下线保持中枢精简。工具越多Agent 的选择成本越高不是越多越好。最后说一个实际经验模块化拆分不是一次性的架构动作而是持续演进的习惯。每次新增工具时问自己一句「这个工具应该属于哪个模块还是需要新开一个模块」边界就会越来越清晰。一开始可能拆得不完美但只要有单向依赖和清晰注册这两个约束在架构就不会腐化。这套方案跑下来你得到的不只是一个能用的 MCP Server而是一个能持续接工具、换模型、扩规模的中枢。核心就三件事边界按变化频率划、注册自动化、通道统一走 TaoToken。剩下的就是不断往里加工具让它越长越壮。