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