1. 從單體到模塊化MCP Server 拆分到底解決什么問題如果你正在做 AI 工具中樞大概率遇到過這種局面一開始所有工具都塞在一個server.py里注冊表、路由、鑒權(quán)、模型調(diào)用全混在一起。工具從 3 個漲到 30 個之后改一個天氣查詢工具的參數(shù)校驗(yàn)結(jié)果把代碼檢索工具的調(diào)用鏈弄崩了。這就是典型的單體 MCP Server 困境。MCP Server 模塊化拆分說白了就是把「協(xié)議處理」「工具注冊」「資源訪問」「模型通道」這幾件事拆成邊界清晰的獨(dú)立模塊讓每個模塊只對自己那攤事負(fù)責(zé)。它適合誰適合正在把內(nèi)部工具鏈接入 AI Agent 的開發(fā)者尤其是需要同時(shí)對接多個模型供應(yīng)商、工具數(shù)量還在持續(xù)增長的團(tuán)隊(duì)。我試過最直接的對比單體架構(gòu)下新增一個工具平均要動 4 個文件、跑一遍全量回歸拆成模塊后新增工具只寫一個tools/xxx_tool.py加一行注冊核心路由代碼零改動?？蓴U(kuò)展性和可維護(hù)性的差距在工具數(shù)量超過 10 個之后就非常明顯了。這篇文章不講空泛的架構(gòu)圖而是給你一套能直接跑的拆分方案模塊邊界怎么劃、工具怎么注冊、路由怎么配以及如何用 TaoToken 的統(tǒng)一 Key 把多模型調(diào)用收斂到一個 API 通道最后完成一次端到端驗(yàn)證。核心檢索詞就三個MCP Server 模塊化拆分、可擴(kuò)展 AI 工具中樞、統(tǒng)一 Key 多模型接入。先說清楚模塊邊界劃分的原則這是整個拆分的地基。我的經(jīng)驗(yàn)是按「變化頻率」和「依賴方向」兩個維度切變化頻率高的放外層。工具的具體實(shí)現(xiàn)天天改模型供應(yīng)商可能隨時(shí)換這些都屬于易變部分應(yīng)該獨(dú)立成模塊。變化頻率低的核心協(xié)議解析、請求生命周期管理放在內(nèi)層穩(wěn)定模塊。依賴方向必須單向。工具模塊可以依賴核心模塊暴露的接口但核心模塊絕不能反向 import 具體工具。一旦出現(xiàn)循環(huán)依賴模塊化就名存實(shí)亡了。判斷標(biāo)準(zhǔn)很簡單刪掉任意一個工具模塊核心模塊應(yīng)該還能正常啟動。落到具體目錄我推薦這樣的結(jié)構(gòu)mcp_server/ ├── core/ # 穩(wěn)定層協(xié)議、路由、生命周期 │ ├── protocol.py # MCP 協(xié)議解析與響應(yīng)格式化 │ ├── router.py # 請求路由與工具分發(fā) │ └── registry.py # 模塊與工具注冊中心 ├── modules/ # 業(yè)務(wù)層按領(lǐng)域拆分 │ ├── tools/ # 工具模塊 │ │ ├── code_search.py │ │ └── weather.py │ └── resources/ # 資源模塊 │ └── file_access.py ├── providers/ # 模型通道層統(tǒng)一走 TaoToken │ └── llm_client.py └── config/ └── settings.toml這個結(jié)構(gòu)的關(guān)鍵在于providers單獨(dú)成層。很多人把模型調(diào)用散落在各個工具里結(jié)果換一個模型要改十幾處。把 LLM 客戶端收斂成一層所有工具通過統(tǒng)一接口調(diào)用后面接 TaoToken 就只需要改這一層。模塊邊界劃好之后每個模塊對外只暴露兩樣?xùn)|西路由聲明和錯誤處理器。內(nèi)部實(shí)現(xiàn)隨便你怎么寫核心層不關(guān)心。這就是高內(nèi)聚低耦合的落地方式也是后面工具注冊和路由配置能自動化運(yùn)轉(zhuǎn)的前提。2. TaoToken 前置準(zhǔn)備統(tǒng)一 Key 與 API 通道配置模塊化拆分解決的是代碼結(jié)構(gòu)問題但多模型接入還有另一個痛點(diǎn)每個模型供應(yīng)商一套 Key、一套 Base URL、一套鑒權(quán)格式。工具模塊越多散落的憑證管理越亂。這一步我們用 TaoToken 把模型通道統(tǒng)一起來讓所有工具模塊通過一個 Key 訪問多個模型。TaoToken 在這里扮演的角色是統(tǒng)一 API 通道你拿到一個 Key配置一個 Base URL就能在工具模塊里調(diào)用不同模型不用為每個供應(yīng)商單獨(dú)維護(hù)客戶端。對模塊化架構(gòu)來說這正好契合providers層的設(shè)計(jì)——通道層只認(rèn)一個入口工具層完全不感知底層是哪個模型。先拿 Key。訪問控制臺創(chuàng)建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite創(chuàng)建時(shí)建議按用途分 Key比如mcp-dev、mcp-prod各一個方便后續(xù)按 Key 做用量隔離和吊銷。Key 只在創(chuàng)建時(shí)完整顯示一次復(fù)制后立刻存進(jìn)環(huán)境變量別硬編碼進(jìn)代碼。拿到 Key 之后把 Base URL 和 Key 寫進(jìn)環(huán)境變量。這是模塊化項(xiàng)目里最省事的做法配置和代碼分離export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意 Base URL 用https://taotoken.net/api不帶任何查詢參數(shù)。很多 401 報(bào)錯就是因?yàn)榘褞?UTM 的官網(wǎng)地址誤填進(jìn)了 Base URL這個坑后面排障章節(jié)會細(xì)說。接下來在providers/llm_client.py里封裝統(tǒng)一客戶端。這一層是模塊化的關(guān)鍵工具模塊只調(diào)用LLMClient.chat()不關(guān)心底層通道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 就能對接因?yàn)?TaoToken 的 API 通道遵循兼容格式。Model ID 通過參數(shù)傳入工具模塊想用哪個模型就傳哪個通道層不做硬編碼。這樣設(shè)計(jì)的好處是以后新增模型工具代碼一行不用改。如果你需要確認(rèn)當(dāng)前可用的 Model ID 列表可以直接在模型對話頁面測試https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite在頁面上選模型、發(fā)一條測試消息能正常返回就說明 Key 和通道都沒問題。這一步建議在寫工具代碼之前先做避免后面調(diào)試時(shí)把通道問題和代碼問題混在一起排查。配置階段還有一件事把settings.toml里的模型通道參數(shù)抽出來別寫死在代碼里。模塊化項(xiàng)目最忌諱配置散落各處集中管理后續(xù)換環(huán)境才不痛苦[provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet-4-5 timeout 60api_key_env存的是環(huán)境變量名而不是 Key 本身這樣配置文件可以安全提交到倉庫。工具模塊讀取配置時(shí)通過os.environ[config.provider.api_key_env]取值既統(tǒng)一又安全。前置準(zhǔn)備做到這里通道層就緒可以進(jìn)入模塊注冊和路由配置了。3. 可復(fù)制配置工具注冊與路由的模塊化實(shí)現(xiàn)這一節(jié)是全文的技術(shù)核心給你一套能直接復(fù)制的模塊注冊與路由配置。模塊化拆分能不能落地就看工具注冊是否自動化、路由是否解耦。先定義模塊基類。所有工具模塊繼承它核心層只依賴這個抽象不依賴任何具體工具# 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 []然后是注冊中心。它維護(hù)一個工具名到處理函數(shù)的映射核心層通過它分發(fā)請求# 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))核心路由只做一件事查表分發(fā)。它不知道也不關(guān)心具體工具怎么實(shí)現(xiàn)# 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)現(xiàn)在寫一個具體工具模塊。注意它只依賴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}啟動時(shí)把所有模塊注冊進(jìn)去新增工具只需要在列表里加一行# 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)這套配置的可擴(kuò)展性體現(xiàn)在新增一個天氣工具你只寫modules/tools/weather.py然后在main.py加一行registry.register(WeatherModule(llm))。核心路由、注冊中心、通道層全部零改動。這就是模塊化拆分帶來的實(shí)際收益。如果你用的是 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 走環(huán)境變量注入Model ID 在工具模塊調(diào)用時(shí)指定。這樣配置的好處是同一個 MCP Server 進(jìn)程里不同工具可以用不同模型但共享同一個通道憑證。路由配置還有一個容易忽略的點(diǎn)錯誤處理器也要按模塊注冊。工具模塊自己定義錯誤類型和對應(yīng)的響應(yīng)格式核心層統(tǒng)一捕獲。這樣某個工具拋異常不會污染其他模塊的響應(yīng)結(jié)構(gòu)。把get_error_handlers()返回的列表在注冊時(shí)一并掛到核心錯誤處理器上模塊的自治性就完整了。4. 端到端驗(yàn)證一次完整調(diào)用與成功結(jié)果配置寫完必須驗(yàn)證否則你不知道是通道問題還是代碼問題。這一節(jié)走一遍完整的端到端調(diào)用從啟動服務(wù)到拿到模型返回。先做最小驗(yàn)證不啟動 MCP Server直接測通道層能不能通。這一步能把 TaoToken 配置問題和業(yè)務(wù)代碼問題徹底分開# verify_channel.py from providers.llm_client import LLMClient llm LLMClient() out llm.chat( modelclaude-sonnet-4-5, messages[{role: user, content: 只回復(fù)兩個字通了}], ) print(out)運(yùn)行python verify_channel.py如果打印出「通了」說明 Key、Base URL、Model ID 三件套全部正確。如果這一步就報(bào)錯直接跳到第 5 節(jié)排障別往下走。通道驗(yàn)證通過后啟動 MCP Server 并測試路由分發(fā)。用一個簡單的 HTTP 請求模擬工具調(diào)用curl -X POST http://127.0.0.1:8080/tools/code_search \ -H Content-Type: application/json \ -d {query: 如何做模塊化拆分}預(yù)期返回結(jié)構(gòu){ status: ok, result: 模塊化拆分的核心是按變化頻率劃分邊界…… }看到status: ok且result有實(shí)際內(nèi)容說明整條鏈路通了請求進(jìn)入核心路由 → 查表分發(fā)到CodeSearchModule→ 模塊調(diào)用LLMClient→ 通道層走 TaoToken → 模型返回 → 逐層回傳。再驗(yàn)證模塊化的關(guān)鍵特性新增模塊不影響已有模塊。臨時(shí)加一個 echo 工具只回顯不調(diào)模型# 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能正常返回同時(shí)/tools/code_search依然工作。這就證明了模塊之間互不干擾可擴(kuò)展性達(dá)標(biāo)。如果你要驗(yàn)證更復(fù)雜的多模型場景可以在同一個 Server 里讓兩個工具用不同 Model ID都走同一個 TaoToken 通道。比如代碼檢索用claude-sonnet-4-5文本摘要用另一個模型觀察兩者是否都能正常返回。這一步能驗(yàn)證通道層對多模型的支持是否到位。驗(yàn)證階段建議記錄三個指標(biāo)首次請求延遲、連續(xù) 10 次請求的成功率、模塊注冊后的啟動時(shí)間。模塊化架構(gòu)下啟動時(shí)間應(yīng)該隨模塊數(shù)量線性增長而不是指數(shù)增長如果發(fā)現(xiàn)啟動明顯變慢多半是模塊間出現(xiàn)了隱式依賴回到第 1 節(jié)的邊界原則檢查。端到端跑通之后你就有了一套可工作的模塊化 MCP Server。接下來把它接入實(shí)際客戶端比如在 Claude Code 里通過 MCP 配置調(diào)用這些工具。接入文檔在這里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite文檔里有不同客戶端的接入示例照著改 Base URL 和 Key 即可。驗(yàn)證通過再進(jìn)入生產(chǎn)使用別跳過這一步直接上量。5. 常見報(bào)錯排查401、local proxy failed 與 choices 解析模塊化項(xiàng)目調(diào)試時(shí)報(bào)錯往往橫跨通道層、路由層、工具層定位困難。這一節(jié)按真實(shí)報(bào)錯逐個拆解幫你快速定位問題出在哪一層。401 Unauthorized。這是最高頻的報(bào)錯幾乎都出在通道層。排查順序先確認(rèn)TAOTOKEN_API_KEY環(huán)境變量在當(dāng)前 shell 里真的存在用echo $TAOTOKEN_API_KEY看有沒有值再確認(rèn) Key 沒有多余空格或換行復(fù)制時(shí)很容易帶上最后確認(rèn) Key 沒有過期或被吊銷。如果環(huán)境變量對但依然 401檢查代碼里是不是硬編碼了舊 Key 覆蓋了環(huán)境變量。local proxy failed / connection refused。這個報(bào)錯通常不是 TaoToken 的問題而是本地網(wǎng)絡(luò)或 Base URL 配置錯誤。先確認(rèn)TAOTOKEN_BASE_URL填的是https://taotoken.net/api不是官網(wǎng)首頁地址。很多人把帶?utm_source...的完整官網(wǎng)鏈接填進(jìn) Base URL導(dǎo)致請求路徑拼接錯誤。Base URL 只到/api后面的路徑由 SDK 自己拼。reading choices of undefined。這個報(bào)錯說明響應(yīng)結(jié)構(gòu)和你代碼里取值的路徑對不上。常見原因是resp.choices[0]里choices為空或者返回的是錯誤對象而不是正常響應(yīng)。排查方法在LLMClient.chat()里先打印完整resp看實(shí)際返回結(jié)構(gòu)。如果是錯誤響應(yīng)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 或類似客戶端報(bào) OAuth 相關(guān)錯誤通常是客戶端的鑒權(quán)配置和 MCP Server 的通道配置沖突了。檢查客戶端配置里的env是否正確注入了TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL。三件套缺任何一個都會導(dǎo)致鑒權(quán)失敗。特別注意客戶端配置里的環(huán)境變量不會自動繼承你 shell 里的變量必須在配置里顯式寫。模塊注冊后路由 404。這個報(bào)錯出在路由層不是通道層。排查確認(rèn)模塊的get_routes()返回的 path 和請求 path 完全一致包括大小寫和斜杠確認(rèn)模塊真的被registry.register()調(diào)用了確認(rèn)注冊發(fā)生在服務(wù)啟動之前。模塊化架構(gòu)下 404 基本都是注冊遺漏不是路由邏輯問題。工具調(diào)用超時(shí)。如果通道驗(yàn)證通過但工具調(diào)用超時(shí)多半是工具模塊內(nèi)部邏輯阻塞了事件循環(huán)。檢查工具處理函數(shù)里有沒有同步的耗時(shí)操作比如同步文件讀寫、同步 HTTP 請求直接跑在 async 函數(shù)里。這類操作要用run_in_executor包起來否則會卡住整個 Server。排障的核心思路是分層定位先測通道層verify_channel.py再測路由層curl 直連最后測工具層具體業(yè)務(wù)邏輯。哪一層先失敗問題就在哪一層。別一上來就改業(yè)務(wù)代碼那樣只會把問題攪得更亂。如果排障過程中需要確認(rèn) Key 狀態(tài)或重新生成回到控制臺https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite控制臺能看到每個 Key 的創(chuàng)建時(shí)間和最近使用情況方便判斷是不是 Key 本身的問題。排障完成后建議把驗(yàn)證腳本保留在倉庫里下次環(huán)境變更時(shí)直接跑一遍比手動排查快得多。6. 長期編碼與 Agent 場景把模塊化中樞用起來模塊化拆分做完、端到端驗(yàn)證通過之后這套 MCP Server 真正的價(jià)值在于長期使用。如果你打算把它作為日常編碼和 Agent 任務(wù)的工具中樞有幾個實(shí)踐建議。第一把工具按使用頻率分層。高頻工具代碼檢索、文件訪問保持輕量啟動即加載低頻工具報(bào)表生成、批量處理做成按需加載減少啟動開銷。模塊化架構(gòu)天然支持這種分層因?yàn)槊總€模塊獨(dú)立加載策略可以按模塊配置。第二模型通道層加一層緩存和重試。工具調(diào)用模型時(shí)相同請求可以緩存結(jié)果減少重復(fù)消耗網(wǎng)絡(luò)抖動時(shí)自動重試避免單次失敗影響 Agent 任務(wù)。這些邏輯都收斂在providers層不影響工具模塊。第三為 Agent 場景準(zhǔn)備 Coding Plan。如果你要讓 Agent 長時(shí)間自主執(zhí)行編碼任務(wù)按量計(jì)費(fèi)可能不好控制成本包月方案更合適https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteCoding Plan 適合需要持續(xù)調(diào)用模型、任務(wù)周期長的場景。模塊化 MCP Server 配合包月通道Agent 可以放心跑長任務(wù)不用擔(dān)心單次調(diào)用成本失控。第四給每個工具模塊寫清楚輸入輸出契約。Agent 調(diào)用工具時(shí)依賴工具描述來決定用哪個工具描述模糊會導(dǎo)致 Agent 選錯工具。每個模塊的get_routes()旁邊配上參數(shù) schema 和用途說明Agent 的調(diào)用準(zhǔn)確率會明顯提升。第五定期清理不再使用的模塊。模塊化的好處是刪除模塊很干凈但前提是你真的去刪。每季度過一遍工具使用日志把三個月沒被調(diào)用的模塊下線保持中樞精簡。工具越多Agent 的選擇成本越高不是越多越好。最后說一個實(shí)際經(jīng)驗(yàn)?zāi)K化拆分不是一次性的架構(gòu)動作而是持續(xù)演進(jìn)的習(xí)慣。每次新增工具時(shí)問自己一句「這個工具應(yīng)該屬于哪個模塊還是需要新開一個模塊」邊界就會越來越清晰。一開始可能拆得不完美但只要有單向依賴和清晰注冊這兩個約束在架構(gòu)就不會腐化。這套方案跑下來你得到的不只是一個能用的 MCP Server而是一個能持續(xù)接工具、換模型、擴(kuò)規(guī)模的中樞。核心就三件事邊界按變化頻率劃、注冊自動化、通道統(tǒng)一走 TaoToken。剩下的就是不斷往里加工具讓它越長越壯。