1. 為什么值得把 MCP 架構(gòu)拆到骨頭里第一次接觸 MCP 的人十有八九會被三個詞繞暈Host、Client、Server?？垂俜綀D覺得挺清楚一動手就發(fā)現(xiàn)——Host 到底管什么Client 和 Server 之間那條 JSON-RPC 通道是誰在維護(hù)為什么我本地跑一個 Server換個 Host 就連不上我最初也是這么過來的。當(dāng)時(shí)為了把一個內(nèi)部工具接進(jìn)編輯器前后折騰了三天最后發(fā)現(xiàn)問題根本不在代碼而在我對這三層職責(zé)的理解是錯的。所以這篇不打算復(fù)述官方文檔而是按我自己的理解路徑把 MCP 架構(gòu)一層層剝開剝到你能拿著這套認(rèn)知去排查任何連接問題為止。MCP全稱 Model Context Protocol本質(zhì)是一套讓模型應(yīng)用Host安全地調(diào)用外部能力Server的通信規(guī)范。它解決的核心問題是模型本身只會生成文本但真實(shí)任務(wù)需要讀文件、查數(shù)據(jù)庫、調(diào)接口、操作設(shè)計(jì)稿這些能力不可能全塞進(jìn)模型里必須外掛。MCP 就是那個外掛標(biāo)準(zhǔn)接口。這篇文章適合三類人一是剛聽說 MCP、想知道它到底怎么運(yùn)轉(zhuǎn)的開發(fā)者二是已經(jīng)在用某個 MCP Server 但一遇到報(bào)錯就懵的人三是準(zhǔn)備自己寫一個 MCP Server 接進(jìn)現(xiàn)有工具鏈的工程師。我會從整體設(shè)計(jì)講到 JSON-RPC 報(bào)文再講到 Host、Client、Server 各自的邊界最后給一份排查清單。全程按為什么這么設(shè)計(jì)來講而不是文檔這么寫。先把一句話結(jié)論放這兒MCP 的分層不是為了好看是為了讓能力提供方和能力使用方徹底解耦。理解了這句話后面所有細(xì)節(jié)都是它的推論。2. 整體設(shè)計(jì)三層結(jié)構(gòu)到底在解耦什么2.1 Host、Client、Server 的職責(zé)邊界很多人把 MCP 理解成客戶端-服務(wù)端兩段式這是第一個誤區(qū)。MCP 實(shí)際是三段式中間那層 Client 經(jīng)常被忽略但它恰恰是整套架構(gòu)的關(guān)鍵。我用一個生活化的類比Host 是公司Client 是公司派出去對接供應(yīng)商的采購員Server 是供應(yīng)商。公司不會直接跟供應(yīng)商打交道所有需求都通過采購員傳達(dá)供應(yīng)商也只認(rèn)采購員不關(guān)心背后是哪家公司。這個中間人設(shè)計(jì)帶來兩個直接好處一是公司換供應(yīng)商采購流程不變二是供應(yīng)商換客戶供貨方式不變。具體到職責(zé)Host模型應(yīng)用本體比如編輯器、IDE 插件、桌面助手。它負(fù)責(zé)管理會話、決定什么時(shí)候該調(diào)用哪個能力、把模型輸出和工具結(jié)果拼起來。Host 是唯一有狀態(tài)的角色它知道用戶是誰、當(dāng)前在做什么任務(wù)。ClientHost 內(nèi)部為每個 Server 創(chuàng)建的一個連接器。一個 Host 可以同時(shí)掛多個 Client每個 Client 對應(yīng)一個 Server 連接。Client 負(fù)責(zé)協(xié)議握手、消息收發(fā)、能力協(xié)商是純粹的通信管道 協(xié)議翻譯。Server能力提供方暴露具體的工具tools、資源resources、提示模板prompts。Server 不關(guān)心誰在調(diào)用只按協(xié)議響應(yīng)請求。注意一個 Host 對多個 Server 時(shí)是一個 Server 一個 Client不是共用一個 Client。這點(diǎn)在排查為什么 A 工具能用 B 工具不能用時(shí)特別關(guān)鍵——問題往往出在某個 Client 的連接上而不是 Host 整體。2.2 為什么中間要插一層 Client有人會問Host 直接連 Server 不行嗎非要加個 Client 增加復(fù)雜度答案在于連接生命周期和能力協(xié)商的隔離。Host 是長期運(yùn)行的應(yīng)用Server 可能隨時(shí)上下線、可能崩潰、可能響應(yīng)超時(shí)。如果 Host 直接管理這些連接一旦某個 Server 卡住整個 Host 都可能被拖死。把連接管理下沉到 Client 層Host 只需要面對Client 可用/不可用這個抽象不用關(guān)心底層是 stdio 還是 HTTP、是本地進(jìn)程還是遠(yuǎn)程服務(wù)。另一個原因是多 Server 并行?，F(xiàn)代 Host 往往同時(shí)掛好幾個 Server一個管文件系統(tǒng)一個管數(shù)據(jù)庫一個管設(shè)計(jì)工具。每個 Server 的啟動方式、認(rèn)證方式、協(xié)議版本可能都不同。Client 層把這些差異吸收掉Host 拿到的就是統(tǒng)一的調(diào)用接口。我實(shí)測下來這個設(shè)計(jì)在穩(wěn)定性上的收益非常明顯。之前有個 Server 因?yàn)榫W(wǎng)絡(luò)問題頻繁超時(shí)如果 Host 直接管連接整個應(yīng)用會周期性卡頓有了 Client 隔離后只有那個 Client 報(bào)錯其他工具照常工作。2.3 傳輸層stdio 與 HTTP 的取舍MCP 目前主流兩種傳輸方式stdio標(biāo)準(zhǔn)輸入輸出和HTTP含 SSE 流式。stdio 適合本地 ServerHost 直接以子進(jìn)程方式啟動 Server通過 stdin/stdout 交換 JSON-RPC 消息。優(yōu)點(diǎn)是零網(wǎng)絡(luò)配置、啟動快、天然隔離缺點(diǎn)是只能本地、進(jìn)程崩潰即斷連、不適合多 Host 共享。HTTP 適合遠(yuǎn)程 ServerServer 獨(dú)立部署多個 Host 通過網(wǎng)絡(luò)訪問。優(yōu)點(diǎn)是解耦徹底、可水平擴(kuò)展缺點(diǎn)是要處理認(rèn)證、超時(shí)、重連、CORS 等一堆網(wǎng)絡(luò)問題。選型邏輯很簡單能力在本機(jī)、只給自己用選 stdio能力要共享、要給團(tuán)隊(duì)用選 HTTP。我見過有人為了看起來專業(yè)把本地文件工具做成 HTTP Server結(jié)果每次啟動都要配端口和證書純屬自找麻煩。維度stdioHTTP部署位置本地子進(jìn)程遠(yuǎn)程獨(dú)立服務(wù)啟動方式Host 拉起進(jìn)程預(yù)先部署多 Host 共享不支持支持認(rèn)證復(fù)雜度無需要崩潰影響單連接斷開需重連機(jī)制適用場景本地工具、個人使用團(tuán)隊(duì)共享、生產(chǎn)環(huán)境3. 核心細(xì)節(jié)JSON-RPC 報(bào)文里藏著什么3.1 JSON-RPC 2.0 是 MCP 的骨架MCP 所有通信都基于JSON-RPC 2.0。這個選擇不是隨便定的——JSON-RPC 足夠簡單就四種消息類型、足夠通用任何語言都能實(shí)現(xiàn)、足夠無狀態(tài)每條消息自包含。對協(xié)議設(shè)計(jì)來說簡單意味著實(shí)現(xiàn)成本低、調(diào)試容易。JSON-RPC 2.0 只有四種消息Request帶id期待響應(yīng)。比如tools/call。Response帶相同id返回結(jié)果或錯誤。Notification不帶id不期待響應(yīng)。比如日志、進(jìn)度通知。Batch消息數(shù)組批量發(fā)送。一條典型的工具調(diào)用請求長這樣{ jsonrpc: 2.0, id: 42, method: tools/call, params: { name: read_file, arguments: { path: /tmp/demo.txt } } }對應(yīng)的響應(yīng){ jsonrpc: 2.0, id: 42, result: { content: [ { type: text, text: 文件內(nèi)容... } ] } }注意id的作用它是請求和響應(yīng)的配對標(biāo)識。因?yàn)?MCP 允許并發(fā)請求響應(yīng)可能亂序返回靠id才能對上號。我踩過的坑是自己寫 Server 時(shí)忘了回填idHost 收到響應(yīng)后無法匹配表現(xiàn)為調(diào)用一直掛起直到超時(shí)。3.2 初始化握手能力協(xié)商發(fā)生在什么時(shí)候MCP 連接建立后第一件事不是直接調(diào)工具而是initialize 握手。這一步?jīng)Q定了雙方能用哪些能力。流程是Client 發(fā)送initialize請求帶上自己的協(xié)議版本和 capabilities。Server 返回自己的協(xié)議版本、capabilities 和 serverInfo。Client 發(fā)送notifications/initialized通知握手完成。Server 的 capabilities 里會聲明它支持哪些能力比如{ capabilities: { tools: { listChanged: true }, resources: { subscribe: true }, prompts: {} } }tools.listChanged: true意味著 Server 支持在運(yùn)行中動態(tài)增刪工具并通過notifications/tools/list_changed通知 Client 刷新。這個細(xì)節(jié)很多人不知道導(dǎo)致工具更新后 Host 里還是舊的。提示如果握手階段協(xié)議版本不匹配不同實(shí)現(xiàn)的處理方式不一樣。有的直接斷開有的降級兼容。排查連上了但調(diào)不了工具時(shí)先看握手日志里的版本號。3.3 三大能力原語tools、resources、promptsMCP Server 暴露的能力分三類理解它們的區(qū)別是用好 MCP 的前提。Tools工具模型可以主動調(diào)用的函數(shù)。有輸入?yún)?shù)、有返回值、可能產(chǎn)生副作用寫文件、發(fā)請求。這是最常用的一類也是模型能干活的核心。工具調(diào)用是模型決定調(diào)什么、傳什么參數(shù)Host 負(fù)責(zé)執(zhí)行并把結(jié)果回給模型。Resources資源可以被讀取的數(shù)據(jù)。類似文件或數(shù)據(jù)庫記錄是只讀的。資源用 URI 標(biāo)識比如file:///path/to/file或db://users/123。模型不能直接調(diào)用資源而是通過 Host 把資源內(nèi)容注入上下文。Prompts提示模板預(yù)定義的提示詞模板可以帶參數(shù)。用戶或 Host 主動選擇使用不是模型自動觸發(fā)。適合把常用任務(wù)固化成模板比如代碼審查生成周報(bào)。三者的關(guān)鍵區(qū)別在于觸發(fā)方tools 由模型觸發(fā)resources 由 Host/用戶選擇注入prompts 由用戶主動選用。搞混這三者設(shè)計(jì)出來的 Server 就會很別扭——比如把只讀數(shù)據(jù)做成 tool每次都要模型調(diào)用一下才能讀純屬浪費(fèi)。原語觸發(fā)方是否只讀典型用途Tools模型否執(zhí)行操作、查詢ResourcesHost/用戶是注入上下文數(shù)據(jù)Prompts用戶是固化任務(wù)模板3.4 消息流一次工具調(diào)用的完整旅程把上面這些串起來一次完整的工具調(diào)用是這樣的用戶在 Host 里提問模型判斷需要調(diào)用某個工具。Host 找到對應(yīng) Server 的 ClientClient 發(fā)送tools/call請求。Server 執(zhí)行工具邏輯返回結(jié)果。Client 收到響應(yīng)交給 Host。Host 把結(jié)果拼進(jìn)模型上下文模型繼續(xù)生成。如果工具執(zhí)行時(shí)間長Server 可以發(fā)notifications/progress通知進(jìn)度Host 可以據(jù)此更新 UI。如果 Server 想主動告訴 Client我的工具列表變了發(fā)notifications/tools/list_changed。這條鏈路里任何一環(huán)出問題表現(xiàn)都是工具調(diào)用失敗。所以排查時(shí)要有意識地從 Host 日志、Client 日志、Server 日志三個層面分別看而不是只盯著報(bào)錯信息。4. 實(shí)操過程從零搭一個最小 MCP Server4.1 環(huán)境準(zhǔn)備與依賴選擇理論講完動手才有感覺。我用 Python 搭一個最小 Server暴露一個echo工具走 stdio 傳輸。選 Python 是因?yàn)楣俜?SDK 成熟選 stdio 是因?yàn)楸镜卣{(diào)試最省事。依賴很簡單pip install mcp官方 SDK 封裝了 JSON-RPC 的收發(fā)、握手、能力協(xié)商你只需要關(guān)注工具邏輯本身。這也是 MCP 設(shè)計(jì)的一個好處——協(xié)議細(xì)節(jié)被 SDK 吸收業(yè)務(wù)代碼保持干凈。注意SDK 版本要和 Host 支持的協(xié)議版本對齊。我遇到過 SDK 太新、Host 太舊導(dǎo)致握手失敗的情況降一個版本就好了。生產(chǎn)環(huán)境建議鎖定版本。4.2 定義工具與注冊最小 Server 的核心就是定義工具 注冊 啟動。工具定義包括名稱、描述、參數(shù) schema。描述很重要——模型是靠描述來判斷該不該調(diào)這個工具的寫得含糊模型就不會用。from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(echo-server) app.list_tools() async def list_tools(): return [ Tool( nameecho, description回顯輸入的文本用于測試連接是否正常, inputSchema{ type: object, properties: { text: {type: string, description: 要回顯的文本} }, required: [text] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name echo: return [TextContent(typetext, textarguments[text])] raise ValueError(f未知工具: {name}) async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: import asyncio asyncio.run(main())這段代碼里list_tools告訴 Client 有哪些工具call_tool處理實(shí)際調(diào)用。inputSchema用 JSON Schema 描述參數(shù)Host 會據(jù)此校驗(yàn)?zāi)Ｐ蜕傻膮?shù)。4.3 接入 Host 與驗(yàn)證把 Server 接進(jìn) Host通常是在 Host 的配置文件里加一段。以常見編輯器類 Host 為例配置大致是{ mcpServers: { echo: { command: python, args: [/path/to/echo_server.py] } } }保存后重啟 Host它就會以子進(jìn)程方式拉起這個 Server完成握手。驗(yàn)證方法是讓模型調(diào)用 echo 工具看是否返回你輸入的文本。如果沒反應(yīng)按這個順序查Server 進(jìn)程有沒有起來、握手日志有沒有報(bào)錯、工具列表有沒有加載出來、調(diào)用時(shí)參數(shù)對不對。我實(shí)測下來八成問題出在路徑寫錯或 Python 環(huán)境不對——Host 用的是系統(tǒng) Python而你裝依賴用的是虛擬環(huán)境。4.4 參數(shù)校驗(yàn)與錯誤處理工具的參數(shù)校驗(yàn)不能只靠 schema。schema 是給模型看的說明書但模型可能生成不符合 schema 的參數(shù)Host 的校驗(yàn)也可能不嚴(yán)格。所以 Server 內(nèi)部必須再校驗(yàn)一遍。錯誤處理要遵循 JSON-RPC 規(guī)范業(yè)務(wù)錯誤用isError: true標(biāo)記在結(jié)果里協(xié)議錯誤才用 error 對象。區(qū)別在于——業(yè)務(wù)錯誤比如文件不存在是模型可以理解和處理的應(yīng)該作為正常結(jié)果返回協(xié)議錯誤比如方法不存在是通信層面的問題應(yīng)該走 error 通道。app.call_tool() async def call_tool(name: str, arguments: dict): if name echo: text arguments.get(text) if not isinstance(text, str): return [TextContent(typetext, text參數(shù) text 必須是字符串)] return [TextContent(typetext, texttext)] raise ValueError(f未知工具: {name})這個區(qū)分很關(guān)鍵。如果把業(yè)務(wù)錯誤當(dāng)成協(xié)議錯誤拋出去模型看不到具體原因就沒法自我糾正。5. 常見問題與排查技巧實(shí)錄5.1 連接類問題速查連接問題是最常見的表現(xiàn)五花八門。我整理了一份速查表現(xiàn)象可能原因排查方向Host 里看不到工具Server 未啟動或握手失敗看 Host 日志、手動跑 Server調(diào)用一直掛起響應(yīng)未回填 id 或未返回檢查 Server 響應(yīng)邏輯連上后立刻斷開協(xié)議版本不匹配對齊 SDK 與 Host 版本部分工具可用部分不可用某個 Client 連接異常逐個 Server 排查工具列表不更新未發(fā) list_changed 通知檢查通知邏輯5.2 那些文檔不會寫的坑坑一stdio 模式下不要往 stdout 打日志。stdio 傳輸用 stdout 傳 JSON-RPC 消息你如果print調(diào)試信息會污染協(xié)議流導(dǎo)致 Host 解析失敗。日志一律走 stderr?？佣erver 啟動慢會被誤判為失敗。有些 Host 有啟動超時(shí)Server 初始化太慢比如要連數(shù)據(jù)庫會被殺掉。解決辦法是把耗時(shí)初始化做成懶加載握手時(shí)快速返回?？尤窂揭媒^對路徑。Host 拉起 Server 時(shí)的工作目錄不一定是你的項(xiàng)目目錄相對路徑會找不到文件。這個坑我踩過不止一次?？铀牟l(fā)調(diào)用要注意狀態(tài)。如果 Server 內(nèi)部有共享狀態(tài)多個工具并發(fā)調(diào)用可能出問題。要么加鎖要么設(shè)計(jì)成無狀態(tài)。坑五錯誤信息要寫給模型看。錯誤信息不只是給開發(fā)者看的模型也會讀。寫操作失敗模型沒法處理寫文件 /tmp/a.txt 不存在請檢查路徑模型就能自我糾正。5.3 調(diào)試工具與方法調(diào)試 MCP 最有效的方法是分層看日志。Host 日志看連接和調(diào)度Client 日志看協(xié)議收發(fā)Server 日志看業(yè)務(wù)邏輯。三層對照問題定位很快。另一個技巧是用最小 Server 驗(yàn)證 Host。當(dāng)你懷疑是 Host 配置問題時(shí)接一個最簡單的 echo Server 上去。如果 echo 能用說明 Host 沒問題問題在你的 Server如果 echo 也不能用問題在 Host 配置或環(huán)境。還有個土辦法但很管用手動構(gòu)造 JSON-RPC 消息。用管道把 initialize 請求喂給 Server看它返回什么。這能繞過 Host直接驗(yàn)證 Server 的協(xié)議實(shí)現(xiàn)是否正確。echo {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}}} | python echo_server.py看輸出里有沒有正確的 initialize 響應(yīng)就能判斷 Server 的握手實(shí)現(xiàn)對不對。5.4 性能與穩(wěn)定性建議工具調(diào)用是同步等待的長耗時(shí)工具會阻塞。如果工具有耗時(shí)操作建議拆成提交任務(wù) 查詢結(jié)果兩步或者用進(jìn)度通知讓 Host 知道還在跑。Server 要能扛住異常。工具內(nèi)部拋異常要捕獲并轉(zhuǎn)成業(yè)務(wù)錯誤返回不能讓異常穿透到協(xié)議層導(dǎo)致連接斷開。我見過一個 Server 因?yàn)闆]捕獲異常一次調(diào)用失敗后整個連接就廢了所有工具都用不了。資源占用也要注意。stdio 模式下每個 Host 會拉起一個 Server 進(jìn)程如果 Server 內(nèi)存占用大多開幾個 Host 就吃不消。這種情況考慮改成 HTTP 共享部署。6. 我對 MCP 架構(gòu)的一點(diǎn)個人體會把 MCP 拆到這一層你會發(fā)現(xiàn)它的設(shè)計(jì)其實(shí)很克制三層職責(zé)清晰、協(xié)議簡單、能力原語只有三個。這種克制帶來的好處是你不需要記住一堆復(fù)雜規(guī)則只要抓住Host 管狀態(tài)、Client 管連接、Server 管能力這條主線大部分問題都能自己推出來。我自己最大的收獲是理解了解耦的價(jià)值。以前寫工具集成總是把業(yè)務(wù)邏輯和通信邏輯攪在一起改一處動全身。MCP 逼著你把能力提供和能力使用分開短期看是多寫了一層長期看維護(hù)成本低得多。如果你正準(zhǔn)備寫自己的 MCP Server我的建議是先跑通最小 echo 版本確認(rèn)握手和調(diào)用鏈路沒問題再往里加業(yè)務(wù)邏輯。別一上來就寫復(fù)雜工具那樣出了問題你分不清是協(xié)議層還是業(yè)務(wù)層。另外日志一定走 stderr路徑一定用絕對路徑錯誤信息一定寫給模型看——這三條能幫你省下大量調(diào)試時(shí)間。