MCP 這個縮寫最近在 AI 工具鏈的圈子里幾乎天天被提起如果你翻過一些相關(guān)技術(shù)帖應(yīng)該對 Model Context Protocol模型上下文協(xié)議有印象。我自己的感覺是MCP 正在把AI 接入外部工具這件事從手工作坊推進到標準件時代。以前接一個工具要寫一堆膠水代碼現(xiàn)在大家照著協(xié)議來就行。這篇文章不聊概念史直接聊開發(fā)——怎么從零開始寫一個真正的 MCP Server 和 Tool順便把我自己踩過的坑、測試下來好用的調(diào)試方式、以及上線部署前那些容易忽略的細節(jié)都梳理一遍。如果你正準備用 MCP 把自家業(yè)務(wù)能力開放給 AI 客戶端或者想讓本地 Agent 能調(diào)用幾個內(nèi)部工具這篇文章應(yīng)該能讓你少走不少彎路。1. 為什么是 MCP以及它的核心運行邏輯1.1 從集成地獄到統(tǒng)一協(xié)議在 MCP 出現(xiàn)之前AI 應(yīng)用要接一個外部工具基本是每條鏈路單獨對接。比如你的 AI 助手要查數(shù)據(jù)庫、查工單系統(tǒng)、查內(nèi)部文檔那就得給每個系統(tǒng)各寫一套函數(shù)調(diào)用邏輯還要處理認證、輸入輸出格式、錯誤重試這些重復(fù)工作。我見過不少團隊維護著四五套互不兼容的工具適配層純粹是為了讓 LLM 能調(diào)用不同后端。MCP 的思路很樸素把AI 應(yīng)用和外部工具/數(shù)據(jù)源之間的一致性接口抽出來做成一個標準協(xié)議。所有工具統(tǒng)一暴露成 MCP Server所有 AI 應(yīng)用統(tǒng)一通過 MCP Client 去調(diào)用。這樣工具只承擔實現(xiàn)協(xié)議的成本AI 應(yīng)用只承擔連接協(xié)議的成本兩邊解耦。1.2 三個核心角色一次完整的 MCP 調(diào)用涉及三個角色Host承載 AI 應(yīng)用的主體比如桌面端 AI 助手、IDE 插件、網(wǎng)關(guān)服務(wù)。它負責把用戶意圖交給模型再把模型想調(diào)用工具的意圖轉(zhuǎn)給 Client。Client就是 Host 內(nèi)部集成的一個庫負責和 Server 建立連接、發(fā)請求、收結(jié)果。Client 通常不需要你手寫用官方 SDK 即可。Server真正干活的進程暴露出 tools、resources、prompts 三類能力核心是 tools。打個比方Host 是餐廳顧客Client 是服務(wù)員Server 是后廚。顧客說來一份少鹽的番茄炒蛋服務(wù)員把需求轉(zhuǎn)述給后廚后廚按標準流程做菜并端回來。這個標準流程就是 MCP 要定義的東西。1.3 通信機制JSON-RPC 2.0 與兩種傳輸方式MCP 的通信協(xié)議基于 JSON-RPC 2.0這個消息格式本身不復(fù)雜——method、params、result、error 四個字段打天下。但真正影響開發(fā)體驗的是傳輸層目前主流有兩條路stdioServer 以子進程方式啟動Host 通過標準輸入輸出跟它通信。好處是零網(wǎng)絡(luò)配置、天然安全適合本地個人工具。HTTP SSEServer-Sent EventsServer 作為一個遠程服務(wù)客戶端通過 HTTP 發(fā)請求、通過 SSE 收推送。適合多客戶端同時訪問、需要鑒權(quán)、需要跨機器部署的生產(chǎn)場景。開發(fā)初期先用 stdio 跑通邏輯再遷移到 HTTP這是最穩(wěn)妥的路徑。直接上 HTTP 容易把協(xié)議實現(xiàn)和網(wǎng)絡(luò)問題兩個變量攪在一起排查起來頭疼。2. 動手選型語言與 SDK 的取舍2.1 語言怎么選MCP 目前最成熟的官方 SDK 是 Python 和 TypeScript。Python 生態(tài)在 AI 領(lǐng)域積累深FastMCP 這類封裝可以讓你用更少的樣板代碼做更多事適合內(nèi)部工具或快速原型。TypeScript 在前端和后端領(lǐng)域滲透率高如果團隊已有 Node.js 基礎(chǔ)設(shè)施那選 TypeScript 能更好地復(fù)用現(xiàn)有工程體系。其他語言比如 Java、Go、Ruby、PHP 也有社區(qū)版或官方出品的 SDK但是成熟度和文檔完整度參差不齊。我的觀點是第一優(yōu)先選 Python 或 TS除非你的服務(wù)端基建非常單一比如全公司只有 Go那再用 Go 的 MCP 庫。2.2 一個 Server 可以掛多種能力的組合不要把 Server 理解成一個工具它是一個能力容器。你可以把一個 Server 設(shè)計成統(tǒng)一的內(nèi)部數(shù)據(jù)查詢臺里面同時注冊數(shù)據(jù)查詢 Tool、指標字典 Resource、對話排障 Prompt。這樣客戶端只需要連一個 Server就能得到一整組能力。開發(fā)時也可以按域拆多個 Server比如訂單域庫存域按需連接。2.3 選 FastMCP 還是底層 SDKPython 生態(tài)里直接用官方 SDK 寫一個 MCP Server 會有不少模板代碼比如初始化 Server 對象、注冊 handler、做生命周期管理。而 FastMCP 這個庫把注冊工具的方式簡化到一個裝飾器幾乎就是寫普通函數(shù)。我用下來更推薦 FastMCP它把樣板代碼壓得很低核心邏輯的辨識度很高后面接 HTTP 傳輸也只需要改一行。TypeScript 官方 SDK 目前做得也不錯默認提供清晰的 Transport 抽象底層控制力更強。如果你對協(xié)議本身有定制需求用底層 SDK 會更順手。3. 用一個 QueryTool 講透 Server 開發(fā)全過程3.1 場景與目標我拿一個模擬場景來演示開發(fā)一個訂單查詢工具 MCP Server接收一個訂單號返回訂單狀態(tài)、金額、下單時間。這個工具如果接入到 AI 客服系統(tǒng)里用戶一句幫我看看我 20240401 的訂單AI 就會自動查出來。放棄暴力的把數(shù)據(jù)庫接入給 AI方案采用 QueryTool 方案的原因是數(shù)據(jù)庫直接暴露給 LLM 風險極大表結(jié)構(gòu)容易泄漏、SQL 容易被亂寫、生產(chǎn)庫有被拖垮的風險。而 Tool 方案有完全可控的入?yún)ⅰ⒖上拗频牟樵冞壿?、可追加的?quán)限校驗。3.2 項目初始化和依賴安裝先建一個干凈的虛擬環(huán)境mkdir mcp-order-server cd mcp-order-server python -m venv .venv source .venv/bin/activate pip install mcp[cli]1.2.0 fastmcp裝完確認版本python -c import fastmcp; print(fastmcp.__version__)如果啟用了其他集成 Sdk比如生態(tài)工具包也一并裝好。這是標準前置步驟。3.3 核心代碼三層結(jié)構(gòu)一次寫清下面是一個結(jié)構(gòu)清晰的最小實現(xiàn)代碼可以直接復(fù)用骨架# server.py from fastmcp import FastMCP mcp FastMCP(訂單查詢服務(wù)) def _get_order_from_db(order_id: str) - dict: # 真實項目這里會走數(shù)據(jù)訪問層控權(quán)限、加監(jiān)控 # 示例中返回模擬數(shù)據(jù) return { order_id: order_id, status: 已發(fā)貨, amount: 299.00, created_at: 2024-04-01 10:22:00 } mcp.tool() def query_order(order_id: str) - dict: 根據(jù)訂單號查詢訂單狀態(tài)、金額和創(chuàng)建時間。 Args: order_id: 完整的訂單號例如 2024040112034567。 if not order_id or len(order_id) 10: return {error: 訂單號格式不正確} return _get_order_from_db(order_id) mcp.resource(order://{order_id}) def order_resource(order_id: str) - dict: 以 Resource 方式暴露只讀數(shù)據(jù)便于描述性引用。 return _get_order_from_db(order_id) if __name__ __main__: mcp.run(transportstdio)這段代碼里最需要注意的是mcp.tool()下面的函數(shù)注釋。MCP 對工具的 JSON Schema 是根據(jù)函數(shù)的簽名和注釋自動生成的。docstring 里對參數(shù)的說明寫得多清楚AI 調(diào)用工具時就有多明白。不少人圖省事不寫參數(shù)說明結(jié)果 AI 調(diào)用時總是把字段名猜錯這就是常見的工具在模型眼里是黑盒問題。mcp.run(transportstdio)這行是入口告訴 FastMCP 用 stdio 模式啟動。等代碼跑通后把 transport 改成http即可切到遠程模式我后面第 5 章會專門討論部署切換的細節(jié)。3.4 啟動并接入客戶端本地驗證最簡單的辦法是用 MCP Inspector 這個官方的調(diào)試界面。命令行執(zhí)行mcp dev server.py這個命令會把服務(wù)啟動到調(diào)試模式然后自動打開一個本地的 Inspector 頁面。在頁面里你可以直觀地看到 Server 暴露出的工具名、工具描述、JSON Schema以及你直接模擬調(diào)用之后返回的結(jié)果。我自己的習慣是先在這里把函數(shù)調(diào)用通了再接到任何上層客戶端。如果接到支持 MCP 的桌面端 AI 客戶端在配置里填入命令python /path/to/server.pySSE 遠程模式則填https://your-domain.com/mcp第一次接桌面端時注意看客戶端有沒有在工具列表里掃到query_order。如果遲遲掃不到優(yōu)先懷疑 Server 啟動時報錯了正常啟動的進程會有握手日志建議先用 Inspector 確認端口。3.5 一個突發(fā)的邊界問題參數(shù)格式校驗我實際測試這個 QueryTool 時遇到一個很有意思的情況AI 在調(diào)用query_order時傳入的order_id是202404011203465這種長度但字段本身被偷偷加了空格或者帶了前綴#ORD-。如果你不做入?yún)⑶逑凑埱髸蜻M數(shù)據(jù)庫層才失敗錯誤信息又長又難看。所以我在工具里加了一個顯式的 clean 和校驗邏輯mcp.tool() def query_order(order_id: str) - dict: 根據(jù)訂單號查詢訂單狀態(tài)、金額和創(chuàng)建時間。 Args: order_id: 訂單號需要是純數(shù)字字符串。 order_id order_id.strip().removeprefix(ORD-) if not order_id.isdigit() or len(order_id) ! 16: return {error: 訂單號格式不正確應(yīng)為16位純數(shù)字} return _get_order_from_db(order_id)不要迷信AI 一定會傳干凈的參數(shù)LLM 的輸出在格式上天然具有不確定性。一個 Tool 除了核心邏輯必須自己兜住入?yún)⑿ｒ灐＿@個習慣能省掉大量下游異常排查。4. 調(diào)試、測試與為什么工具調(diào)用總是失敗4.1 日志與輸出的隔離陷阱開發(fā) MCP Server 時最容易被表象迷惑的就是日志。你如果在代碼里用了print()來調(diào)試在 stdio 模式下這些 print 內(nèi)容會直接打到 stdout 上而 stdout 正是 MCP 協(xié)議通信的通道。這樣會直接污染協(xié)議流導(dǎo)致客戶端解析失敗表現(xiàn)為連接成功但收不到工具列表或調(diào)用時超時。正確的做法是全部用logging模塊并把日志打到 stderrimport logging logging.basicConfig(levellogging.DEBUG) logger logging.getLogger(mcp-order-server) logger.info(query_order called with %s, order_id)本地排查協(xié)議問題先分清三層第一層Server 有沒有正常啟動看進程日志。第二層工具的 JSON Schema 有沒有生成看 Inspector。第三層工具調(diào)用結(jié)果是否正常返回看 Inspector 模擬調(diào)用。多數(shù)工具失效問題都卡在第二三層很少需要抓原始 TCP 包。4.2 測試策略單測之外補一輪帶 LLM 的端到端測試傳統(tǒng)的工具開發(fā)者容易犯的毛病是只做單元測試把函數(shù)邏輯測通了就以為大功告成。但 MCP 工具層的特殊性在于真正調(diào)用它的是 LLMLLM 對工具的理解與你代碼里的 docstring 直接相關(guān)。你注釋里寫訂單號需要是16位純數(shù)字AI 如果是先脫敏后傳參大概率是對的但如果文檔描述模糊AI 可能會傳余額字段來查訂單或者把order_id寫成了orderNumber。我的經(jīng)驗是加一層端到端測試準備 5-10 個真實風格的自然語言問句。跑一個帶工具的客戶端會話讓它依次回答這些問題。人工檢查 AI 每次調(diào)用工具時的參數(shù)是否如預(yù)期。這種做法能提前發(fā)現(xiàn)大量看起來工具能用、接上 AI 就不能用的問題。4.3 命名的坑use tool 名的語義要收斂工具命名直接影響 LLM 的識別準確率。比如你把一個查訂單狀態(tài)的工具命名為get_dataLLM 可能分不清它到底是查訂單、查庫存還是查物流調(diào)用成功率會明顯下降。更推薦的做法是把工具名設(shè)計成動詞業(yè)務(wù)對象如query_order_status、query_inventory_quantity。工具的 description 也可以寫得像一句明確的能力聲明比如查詢訂單的實時狀態(tài)和配送進度輸入訂單號即可。我在多個命名實驗中發(fā)現(xiàn)描述里把不支持的能力也順帶寫進去如不包含物流軌跡物流軌跡另查 trade_logistics可以顯著減少錯誤調(diào)用。5. 遠程化部署stdio 轉(zhuǎn) HTTP 的完整過渡5.1 生命周期管理的變化本地 stdio 模式下Server 的生命周期跟客戶端進程一致——客戶端啟動它啟動客戶端退出它退出。轉(zhuǎn)成 HTTP 模式后Server 變成常駐服務(wù)需要考慮四個原來沒有的問題并發(fā)多個客戶端同時連上每個請求是否安全隔離。鑒權(quán)誰有權(quán)限調(diào)用工具。超時與重試網(wǎng)絡(luò)請求什么時候算失敗。審計工具被誰調(diào)用、每次傳了什么參數(shù)。FastMCP 如果需要開啟 HTTP 模式需要加一個額外的異步服務(wù)器入口from fastmcp import FastMCP mcp FastMCP(訂單查詢服務(wù)) # ... 工具定義 ... if __name__ __main__: mcp.run(transporthttp, host0.0.0.0, port8080)啟動后HTTP 服務(wù)提供一個端點客戶端通過配置這個 URL 建立 SSE 流式連接。注意這里跟普通 REST API 的區(qū)別MCP 的 HTTP 傳輸并不是每次請求打一次接口這么簡單它需要建立一個持久化的 SSE 通道讓服務(wù)端可以主動給客戶端推送事件。這個語義的轉(zhuǎn)變意味著你的負載均衡、健康檢查配置也要跟著調(diào)整不能簡單按 HTTP 請求數(shù)來壓測。5.2 鑒權(quán)與多租戶隔離遠程化之后第一個要解決的問題是鑒權(quán)。MCP 官方協(xié)議目前提供的鑒權(quán)方案可以內(nèi)嵌 OAuth 2.1 流程也可以直接加在反向代理層。我實際部署時的做法是統(tǒng)一走公司內(nèi)部網(wǎng)關(guān)網(wǎng)關(guān)層完成單點登錄認證生成短期 token。MCP Server 每次收到請求都驗證 token并從 token 里解析出用戶身份和角色。在 Tool 函數(shù)內(nèi)部根據(jù)身份做數(shù)據(jù)權(quán)限過濾。舉個具體場景同樣是query_order普通客服角色只能查自己團隊負責的訂單而大區(qū)總監(jiān)可以查整個大區(qū)訂單。這一切不能靠 LLM 自覺必須在 Server 里硬編碼權(quán)限邊界。你要清楚一個事實LLM 可以騙一個沒有鑒權(quán)的工具所以所有危險操作都必須有一層硬校驗——比如只允許 SELECT、不允許 UPDATE。5.3 日志、監(jiān)控、限流生產(chǎn)級部署別忘了打日志。我的建議是從第一版上線就只有意識地記錄三個信息時間戳與唯一請求 ID。入?yún)⒄⒁饷撁羟f別整單號全量打進去。響應(yīng)狀態(tài)、耗時、最終用戶身份。限流層面面向內(nèi)部使用可以先做全局限流比如每客戶端每分鐘最多 60 次調(diào)用。如果工具推動的是 LLM 調(diào)用LLM 的循環(huán)調(diào)用有時會產(chǎn)生突發(fā)流量不加限流底層數(shù)據(jù)庫或第三方依賴很容易被打滿。我在一臺測試機上曾見過循環(huán)調(diào)用把第三方查詢接口打到超時就是因為沒有給工具加流量閘門。5.4 一個常見誤區(qū)和進階方向遠程化還有一個常見誤區(qū)以為 MCP Client 只能由一個 AI 應(yīng)用來連。實際上你完全可以直接用 MCP Client SDK 把 Server 包一層做成一個內(nèi)部命令行工具、一個定時任務(wù)甚至一個異步 Worker。MCP Tool 的本質(zhì)是能力封裝不是 AI 專屬 API。這個點想通之后同一個 Server 可以復(fù)用在多個業(yè)務(wù)鏈路里工具函數(shù)變成一套可復(fù)用的中間層能力跨業(yè)務(wù)暴露價值。6. 進階設(shè)計資源、提示詞與復(fù)雜工具模式6.1 Resource 不只是數(shù)據(jù)還是上下文的引子Resource 在 MCP 里可以理解為只讀數(shù)據(jù)的描述性入口。它和 Tool 最大的區(qū)別是Tool 是一次動作Resource 是一個可被引用的數(shù)據(jù)對象。比如我在 Server 里注冊了一個order://{order_id}的 ResourceAI 在回答用戶時可以在上下文里引用關(guān)于訂單的資源然后讓工具去查更多。Resource 很適合把數(shù)據(jù)模型、元數(shù)據(jù)、配置項這些內(nèi)容暴露給模型讓模型在交互時擁有足夠的背景知識。6.2 Prompt 模塊化沉淀調(diào)用經(jīng)驗MCP 的 Prompt 能力也值得善用。你可以把客服對話時如何查詢訂單的提示模板做到 Server 里客戶端連接后自動拿到這些模板。每次接新客戶端時不用重新從零調(diào)提示詞直接在客戶端側(cè)選一個模板就能獲得不錯的效果。這對團隊合作的價值很高相當于把怎么用這套工具最順的經(jīng)驗沉淀成配置。6.3 復(fù)雜工具多輸入?yún)?shù)的組合查詢當工具的參數(shù)超過三個就要考慮設(shè)計成結(jié)構(gòu)化的組合查詢了。比如企業(yè)內(nèi)部的訂單查詢工具除了訂單號還支持客戶名稱時間范圍狀態(tài)的組合過濾。這種工具的輸入要用 JSON 對象而不是平鋪參數(shù)。我的實現(xiàn)方式from pydantic import BaseModel class OrderQueryParams(BaseModel): order_id: str | None None customer_name: str | None None date_from: str | None None date_to: str | None None status: str | None None mcp.tool() def query_orders_advanced(params: OrderQueryParams) - list[dict]: 按組合條件查詢訂單列表條件可任意組合至少需要提供一個字段。 return _query_orders(params)把它設(shè)置成 Pydantic Model 有兩個好處FastMCP 能直接把 Model 轉(zhuǎn)成結(jié)構(gòu)良好的 JSON Schema 給 LLM。字段級校驗在入口處就完成了非法值不會泄漏進下層。6.4 長耗時任務(wù)的模式選擇MCP 工具是同步調(diào)用還是異步結(jié)果回傳取決于傳輸方式。HTTP SSE 模式下可以采用立即返回一個任務(wù) ID后續(xù)通過 Resource 或事件通道查詢進度的方式stdio 模式下則建議保持同步調(diào)用設(shè)定合理的超時上限。我自己做數(shù)據(jù)重算類工具時傾向于異步任務(wù)模式——先讓工具回一個任務(wù)已提交然后單獨做一個查詢進度的工具這樣 LLM 不會因為長時間等待而誤判調(diào)用失敗。7. 上線前后一定要檢查的十項清單開發(fā)接近尾聲很多問題不是代碼邏輯錯而是部署形態(tài)沒想全。下面這十項是我自己在每次部署之前都會過的清單也分享給你們照著檢查基本能規(guī)避絕大部分上線事故Server 啟動方式是否可被進程管理工具托管sudo systemd 或容器平臺沒有守護進程的話掛了沒人拉。日志是否全量走 stderr 或獨立文件沒有污染 stdio 通道。Token 和密鑰是否通過環(huán)境變量或密鑰管理服務(wù)注入有沒有硬編碼進代碼。工具入?yún)⑹欠褡隽嘶拘ｒ炗绕溽槍?LLM 輸入的不確定性。數(shù)據(jù)庫訪問是否限定了最小權(quán)限集有沒有按用戶隔離數(shù)據(jù)范圍。是否有審計字段可以追溯某次查詢是哪個用戶、哪個客戶端觸發(fā)的。超時時間是否合理過長會積累請求積壓過短會誤殺依賴的慢請求。并發(fā)數(shù)是否有壓測數(shù)據(jù)支撐避免突發(fā)流量打滿依賴。API 網(wǎng)關(guān)或負載均衡的會話保持是否適配 SSE 連接不然長連接容易被切斷。配置文件是否有版本管理避免上線后改不回滾。其中第九條曾經(jīng)讓我費了不少時間。之前我把 MCP HTTP 服務(wù)部署到負載均衡后面結(jié)果發(fā)現(xiàn)客戶端每隔幾十秒就斷連一次排查了很久才發(fā)現(xiàn)是網(wǎng)關(guān)的默認空閑超時時間太短把 SSE 長連接給掐了。這種問題在日志里特別隱蔽因為它不是報錯只是連接被重置。如果你的網(wǎng)絡(luò)拓撲里帶有網(wǎng)關(guān)請務(wù)必檢查空閑連接超時。8. 做 Tool 和做平臺更長期的視角當你把第一個 Server 跑通之后建議退一步問自己一個問題團隊里有多少場景其實可以抽象成同一種公共能力我的經(jīng)驗是與其給每個 AI 應(yīng)用各自連一套獨立 Server不如先梳理一下內(nèi)部公共數(shù)據(jù)接口按業(yè)務(wù)域做成統(tǒng)一的 MCP Server 組。比如訂單域、商品域、庫存域、用戶域每個域一個 Server所有上層應(yīng)用按需連接。這能讓團隊沉淀出一層穩(wěn)定的AI 可調(diào)用中間層后續(xù)做新的 AI 功能成本會肉眼可見地下降。從工程角度講MCP 的標準化還帶來一個隱性收益新員工入職后學(xué)習如何提供工具能力不再需要翻舊項目的膠水代碼只需要看協(xié)議和 SDK 文檔。這對團隊長期維護的成本是很大的改善。如果你現(xiàn)在正處在要不要上車 MCP的觀望期我的建議是先拿一個低頻、只讀、不敏感的工具跑通全鏈路比如查應(yīng)用版本信息或者查配置字典。這個周期一般不會超過半天卻能完整經(jīng)歷從開發(fā)、調(diào)試到接入客戶端的全部過程比看十篇文章都有用。跑通之后再逐步擴大工具覆蓋范圍步步為營風險完全可控。