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