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