議實戰(zhàn)指南：構(gòu)建標(biāo)準(zhǔn)化AI Agent工具調(diào)用系統(tǒng))
1. 從“玩具”到“生產(chǎn)力”為什么我們需要MCP協(xié)議如果你最近在折騰AI Agent尤其是那些能調(diào)用外部工具、幫你查天氣、訂機票、寫代碼的智能體那你大概率已經(jīng)遇到了一個核心瓶頸工具連接。你可能會用LangChain的Toolkit或者直接調(diào)用某個API但很快就會發(fā)現(xiàn)當(dāng)你想讓Agent同時連接數(shù)據(jù)庫、搜索引擎、代碼執(zhí)行環(huán)境和內(nèi)部業(yè)務(wù)系統(tǒng)時事情變得一團(tuán)糟。每個工具都有不同的認(rèn)證方式、輸入輸出格式、錯誤處理邏輯你寫的膠水代碼越來越多Agent的核心邏輯反而被淹沒在繁瑣的集成細(xì)節(jié)里。這就像你想造一輛能適應(yīng)各種地形的全能車結(jié)果大部分時間都在為不同的輪胎、不同的發(fā)動機接口而頭疼。MCPModel Context Protocol協(xié)議的出現(xiàn)就是為了解決這個“接口標(biāo)準(zhǔn)化”的問題。它不是一個具體的工具或框架而是一套通信協(xié)議和規(guī)范旨在為AI模型特別是大型語言模型提供一個統(tǒng)一、標(biāo)準(zhǔn)化的方式來發(fā)現(xiàn)、描述和調(diào)用外部工具或稱為“資源”。簡單來說MCP想讓AI模型像我們使用USB接口一樣使用外部能力插上就能識別驅(qū)動自動安裝即插即用。這篇指南就是帶你從零開始親手搭建一個基于MCP協(xié)議的AI Agent讓它能穩(wěn)定、可靠地連接并使用外部工具。無論你是想做一個個人效率助手還是為企業(yè)構(gòu)建一個復(fù)雜的自動化流程理解并實踐MCP都能讓你從“拼接怪”式的開發(fā)升級到“架構(gòu)師”式的設(shè)計。2. 拆解MCP協(xié)議核心三要素與工作流全景在動手寫代碼之前我們必須先理解MCP協(xié)議到底規(guī)定了什么。它不是魔法而是一套清晰的“游戲規(guī)則”。我們可以將其核心拆解為三個角色和它們之間的交互流程。2.1 核心角色定義一個完整的MCP生態(tài)涉及三個關(guān)鍵角色客戶端Client通常是AI應(yīng)用或Agent本身。它負(fù)責(zé)發(fā)起請求是工具的“使用者”。在我們的場景中這就是我們構(gòu)建的AI Agent大腦。服務(wù)器Server工具或資源的提供者。它封裝了具體的功能實現(xiàn)比如數(shù)據(jù)庫查詢、代碼執(zhí)行、調(diào)用第三方API等。一個Server可以提供一個或多個工具。協(xié)議Protocol定義Client和Server之間通信的語言JSON-RPC over stdio/HTTP/SSE和消息格式。這是MCP協(xié)議本身。2.2 標(biāo)準(zhǔn)工作流一次完整的工具調(diào)用是如何發(fā)生的理解角色后我們來看一次標(biāo)準(zhǔn)的交互流程。這就像一次精心編排的對話初始化與握手InitializeClient啟動連接到Server。雙方交換初始化信息包括各自的能力聲明。Server會告訴Client“我這里有哪些工具可用?！惫ぞ吡斜慝@取ListToolsClient向Server請求可用的工具列表。Server返回一個數(shù)組其中每個工具都有唯一的name、清晰的description以及詳細(xì)的inputSchemaJSON Schema格式。這個description至關(guān)重要它是LLM決定是否及如何調(diào)用該工具的主要依據(jù)。工具調(diào)用CallToolLLM在Client內(nèi)部根據(jù)用戶請求和上下文決定調(diào)用哪個工具并生成符合inputSchema的參數(shù)。Client將這個調(diào)用請求發(fā)送給Server。執(zhí)行與返回ResultServer執(zhí)行實際的操作如查詢數(shù)據(jù)庫、調(diào)用API然后將結(jié)果以結(jié)構(gòu)化文本、圖片、JSON等或非結(jié)構(gòu)化的形式返回給Client。結(jié)果中還可以包含isError標(biāo)志來指示調(diào)用是否成功。資源推送可選Resources除了被動的工具調(diào)用MCP還支持Server主動向Client推送“資源”如動態(tài)更新的文檔、實時日志流。Client可以訂閱Subscribe這些資源Server會在資源變化時通知NotifyClient。這個流程的核心優(yōu)勢在于解耦。Client你的Agent不需要知道工具是用Python、Go還是Rust寫的也不需要關(guān)心它部署在本地還是云端。它只需要按照協(xié)議發(fā)送JSON-RPC消息。同樣Server開發(fā)者可以專注于實現(xiàn)業(yè)務(wù)邏輯而無需為每個AI框架做適配。注意MCP協(xié)議目前有多種傳輸方式最常用的是stdio標(biāo)準(zhǔn)輸入輸出適用于本地進(jìn)程和HTTP適用于遠(yuǎn)程服務(wù)。對于初學(xué)者和大多數(shù)集成場景從stdio開始是最簡單直接的選擇。3. 實戰(zhàn)第一步構(gòu)建你的第一個MCP服務(wù)器工具提供方理論清晰后我們開始動手。我們將使用官方推薦的TypeScript/JavaScript SDK來構(gòu)建一個Server因為它生態(tài)成熟文檔豐富。我們將創(chuàng)建一個提供“天氣查詢”和“計算器”兩個簡單工具的Server。3.1 環(huán)境準(zhǔn)備與項目初始化首先確保你的環(huán)境有Node.js建議18和npm。然后創(chuàng)建一個新項目并安裝核心依賴。# 創(chuàng)建一個新的項目目錄 mkdir my-mcp-server cd my-mcp-server # 初始化項目 npm init -y # 安裝MCP服務(wù)器SDK和類型定義 npm install modelcontextprotocol/sdk npm install --save-dev typescript types/node # 初始化TypeScript配置 npx tsc --init修改生成的tsconfig.json確保設(shè)置正確例如{ compilerOptions: { target: ES2022, module: NodeNext, moduleResolution: NodeNext, outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*], exclude: [node_modules] }3.2 實現(xiàn)核心服務(wù)器邏輯在src目錄下創(chuàng)建index.ts開始編寫Server。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListToolsRequestSchema, } from modelcontextprotocol/sdk/types.js; // 1. 創(chuàng)建Server實例 const server new Server( { name: my-first-mcp-server, version: 0.1.0, }, { capabilities: { tools: {}, // 聲明本服務(wù)器提供工具能力 }, } ); // 2. 定義工具列表 const tools [ { name: get_weather, description: 獲取指定城市的當(dāng)前天氣情況。, inputSchema: { type: object, properties: { city: { type: string, description: 城市名稱例如Beijing, Shanghai, New York, }, unit: { type: string, enum: [celsius, fahrenheit], description: 溫度單位默認(rèn)為攝氏度celsius, default: celsius, }, }, required: [city], }, }, { name: calculate, description: 執(zhí)行簡單的數(shù)學(xué)計算。, inputSchema: { type: object, properties: { expression: { type: string, description: 數(shù)學(xué)表達(dá)式例如(3 4) * 2 / 5。支持加減乘除和括號。, }, }, required: [expression], }, }, ]; // 3. 處理ListTools請求當(dāng)Client詢問有什么工具時返回這個列表 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: tools, }; }); // 4. 處理CallTool請求當(dāng)Client調(diào)用具體工具時執(zhí)行相應(yīng)邏輯 server.setRequestHandler(CallToolRequestSchema, async (request) { const { name, arguments: args } request.params; if (name get_weather) { // 模擬天氣查詢邏輯 const city (args as any).city; const unit (args as any).unit || celsius; // 在實際應(yīng)用中這里會調(diào)用真實的天氣API const temp Math.floor(Math.random() * 30) 10; // 模擬溫度 const conditions [晴朗, 多云, 小雨, 陰天]; const condition conditions[Math.floor(Math.random() * conditions.length)]; let displayTemp temp; if (unit fahrenheit) { displayTemp Math.round((temp * 9) / 5 32); } return { content: [ { type: text, text: 城市【${city}】的當(dāng)前天氣為${condition}溫度 ${displayTemp}°${unit celsius ? C : F}。, }, ], }; } else if (name calculate) { // 執(zhí)行計算 const expression (args as any).expression; try { // 警告在生產(chǎn)環(huán)境中直接使用eval是極其危險的容易導(dǎo)致代碼注入 // 這里僅用于演示。實際應(yīng)用應(yīng)使用安全的數(shù)學(xué)表達(dá)式解析庫如math.js const result eval(expression); return { content: [ { type: text, text: 計算表達(dá)式【${expression}】的結(jié)果是${result}, }, ], }; } catch (error) { return { content: [ { type: text, text: 計算表達(dá)式【${expression}】時出錯${error}, }, ], isError: true, }; } } // 如果工具名未找到 return { content: [ { type: text, text: 未知工具${name}, }, ], isError: true, }; }); // 5. 啟動服務(wù)器使用stdio傳輸 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Server (my-first-mcp-server) 已啟動并等待連接...); } main().catch((error) { console.error(服務(wù)器啟動失敗:, error); process.exit(1); });代碼解讀與避坑點工具描述description是靈魂get_weather工具的description字段寫得非常具體。LLM會閱讀這個描述來決定是否調(diào)用它。模糊的描述會導(dǎo)致LLM錯誤調(diào)用或忽略該工具。輸入模式inputSchema是契約它嚴(yán)格定義了Client必須傳入的參數(shù)格式和類型。使用JSON Schema可以確保類型安全并給LLM清晰的提示。安全警告計算器工具中使用了eval這在實際項目中是絕對禁止的因為它會執(zhí)行任意字符串代碼帶來嚴(yán)重的安全風(fēng)險。此處僅作最簡單演示。真實場景務(wù)必使用像math.js或expr-eval這樣的安全庫來解析數(shù)學(xué)表達(dá)式。錯誤處理在catch塊和未知工具返回中我們都設(shè)置了isError: true。這有助于Client和背后的LLM識別調(diào)用失敗從而可能嘗試其他策略或向用戶報錯。3.3 構(gòu)建與運行編譯并運行這個服務(wù)器。# 編譯TypeScript npx tsc # 運行服務(wù)器 node dist/index.js運行后程序會阻塞等待Client通過標(biāo)準(zhǔn)輸入輸出進(jìn)行連接。這意味著我們的Server已經(jīng)就緒。4. 實戰(zhàn)第二步構(gòu)建MCP客戶端AI Agent大腦現(xiàn)在我們有了工具提供方Server需要一個使用者Client。我們將構(gòu)建一個簡單的命令行AI Agent它使用OpenAI的GPT模型作為大腦并通過MCP協(xié)議調(diào)用我們剛寫的Server里的工具。4.1 客戶端項目初始化新建一個客戶端項目目錄。mkdir my-mcp-client cd my-mcp-client npm init -y npm install modelcontextprotocol/sdk openai dotenv npm install --save-dev typescript types/node npx tsc --init # 同樣配置好tsconfig.json創(chuàng)建.env文件存放你的OpenAI API密鑰OPENAI_API_KEYsk-your-api-key-here4.2 實現(xiàn)客戶端與工具調(diào)用邏輯在src目錄下創(chuàng)建index.ts。import { Client } from modelcontextprotocol/sdk/client/index.js; import { StdioClientTransport } from modelcontextprotocol/sdk/client/stdio.js; import OpenAI from openai; import * as path from path; import * as child_process from child_process; import * as fs from fs; import dotenv from dotenv; dotenv.config(); async function main() { // 1. 啟動MCP Server進(jìn)程 const serverPath path.resolve(__dirname, ../../my-mcp-server/dist/index.js); // 這里假設(shè)server項目在相鄰目錄請根據(jù)實際情況調(diào)整路徑 if (!fs.existsSync(serverPath)) { console.error(未找到MCP Server可執(zhí)行文件: ${serverPath}); console.error(請確保已編譯并構(gòu)建了您的MCP服務(wù)器項目。); process.exit(1); } const serverProcess child_process.spawn(node, [serverPath], { stdio: [pipe, pipe, inherit], // 將server的stderr繼承到當(dāng)前控制臺便于調(diào)試 }); // 2. 創(chuàng)建MCP Client并連接 const client new Client( { name: my-mcp-agent, version: 0.1.0, }, { capabilities: {}, } ); const transport new StdioClientTransport({ command: node, args: [serverPath], }); await client.connect(transport); console.log(MCP Client 已連接至服務(wù)器。); // 3. 獲取服務(wù)器提供的工具列表 const toolsResponse await client.listTools(); const availableTools toolsResponse.tools; console.log(從服務(wù)器獲取到 ${availableTools.length} 個工具, availableTools.map(t t.name)); // 4. 初始化OpenAI客戶端 const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY, }); // 5. 為LLM構(gòu)造工具調(diào)用格式的函數(shù)定義 const toolDefinitionsForLLM availableTools.map(tool ({ type: function as const, function: { name: tool.name, description: tool.description, parameters: tool.inputSchema, }, })); // 6. 主對話循環(huán) const readline require(readline).createInterface({ input: process.stdin, output: process.stdout }); const question (prompt: string): Promisestring { return new Promise((resolve) { readline.question(prompt, resolve); }); }; console.log(\n AI助手已就緒集成MCP工具); console.log(你可以詢問天氣或讓我計算。輸入 exit 退出。\n); const conversationHistory: ArrayOpenAI.ChatCompletionMessageParam []; while (true) { const userInput await question(\n你: ); if (userInput.toLowerCase() exit) { break; } conversationHistory.push({ role: user, content: userInput }); try { // 調(diào)用OpenAI并告知它可用的工具 const completion await openai.chat.completions.create({ model: gpt-4o-mini, // 或使用 gpt-3.5-turbo messages: [ { role: system, content: 你是一個有幫助的助手可以調(diào)用工具來獲取天氣或進(jìn)行計算。請根據(jù)用戶需求決定是否調(diào)用工具。如果調(diào)用請嚴(yán)格遵循工具的參數(shù)格式要求。 }, ...conversationHistory, ], tools: toolDefinitionsForLLM, tool_choice: auto, // 讓模型自行決定是否調(diào)用工具 }); const responseMessage completion.choices[0].message; conversationHistory.push(responseMessage); // 檢查LLM是否想要調(diào)用工具 const toolCalls responseMessage.tool_calls; let finalResponseText responseMessage.content || ; if (toolCalls toolCalls.length 0) { console.log(助手決定調(diào)用工具: ${toolCalls.map(tc tc.function.name).join(, )}); for (const toolCall of toolCalls) { const toolName toolCall.function.name; const toolArgs JSON.parse(toolCall.function.arguments); // 通過MCP Client實際調(diào)用工具 const toolResult await client.callTool({ name: toolName, arguments: toolArgs, }); const resultContent toolResult.content?.[0]?.text || 工具未返回文本結(jié)果; const isError toolResult.isError; // 將工具調(diào)用結(jié)果作為新的消息追加到歷史讓LLM進(jìn)行總結(jié)或下一步?jīng)Q策 conversationHistory.push({ role: tool, tool_call_id: toolCall.id, content: isError ? 工具調(diào)用出錯: ${resultContent} : resultContent, }); // 如果是錯誤可能直接輸出錯誤信息 if (isError) { finalResponseText 調(diào)用工具【${toolName}】時出錯${resultContent}; } else { // 如果不錯誤我們可能需要LLM根據(jù)工具結(jié)果生成最終回復(fù) // 這里簡化處理直接展示結(jié)果 finalResponseText 工具【${toolName}】返回結(jié)果${resultContent}; } } // 可選如果希望LLM基于工具結(jié)果生成更自然的回復(fù)可以在這里再進(jìn)行一次API調(diào)用 // 但為了簡化演示我們直接輸出工具結(jié)果 } console.log(助手: ${finalResponseText}); } catch (error) { console.error(處理請求時發(fā)生錯誤:, error); } } readline.close(); await client.close(); serverProcess.kill(); console.log(會話結(jié)束。); } main().catch(console.error);關(guān)鍵實現(xiàn)解析進(jìn)程管理客戶端通過child_process.spawn啟動并管理Server進(jìn)程通過stdio管道進(jìn)行通信。這是一種常見的本地集成模式。動態(tài)工具發(fā)現(xiàn)客戶端在啟動后首先調(diào)用client.listTools()從Server獲取最新的工具列表和它們的schema。這意味著你更新Server工具后Client無需修改代碼即可感知。OpenAI Function Calling 適配我們將MCP工具的描述完美轉(zhuǎn)換成了OpenAI Function Calling所需的格式。這是連接MCP協(xié)議與主流LLM的關(guān)鍵橋梁。對話管理我們維護(hù)了一個conversationHistory數(shù)組包含了用戶消息、LLM回復(fù)以及工具調(diào)用結(jié)果。將工具結(jié)果以role: tool的消息格式放回歷史是讓LLM理解上下文并生成最終回答的標(biāo)準(zhǔn)做法。4.3 運行你的AI Agent確保你的MCP Server項目已經(jīng)編譯dist/index.js存在并且Client項目中的路徑配置正確。然后在Client目錄下運行npx tsc node dist/index.js現(xiàn)在你可以嘗試對話你: 上海天氣怎么樣 助手決定調(diào)用工具: get_weather 助手: 工具【get_weather】返回結(jié)果城市【上?！康漠?dāng)前天氣為多云溫度 22°C。 你: 幫我算一下(1527)*3等于多少 助手決定調(diào)用工具: calculate 助手: 工具【calculate】返回結(jié)果計算表達(dá)式【(1527)*3】的結(jié)果是126恭喜你已經(jīng)成功構(gòu)建了一個基于MCP協(xié)議、能動態(tài)發(fā)現(xiàn)并調(diào)用外部工具的AI Agent原型。5. 進(jìn)階生產(chǎn)環(huán)境部署與架構(gòu)考量上面的例子是一個本地一體化的演示。但在生產(chǎn)環(huán)境中Client、Server和LLM服務(wù)往往是分離部署的。下面我們來探討更實際的架構(gòu)。5.1 服務(wù)器部署模式HTTP Transport對于遠(yuǎn)程工具服務(wù)我們需要使用HTTP傳輸模式。這需要修改我們的Server。首先安裝HTTP傳輸層依賴cd my-mcp-server npm install modelcontextprotocol/sdk/server/http.js然后修改或新建一個HTTP服務(wù)器文件如src/server-http.tsimport { Server } from modelcontextprotocol/sdk/server/index.js; import { HTTPServerTransport } from modelcontextprotocol/sdk/server/http.js; import express from express; // ... 工具定義和請求處理邏輯與之前相同 ... async function main() { const app express(); app.use(express.json()); const server new Server(...); // 初始化Server同上 // 設(shè)置請求處理器 server.setRequestHandler(ListToolsRequestSchema, ...); server.setRequestHandler(CallToolRequestSchema, ...); // 創(chuàng)建HTTP Transport并綁定到Express路由 const transport new HTTPServerTransport(app, /mcp); await server.connect(transport); const port process.env.PORT || 3000; app.listen(port, () { console.log(MCP HTTP Server 運行在 http://localhost:${port}/mcp); }); } main();這樣你的工具服務(wù)器就暴露了一個HTTP端點例如http://your-server:3000/mcp。任何兼容MCP協(xié)議的Client都可以通過HTTP連接到它。5.2 客戶端連接遠(yuǎn)程服務(wù)器相應(yīng)地客戶端也需要改為使用HTTP連接。// 在客戶端項目中 import { Client } from modelcontextprotocol/sdk/client/index.js; import { HTTPClientTransport } from modelcontextprotocol/sdk/client/http.js; async function connectToRemoteServer() { const client new Client(...); const transport new HTTPClientTransport(new URL(http://your-server:3000/mcp)); await client.connect(transport); // ... 后續(xù)工具調(diào)用邏輯不變 }5.3 多服務(wù)器管理與工具編排一個強大的Agent往往需要連接多個工具服務(wù)器。MCP Client可以同時連接多個Server。你需要管理多個Client實例并在向LLM提供工具定義時合并來自所有服務(wù)器的工具列表同時注意處理工具名沖突建議在Server層面確保工具名全局唯一或添加命名空間前綴。更復(fù)雜的場景下你可能需要一個工具路由層或編排引擎。這個層負(fù)責(zé)負(fù)載均衡當(dāng)多個Server提供相同功能的工具時如不同的天氣API根據(jù)成本、延遲、可用性進(jìn)行選擇。權(quán)限與鑒權(quán)管理不同工具對不同用戶或請求的訪問權(quán)限。組合工具將多個工具調(diào)用串聯(lián)起來完成復(fù)雜任務(wù)如“查天氣然后根據(jù)天氣推薦穿衣”。Fallback策略當(dāng)主工具調(diào)用失敗時自動嘗試備用工具。這超出了基礎(chǔ)MCP協(xié)議的范圍通常需要在你的AI應(yīng)用框架如LangChain, LlamaIndex或自定義的Agent邏輯中實現(xiàn)。5.4 安全性、錯誤處理與監(jiān)控在生產(chǎn)環(huán)境中以下幾點至關(guān)重要輸入驗證與凈化Server端必須對Client傳入的arguments進(jìn)行嚴(yán)格的驗證防止注入攻擊。即使有JSON Schema也要在業(yè)務(wù)邏輯層再次檢查。認(rèn)證與授權(quán)HTTP模式下必須實施API密鑰、OAuth等認(rèn)證機制。MCP協(xié)議本身不規(guī)定認(rèn)證方式這需要在傳輸層如HTTPS 頭部令牌或應(yīng)用層實現(xiàn)。限流與配額為工具調(diào)用設(shè)置速率限制和調(diào)用配額防止濫用。全面的錯誤處理Client端需要處理網(wǎng)絡(luò)超時、Server無響應(yīng)、返回格式錯誤等各種異常給出友好的用戶提示或重試策略。日志與監(jiān)控記錄所有工具調(diào)用的請求、響應(yīng)、耗時和錯誤。這對于調(diào)試、優(yōu)化和成本核算必不可少?？紤]使用結(jié)構(gòu)化日志如JSON格式并輸出到集中式日志系統(tǒng)。成本控制特別是調(diào)用付費API的工具如發(fā)送短信、生成圖像需要在Server或路由層實施預(yù)算控制。6. 生態(tài)與工具鏈加速開發(fā)的利器手動編寫Server和Client雖然有助于理解原理但對于快速開發(fā)利用現(xiàn)有生態(tài)工具效率更高。官方與社區(qū)Server已經(jīng)有很多現(xiàn)成的MCP Server實現(xiàn)可以直接使用或作為參考。文件系統(tǒng)提供讀寫本地文件的能力。Git提供Git倉庫的查詢和操作。SQL數(shù)據(jù)庫連接并查詢MySQL、PostgreSQL等。搜索引擎連接Brave Search、Google Programmable Search等。你可以在MCP協(xié)議的GitHub倉庫或社區(qū)中找到更多。Server開發(fā)框架除了TypeScript SDK也有Python、Rust等語言的SDK方便你用熟悉的語言開發(fā)工具。Client集成框架Claude Desktop / Anthropic APIAnthropic官方大力推廣MCP其Claude桌面應(yīng)用直接支持通過MCP協(xié)議加載本地工具。Cursor IDE一些先進(jìn)的AI編程IDE也開始內(nèi)置MCP Client允許AI助手直接調(diào)用你配置的工具。LangChain / LlamaIndex這些流行的AI應(yīng)用框架正在逐步增加對MCP的原生支持你可以用幾行代碼就將MCP工具接入到現(xiàn)有的Chain或Agent中。調(diào)試與測試工具像mcp-cli這樣的命令行工具可以讓你手動測試MCP Server發(fā)送ListTools和CallTool請求而無需編寫完整的Client極大方便了Server的開發(fā)和調(diào)試。擁抱這些工具鏈能讓你從協(xié)議細(xì)節(jié)中解放出來更專注于設(shè)計和實現(xiàn)有價值的工具本身。7. 踩坑實錄從開發(fā)到部署的常見問題在實際項目中我遇到了不少坑這里分享幾個典型的問題一工具描述description寫得太差導(dǎo)致LLM從不調(diào)用或錯誤調(diào)用?，F(xiàn)象你寫了一個完美的數(shù)據(jù)庫查詢工具但LLM總是忽略它或者用錯誤的參數(shù)調(diào)用。根因LLM完全依賴description和inputSchema來理解工具。模糊的描述如“查詢數(shù)據(jù)”毫無用處。解決方案描述要具體、包含關(guān)鍵詞、說明使用場景和限制。例如“根據(jù)用戶ID查詢其在訂單表中的最近10條訂單記錄返回訂單號、日期、金額和狀態(tài)。用戶ID必須是數(shù)字?！蓖瑫rinputSchema中的參數(shù)描述也要詳盡。問題二Server進(jìn)程僵尸或資源泄漏?，F(xiàn)象Client異常退出后Server進(jìn)程沒有正確關(guān)閉占用系統(tǒng)資源。根因Client端沒有正確處理斷開連接和清理進(jìn)程的邏輯。解決方案在Client代碼中監(jiān)聽SIGINT、SIGTERM等退出信號確保在退出前調(diào)用client.close()并killServer進(jìn)程。使用child_process時考慮使用p-kill等庫來確保進(jìn)程樹被徹底清理。問題三工具調(diào)用超時或阻塞主線程?，F(xiàn)象某個工具如一個慢速網(wǎng)絡(luò)請求執(zhí)行時間很長導(dǎo)致整個Agent響應(yīng)卡住。根因Server同步執(zhí)行耗時操作阻塞了請求處理循環(huán)。解決方案Server端所有工具處理函數(shù)都必須是async的。對于可能耗時的操作要設(shè)置合理的超時例如使用Promise.race或AbortController并及時向Client返回超時錯誤避免無限期等待。問題四多工具并發(fā)調(diào)用時的狀態(tài)沖突。現(xiàn)象Agent同時調(diào)用“寫入文件”和“讀取文件”工具導(dǎo)致讀取到不完整的數(shù)據(jù)。根因工具Server是無狀態(tài)的但工具操作的外部資源如文件、數(shù)據(jù)庫存在狀態(tài)競爭。解決方案這需要在業(yè)務(wù)邏輯層面解決。可以為相關(guān)工具組設(shè)計鎖機制如使用文件鎖、數(shù)據(jù)庫事務(wù)或者在工具描述中明確說明其非冪等性和潛在沖突讓LLM或上層的編排邏輯進(jìn)行順序調(diào)度。構(gòu)建基于MCP的AI Agent協(xié)議本身只是解決了“連接”的問題。真正的挑戰(zhàn)在于如何設(shè)計好用、安全、可靠的工具以及如何讓LLM智能、高效地使用這些工具。這需要你同時具備后端開發(fā)、API設(shè)計以及對LLM能力邊界和思維模式的深刻理解。從這個小原型出發(fā)不斷迭代你的工具集和Agent邏輯你就能打造出真正強大的AI應(yīng)用。 MCP協(xié)議實戰(zhàn)指南：構(gòu)建標(biāo)準(zhǔn)化AI Agent工具調(diào)用系統(tǒng)
1. 從“玩具”到“生產(chǎn)力”為什么我們需要MCP協(xié)議如果你最近在折騰AI Agent尤其是那些能調(diào)用外部工具、幫你查天氣、訂機票、寫代碼的智能體那你大概率已經(jīng)遇到了一個核心瓶頸工具連接。你可能會用LangChain的Toolkit或者直接調(diào)用某個API但很快就會發(fā)現(xiàn)當(dāng)你想讓Agent同時連接數(shù)據(jù)庫、搜索引擎、代碼執(zhí)行環(huán)境和內(nèi)部業(yè)務(wù)系統(tǒng)時事情變得一團(tuán)糟。每個工具都有不同的認(rèn)證方式、輸入輸出格式、錯誤處理邏輯你寫的膠水代碼越來越多Agent的核心邏輯反而被淹沒在繁瑣的集成細(xì)節(jié)里。這就像你想造一輛能適應(yīng)各種地形的全能車結(jié)果大部分時間都在為不同的輪胎、不同的發(fā)動機接口而頭疼。MCPModel Context Protocol協(xié)議的出現(xiàn)就是為了解決這個“接口標(biāo)準(zhǔn)化”的問題。它不是一個具體的工具或框架而是一套通信協(xié)議和規(guī)范旨在為AI模型特別是大型語言模型提供一個統(tǒng)一、標(biāo)準(zhǔn)化的方式來發(fā)現(xiàn)、描述和調(diào)用外部工具或稱為“資源”。簡單來說MCP想讓AI模型像我們使用USB接口一樣使用外部能力插上就能識別驅(qū)動自動安裝即插即用。這篇指南就是帶你從零開始親手搭建一個基于MCP協(xié)議的AI Agent讓它能穩(wěn)定、可靠地連接并使用外部工具。無論你是想做一個個人效率助手還是為企業(yè)構(gòu)建一個復(fù)雜的自動化流程理解并實踐MCP都能讓你從“拼接怪”式的開發(fā)升級到“架構(gòu)師”式的設(shè)計。2. 拆解MCP協(xié)議核心三要素與工作流全景在動手寫代碼之前我們必須先理解MCP協(xié)議到底規(guī)定了什么。它不是魔法而是一套清晰的“游戲規(guī)則”。我們可以將其核心拆解為三個角色和它們之間的交互流程。2.1 核心角色定義一個完整的MCP生態(tài)涉及三個關(guān)鍵角色客戶端Client通常是AI應(yīng)用或Agent本身。它負(fù)責(zé)發(fā)起請求是工具的“使用者”。在我們的場景中這就是我們構(gòu)建的AI Agent大腦。服務(wù)器Server工具或資源的提供者。它封裝了具體的功能實現(xiàn)比如數(shù)據(jù)庫查詢、代碼執(zhí)行、調(diào)用第三方API等。一個Server可以提供一個或多個工具。協(xié)議Protocol定義Client和Server之間通信的語言JSON-RPC over stdio/HTTP/SSE和消息格式。這是MCP協(xié)議本身。2.2 標(biāo)準(zhǔn)工作流一次完整的工具調(diào)用是如何發(fā)生的理解角色后我們來看一次標(biāo)準(zhǔn)的交互流程。這就像一次精心編排的對話初始化與握手InitializeClient啟動連接到Server。雙方交換初始化信息包括各自的能力聲明。Server會告訴Client“我這里有哪些工具可用?！惫ぞ吡斜慝@取ListToolsClient向Server請求可用的工具列表。Server返回一個數(shù)組其中每個工具都有唯一的name、清晰的description以及詳細(xì)的inputSchemaJSON Schema格式。這個description至關(guān)重要它是LLM決定是否及如何調(diào)用該工具的主要依據(jù)。工具調(diào)用CallToolLLM在Client內(nèi)部根據(jù)用戶請求和上下文決定調(diào)用哪個工具并生成符合inputSchema的參數(shù)。Client將這個調(diào)用請求發(fā)送給Server。執(zhí)行與返回ResultServer執(zhí)行實際的操作如查詢數(shù)據(jù)庫、調(diào)用API然后將結(jié)果以結(jié)構(gòu)化文本、圖片、JSON等或非結(jié)構(gòu)化的形式返回給Client。結(jié)果中還可以包含isError標(biāo)志來指示調(diào)用是否成功。資源推送可選Resources除了被動的工具調(diào)用MCP還支持Server主動向Client推送“資源”如動態(tài)更新的文檔、實時日志流。Client可以訂閱Subscribe這些資源Server會在資源變化時通知NotifyClient。這個流程的核心優(yōu)勢在于解耦。Client你的Agent不需要知道工具是用Python、Go還是Rust寫的也不需要關(guān)心它部署在本地還是云端。它只需要按照協(xié)議發(fā)送JSON-RPC消息。同樣Server開發(fā)者可以專注于實現(xiàn)業(yè)務(wù)邏輯而無需為每個AI框架做適配。注意MCP協(xié)議目前有多種傳輸方式最常用的是stdio標(biāo)準(zhǔn)輸入輸出適用于本地進(jìn)程和HTTP適用于遠(yuǎn)程服務(wù)。對于初學(xué)者和大多數(shù)集成場景從stdio開始是最簡單直接的選擇。3. 實戰(zhàn)第一步構(gòu)建你的第一個MCP服務(wù)器工具提供方理論清晰后我們開始動手。我們將使用官方推薦的TypeScript/JavaScript SDK來構(gòu)建一個Server因為它生態(tài)成熟文檔豐富。我們將創(chuàng)建一個提供“天氣查詢”和“計算器”兩個簡單工具的Server。3.1 環(huán)境準(zhǔn)備與項目初始化首先確保你的環(huán)境有Node.js建議18和npm。然后創(chuàng)建一個新項目并安裝核心依賴。# 創(chuàng)建一個新的項目目錄 mkdir my-mcp-server cd my-mcp-server # 初始化項目 npm init -y # 安裝MCP服務(wù)器SDK和類型定義 npm install modelcontextprotocol/sdk npm install --save-dev typescript types/node # 初始化TypeScript配置 npx tsc --init修改生成的tsconfig.json確保設(shè)置正確例如{ compilerOptions: { target: ES2022, module: NodeNext, moduleResolution: NodeNext, outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*], exclude: [node_modules] }3.2 實現(xiàn)核心服務(wù)器邏輯在src目錄下創(chuàng)建index.ts開始編寫Server。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListToolsRequestSchema, } from modelcontextprotocol/sdk/types.js; // 1. 創(chuàng)建Server實例 const server new Server( { name: my-first-mcp-server, version: 0.1.0, }, { capabilities: { tools: {}, // 聲明本服務(wù)器提供工具能力 }, } ); // 2. 定義工具列表 const tools [ { name: get_weather, description: 獲取指定城市的當(dāng)前天氣情況。, inputSchema: { type: object, properties: { city: { type: string, description: 城市名稱例如Beijing, Shanghai, New York, }, unit: { type: string, enum: [celsius, fahrenheit], description: 溫度單位默認(rèn)為攝氏度celsius, default: celsius, }, }, required: [city], }, }, { name: calculate, description: 執(zhí)行簡單的數(shù)學(xué)計算。, inputSchema: { type: object, properties: { expression: { type: string, description: 數(shù)學(xué)表達(dá)式例如(3 4) * 2 / 5。支持加減乘除和括號。, }, }, required: [expression], }, }, ]; // 3. 處理ListTools請求當(dāng)Client詢問有什么工具時返回這個列表 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: tools, }; }); // 4. 處理CallTool請求當(dāng)Client調(diào)用具體工具時執(zhí)行相應(yīng)邏輯 server.setRequestHandler(CallToolRequestSchema, async (request) { const { name, arguments: args } request.params; if (name get_weather) { // 模擬天氣查詢邏輯 const city (args as any).city; const unit (args as any).unit || celsius; // 在實際應(yīng)用中這里會調(diào)用真實的天氣API const temp Math.floor(Math.random() * 30) 10; // 模擬溫度 const conditions [晴朗, 多云, 小雨, 陰天]; const condition conditions[Math.floor(Math.random() * conditions.length)]; let displayTemp temp; if (unit fahrenheit) { displayTemp Math.round((temp * 9) / 5 32); } return { content: [ { type: text, text: 城市【${city}】的當(dāng)前天氣為${condition}溫度 ${displayTemp}°${unit celsius ? C : F}。, }, ], }; } else if (name calculate) { // 執(zhí)行計算 const expression (args as any).expression; try { // 警告在生產(chǎn)環(huán)境中直接使用eval是極其危險的容易導(dǎo)致代碼注入 // 這里僅用于演示。實際應(yīng)用應(yīng)使用安全的數(shù)學(xué)表達(dá)式解析庫如math.js const result eval(expression); return { content: [ { type: text, text: 計算表達(dá)式【${expression}】的結(jié)果是${result}, }, ], }; } catch (error) { return { content: [ { type: text, text: 計算表達(dá)式【${expression}】時出錯${error}, }, ], isError: true, }; } } // 如果工具名未找到 return { content: [ { type: text, text: 未知工具${name}, }, ], isError: true, }; }); // 5. 啟動服務(wù)器使用stdio傳輸 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Server (my-first-mcp-server) 已啟動并等待連接...); } main().catch((error) { console.error(服務(wù)器啟動失敗:, error); process.exit(1); });代碼解讀與避坑點工具描述description是靈魂get_weather工具的description字段寫得非常具體。LLM會閱讀這個描述來決定是否調(diào)用它。模糊的描述會導(dǎo)致LLM錯誤調(diào)用或忽略該工具。輸入模式inputSchema是契約它嚴(yán)格定義了Client必須傳入的參數(shù)格式和類型。使用JSON Schema可以確保類型安全并給LLM清晰的提示。安全警告計算器工具中使用了eval這在實際項目中是絕對禁止的因為它會執(zhí)行任意字符串代碼帶來嚴(yán)重的安全風(fēng)險。此處僅作最簡單演示。真實場景務(wù)必使用像math.js或expr-eval這樣的安全庫來解析數(shù)學(xué)表達(dá)式。錯誤處理在catch塊和未知工具返回中我們都設(shè)置了isError: true。這有助于Client和背后的LLM識別調(diào)用失敗從而可能嘗試其他策略或向用戶報錯。3.3 構(gòu)建與運行編譯并運行這個服務(wù)器。# 編譯TypeScript npx tsc # 運行服務(wù)器 node dist/index.js運行后程序會阻塞等待Client通過標(biāo)準(zhǔn)輸入輸出進(jìn)行連接。這意味著我們的Server已經(jīng)就緒。4. 實戰(zhàn)第二步構(gòu)建MCP客戶端AI Agent大腦現(xiàn)在我們有了工具提供方Server需要一個使用者Client。我們將構(gòu)建一個簡單的命令行AI Agent它使用OpenAI的GPT模型作為大腦并通過MCP協(xié)議調(diào)用我們剛寫的Server里的工具。4.1 客戶端項目初始化新建一個客戶端項目目錄。mkdir my-mcp-client cd my-mcp-client npm init -y npm install modelcontextprotocol/sdk openai dotenv npm install --save-dev typescript types/node npx tsc --init # 同樣配置好tsconfig.json創(chuàng)建.env文件存放你的OpenAI API密鑰OPENAI_API_KEYsk-your-api-key-here4.2 實現(xiàn)客戶端與工具調(diào)用邏輯在src目錄下創(chuàng)建index.ts。import { Client } from modelcontextprotocol/sdk/client/index.js; import { StdioClientTransport } from modelcontextprotocol/sdk/client/stdio.js; import OpenAI from openai; import * as path from path; import * as child_process from child_process; import * as fs from fs; import dotenv from dotenv; dotenv.config(); async function main() { // 1. 啟動MCP Server進(jìn)程 const serverPath path.resolve(__dirname, ../../my-mcp-server/dist/index.js); // 這里假設(shè)server項目在相鄰目錄請根據(jù)實際情況調(diào)整路徑 if (!fs.existsSync(serverPath)) { console.error(未找到MCP Server可執(zhí)行文件: ${serverPath}); console.error(請確保已編譯并構(gòu)建了您的MCP服務(wù)器項目。); process.exit(1); } const serverProcess child_process.spawn(node, [serverPath], { stdio: [pipe, pipe, inherit], // 將server的stderr繼承到當(dāng)前控制臺便于調(diào)試 }); // 2. 創(chuàng)建MCP Client并連接 const client new Client( { name: my-mcp-agent, version: 0.1.0, }, { capabilities: {}, } ); const transport new StdioClientTransport({ command: node, args: [serverPath], }); await client.connect(transport); console.log(MCP Client 已連接至服務(wù)器。); // 3. 獲取服務(wù)器提供的工具列表 const toolsResponse await client.listTools(); const availableTools toolsResponse.tools; console.log(從服務(wù)器獲取到 ${availableTools.length} 個工具, availableTools.map(t t.name)); // 4. 初始化OpenAI客戶端 const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY, }); // 5. 為LLM構(gòu)造工具調(diào)用格式的函數(shù)定義 const toolDefinitionsForLLM availableTools.map(tool ({ type: function as const, function: { name: tool.name, description: tool.description, parameters: tool.inputSchema, }, })); // 6. 主對話循環(huán) const readline require(readline).createInterface({ input: process.stdin, output: process.stdout }); const question (prompt: string): Promisestring { return new Promise((resolve) { readline.question(prompt, resolve); }); }; console.log(\n AI助手已就緒集成MCP工具); console.log(你可以詢問天氣或讓我計算。輸入 exit 退出。\n); const conversationHistory: ArrayOpenAI.ChatCompletionMessageParam []; while (true) { const userInput await question(\n你: ); if (userInput.toLowerCase() exit) { break; } conversationHistory.push({ role: user, content: userInput }); try { // 調(diào)用OpenAI并告知它可用的工具 const completion await openai.chat.completions.create({ model: gpt-4o-mini, // 或使用 gpt-3.5-turbo messages: [ { role: system, content: 你是一個有幫助的助手可以調(diào)用工具來獲取天氣或進(jìn)行計算。請根據(jù)用戶需求決定是否調(diào)用工具。如果調(diào)用請嚴(yán)格遵循工具的參數(shù)格式要求。 }, ...conversationHistory, ], tools: toolDefinitionsForLLM, tool_choice: auto, // 讓模型自行決定是否調(diào)用工具 }); const responseMessage completion.choices[0].message; conversationHistory.push(responseMessage); // 檢查LLM是否想要調(diào)用工具 const toolCalls responseMessage.tool_calls; let finalResponseText responseMessage.content || ; if (toolCalls toolCalls.length 0) { console.log(助手決定調(diào)用工具: ${toolCalls.map(tc tc.function.name).join(, )}); for (const toolCall of toolCalls) { const toolName toolCall.function.name; const toolArgs JSON.parse(toolCall.function.arguments); // 通過MCP Client實際調(diào)用工具 const toolResult await client.callTool({ name: toolName, arguments: toolArgs, }); const resultContent toolResult.content?.[0]?.text || 工具未返回文本結(jié)果; const isError toolResult.isError; // 將工具調(diào)用結(jié)果作為新的消息追加到歷史讓LLM進(jìn)行總結(jié)或下一步?jīng)Q策 conversationHistory.push({ role: tool, tool_call_id: toolCall.id, content: isError ? 工具調(diào)用出錯: ${resultContent} : resultContent, }); // 如果是錯誤可能直接輸出錯誤信息 if (isError) { finalResponseText 調(diào)用工具【${toolName}】時出錯${resultContent}; } else { // 如果不錯誤我們可能需要LLM根據(jù)工具結(jié)果生成最終回復(fù) // 這里簡化處理直接展示結(jié)果 finalResponseText 工具【${toolName}】返回結(jié)果${resultContent}; } } // 可選如果希望LLM基于工具結(jié)果生成更自然的回復(fù)可以在這里再進(jìn)行一次API調(diào)用 // 但為了簡化演示我們直接輸出工具結(jié)果 } console.log(助手: ${finalResponseText}); } catch (error) { console.error(處理請求時發(fā)生錯誤:, error); } } readline.close(); await client.close(); serverProcess.kill(); console.log(會話結(jié)束。); } main().catch(console.error);關(guān)鍵實現(xiàn)解析進(jìn)程管理客戶端通過child_process.spawn啟動并管理Server進(jìn)程通過stdio管道進(jìn)行通信。這是一種常見的本地集成模式。動態(tài)工具發(fā)現(xiàn)客戶端在啟動后首先調(diào)用client.listTools()從Server獲取最新的工具列表和它們的schema。這意味著你更新Server工具后Client無需修改代碼即可感知。OpenAI Function Calling 適配我們將MCP工具的描述完美轉(zhuǎn)換成了OpenAI Function Calling所需的格式。這是連接MCP協(xié)議與主流LLM的關(guān)鍵橋梁。對話管理我們維護(hù)了一個conversationHistory數(shù)組包含了用戶消息、LLM回復(fù)以及工具調(diào)用結(jié)果。將工具結(jié)果以role: tool的消息格式放回歷史是讓LLM理解上下文并生成最終回答的標(biāo)準(zhǔn)做法。4.3 運行你的AI Agent確保你的MCP Server項目已經(jīng)編譯dist/index.js存在并且Client項目中的路徑配置正確。然后在Client目錄下運行npx tsc node dist/index.js現(xiàn)在你可以嘗試對話你: 上海天氣怎么樣 助手決定調(diào)用工具: get_weather 助手: 工具【get_weather】返回結(jié)果城市【上?！康漠?dāng)前天氣為多云溫度 22°C。 你: 幫我算一下(1527)*3等于多少 助手決定調(diào)用工具: calculate 助手: 工具【calculate】返回結(jié)果計算表達(dá)式【(1527)*3】的結(jié)果是126恭喜你已經(jīng)成功構(gòu)建了一個基于MCP協(xié)議、能動態(tài)發(fā)現(xiàn)并調(diào)用外部工具的AI Agent原型。5. 進(jìn)階生產(chǎn)環(huán)境部署與架構(gòu)考量上面的例子是一個本地一體化的演示。但在生產(chǎn)環(huán)境中Client、Server和LLM服務(wù)往往是分離部署的。下面我們來探討更實際的架構(gòu)。5.1 服務(wù)器部署模式HTTP Transport對于遠(yuǎn)程工具服務(wù)我們需要使用HTTP傳輸模式。這需要修改我們的Server。首先安裝HTTP傳輸層依賴cd my-mcp-server npm install modelcontextprotocol/sdk/server/http.js然后修改或新建一個HTTP服務(wù)器文件如src/server-http.tsimport { Server } from modelcontextprotocol/sdk/server/index.js; import { HTTPServerTransport } from modelcontextprotocol/sdk/server/http.js; import express from express; // ... 工具定義和請求處理邏輯與之前相同 ... async function main() { const app express(); app.use(express.json()); const server new Server(...); // 初始化Server同上 // 設(shè)置請求處理器 server.setRequestHandler(ListToolsRequestSchema, ...); server.setRequestHandler(CallToolRequestSchema, ...); // 創(chuàng)建HTTP Transport并綁定到Express路由 const transport new HTTPServerTransport(app, /mcp); await server.connect(transport); const port process.env.PORT || 3000; app.listen(port, () { console.log(MCP HTTP Server 運行在 http://localhost:${port}/mcp); }); } main();這樣你的工具服務(wù)器就暴露了一個HTTP端點例如http://your-server:3000/mcp。任何兼容MCP協(xié)議的Client都可以通過HTTP連接到它。5.2 客戶端連接遠(yuǎn)程服務(wù)器相應(yīng)地客戶端也需要改為使用HTTP連接。// 在客戶端項目中 import { Client } from modelcontextprotocol/sdk/client/index.js; import { HTTPClientTransport } from modelcontextprotocol/sdk/client/http.js; async function connectToRemoteServer() { const client new Client(...); const transport new HTTPClientTransport(new URL(http://your-server:3000/mcp)); await client.connect(transport); // ... 后續(xù)工具調(diào)用邏輯不變 }5.3 多服務(wù)器管理與工具編排一個強大的Agent往往需要連接多個工具服務(wù)器。MCP Client可以同時連接多個Server。你需要管理多個Client實例并在向LLM提供工具定義時合并來自所有服務(wù)器的工具列表同時注意處理工具名沖突建議在Server層面確保工具名全局唯一或添加命名空間前綴。更復(fù)雜的場景下你可能需要一個工具路由層或編排引擎。這個層負(fù)責(zé)負(fù)載均衡當(dāng)多個Server提供相同功能的工具時如不同的天氣API根據(jù)成本、延遲、可用性進(jìn)行選擇。權(quán)限與鑒權(quán)管理不同工具對不同用戶或請求的訪問權(quán)限。組合工具將多個工具調(diào)用串聯(lián)起來完成復(fù)雜任務(wù)如“查天氣然后根據(jù)天氣推薦穿衣”。Fallback策略當(dāng)主工具調(diào)用失敗時自動嘗試備用工具。這超出了基礎(chǔ)MCP協(xié)議的范圍通常需要在你的AI應(yīng)用框架如LangChain, LlamaIndex或自定義的Agent邏輯中實現(xiàn)。5.4 安全性、錯誤處理與監(jiān)控在生產(chǎn)環(huán)境中以下幾點至關(guān)重要輸入驗證與凈化Server端必須對Client傳入的arguments進(jìn)行嚴(yán)格的驗證防止注入攻擊。即使有JSON Schema也要在業(yè)務(wù)邏輯層再次檢查。認(rèn)證與授權(quán)HTTP模式下必須實施API密鑰、OAuth等認(rèn)證機制。MCP協(xié)議本身不規(guī)定認(rèn)證方式這需要在傳輸層如HTTPS 頭部令牌或應(yīng)用層實現(xiàn)。限流與配額為工具調(diào)用設(shè)置速率限制和調(diào)用配額防止濫用。全面的錯誤處理Client端需要處理網(wǎng)絡(luò)超時、Server無響應(yīng)、返回格式錯誤等各種異常給出友好的用戶提示或重試策略。日志與監(jiān)控記錄所有工具調(diào)用的請求、響應(yīng)、耗時和錯誤。這對于調(diào)試、優(yōu)化和成本核算必不可少?？紤]使用結(jié)構(gòu)化日志如JSON格式并輸出到集中式日志系統(tǒng)。成本控制特別是調(diào)用付費API的工具如發(fā)送短信、生成圖像需要在Server或路由層實施預(yù)算控制。6. 生態(tài)與工具鏈加速開發(fā)的利器手動編寫Server和Client雖然有助于理解原理但對于快速開發(fā)利用現(xiàn)有生態(tài)工具效率更高。官方與社區(qū)Server已經(jīng)有很多現(xiàn)成的MCP Server實現(xiàn)可以直接使用或作為參考。文件系統(tǒng)提供讀寫本地文件的能力。Git提供Git倉庫的查詢和操作。SQL數(shù)據(jù)庫連接并查詢MySQL、PostgreSQL等。搜索引擎連接Brave Search、Google Programmable Search等。你可以在MCP協(xié)議的GitHub倉庫或社區(qū)中找到更多。Server開發(fā)框架除了TypeScript SDK也有Python、Rust等語言的SDK方便你用熟悉的語言開發(fā)工具。Client集成框架Claude Desktop / Anthropic APIAnthropic官方大力推廣MCP其Claude桌面應(yīng)用直接支持通過MCP協(xié)議加載本地工具。Cursor IDE一些先進(jìn)的AI編程IDE也開始內(nèi)置MCP Client允許AI助手直接調(diào)用你配置的工具。LangChain / LlamaIndex這些流行的AI應(yīng)用框架正在逐步增加對MCP的原生支持你可以用幾行代碼就將MCP工具接入到現(xiàn)有的Chain或Agent中。調(diào)試與測試工具像mcp-cli這樣的命令行工具可以讓你手動測試MCP Server發(fā)送ListTools和CallTool請求而無需編寫完整的Client極大方便了Server的開發(fā)和調(diào)試。擁抱這些工具鏈能讓你從協(xié)議細(xì)節(jié)中解放出來更專注于設(shè)計和實現(xiàn)有價值的工具本身。7. 踩坑實錄從開發(fā)到部署的常見問題在實際項目中我遇到了不少坑這里分享幾個典型的問題一工具描述description寫得太差導(dǎo)致LLM從不調(diào)用或錯誤調(diào)用?，F(xiàn)象你寫了一個完美的數(shù)據(jù)庫查詢工具但LLM總是忽略它或者用錯誤的參數(shù)調(diào)用。根因LLM完全依賴description和inputSchema來理解工具。模糊的描述如“查詢數(shù)據(jù)”毫無用處。解決方案描述要具體、包含關(guān)鍵詞、說明使用場景和限制。例如“根據(jù)用戶ID查詢其在訂單表中的最近10條訂單記錄返回訂單號、日期、金額和狀態(tài)。用戶ID必須是數(shù)字?！蓖瑫rinputSchema中的參數(shù)描述也要詳盡。問題二Server進(jìn)程僵尸或資源泄漏?，F(xiàn)象Client異常退出后Server進(jìn)程沒有正確關(guān)閉占用系統(tǒng)資源。根因Client端沒有正確處理斷開連接和清理進(jìn)程的邏輯。解決方案在Client代碼中監(jiān)聽SIGINT、SIGTERM等退出信號確保在退出前調(diào)用client.close()并killServer進(jìn)程。使用child_process時考慮使用p-kill等庫來確保進(jìn)程樹被徹底清理。問題三工具調(diào)用超時或阻塞主線程?，F(xiàn)象某個工具如一個慢速網(wǎng)絡(luò)請求執(zhí)行時間很長導(dǎo)致整個Agent響應(yīng)卡住。根因Server同步執(zhí)行耗時操作阻塞了請求處理循環(huán)。解決方案Server端所有工具處理函數(shù)都必須是async的。對于可能耗時的操作要設(shè)置合理的超時例如使用Promise.race或AbortController并及時向Client返回超時錯誤避免無限期等待。問題四多工具并發(fā)調(diào)用時的狀態(tài)沖突。現(xiàn)象Agent同時調(diào)用“寫入文件”和“讀取文件”工具導(dǎo)致讀取到不完整的數(shù)據(jù)。根因工具Server是無狀態(tài)的但工具操作的外部資源如文件、數(shù)據(jù)庫存在狀態(tài)競爭。解決方案這需要在業(yè)務(wù)邏輯層面解決。可以為相關(guān)工具組設(shè)計鎖機制如使用文件鎖、數(shù)據(jù)庫事務(wù)或者在工具描述中明確說明其非冪等性和潛在沖突讓LLM或上層的編排邏輯進(jìn)行順序調(diào)度。構(gòu)建基于MCP的AI Agent協(xié)議本身只是解決了“連接”的問題。真正的挑戰(zhàn)在于如何設(shè)計好用、安全、可靠的工具以及如何讓LLM智能、高效地使用這些工具。這需要你同時具備后端開發(fā)、API設(shè)計以及對LLM能力邊界和思維模式的深刻理解。從這個小原型出發(fā)不斷迭代你的工具集和Agent邏輯你就能打造出真正強大的AI應(yīng)用。