做AI Agent时我被内置工具坑到怀疑人生写LangChain Agent原生工具一段时间踩了两个无法解决的硬伤工具强绑定项目工具代码和Agent耦合换项目就要复制重构无法复用语言锁死Node写的工具不能给Python/Rust Agent调用跨语言互通完全无解直到接触MCPModel Context Protocol才找到标准化解决方案把工具抽成独立MCP Server进程通过统一协议通信本地stdio、远程HTTP双模式真正实现LLM与工具完全解耦。读完本文你能学到MCP协议核心原理、stdio跨进程通信底层逻辑完整可运行Node MCP Server内置用户查询工具静态资源LangChain MultiServerMCPClient多服务Agent调用实战开发过程中90%人都会踩的MCP坑与修复方案一套可直接迁移到生产的Agent循环调用模板一、先搞懂MCP到底解决了什么问题1. 无MCP的旧架构痛点拉满Agent主进程LangChain/Python ↓ 直接内存调用 Tool函数同进程、同语言缺陷工具与Agent代码强耦合无法跨项目共享只能同语言调用Java/Python/JS工具无法互通工具崩溃直接连带整个Agent进程挂掉2. MCP标准化架构解耦核心Agent客户端任意语言 ←MCP协议→ MCP Server独立子进程 通信分两种模式 1. 本地stdio标准输入输出子进程IPC通信本次实战 2. 远程HTTP/SSE公网部署跨机器调用MCP两大核心能力Tool工具给LLM提供可执行能力本文用户查询接口Resource静态资源给LLM注入上下文文档使用指南二、实战第一步手写MCP ServerNode完整代码新建my-mcp-server.mjs完整可直接运行内置用户查询工具静态文档资源import{McpServer}frommodelcontextprotocol/sdk/server/mcp.js;import{StdioServerTransport}frommodelcontextprotocol/sdk/server/stdio.js;import{z}fromzod;// 模拟数据库生产可替换真实MySQL/Redisconstdatabase{users:{001:{id:001,name:祖豪,email:zhqq.com,role:admin},002:{id:002,name:光光,email:ggqq.com,role:user},003:{id:003,name:小红,email:xhqq.com,role:user},}}// 初始化MCP服务实例constservernewMcpServer({name:my-mcp-server,version:1.0.0});// 注册工具查询用户信息server.registerTool(query_user,{description:查询数据库中的用户信息。输入用户ID, 返回该用户的详细信息姓名、邮箱、角色,inputSchema:{userId:z.string().describe(用户ID, 例如001, 002, 003)}},async({userId}){constuserdatabase.users[userId];if(!user){return{content:[{type:text,text:用户 ID${userId}不存在。可用的ID: 001, 002, 003}]}}return{content:[{type:text,text:用户${user.id}的信息是姓名${user.name}, 邮箱${user.email}, 角色${user.role}}]}})// 注册静态资源MCP使用指南自动注入Agent系统提示词server.registerResource(使用指南,docs://guide,{description:MCP Server 使用指南,mimeType:text/plain},async(){return{contents:[{uri:docs://guide,mimeType:text/plain,text:MCP Server 使用指南 功能提供用户查询等工具。 使用在 Cursor 等 MCP Client / LangChain Agent 中通过自然语言对话框架会自动调用相应工具。}]}})// stdio跨进程通信通道本地MCP核心consttransportnewStdioServerTransport();awaitserver.connect(transport);关键代码说明StdioServerTransport本地进程间通信载体Client启动子进程后通过标准输入输出传输JSON-RPC消息registerTool对外暴露可被LLM调用的工具zod做参数强校验registerResource静态资源Client可读取作为系统上下文减少人工写Prompt三、实战第二步LangChain MCP Client Agent调用完整代码新建langchain-mcp-test.js基于DeepSeek大模型自动拉起MCP子进程、循环工具调用importdotenv/config;import{MultiServerMCPClient}fromlangchain/mcp-adapters;import{ChatOpenAI}fromlangchain/openai;importchalkfromchalk;import{HumanMessage,SystemMessage,ToolMessage}fromlangchain/core/messages;// 初始化大模型兼容OpenAI格式APIconstmodelnewChatOpenAI({modelName:deepseek-v4-pro,apiKey:process.env.DEEPSEEK_API_KEY,temperature:0,configuration:{baseURL:https://api.deepseek.com/v1,},});// 多MCP服务客户端配置自动启动node子进程constmcpClientnewMultiServerMCPClient({mcpServers:{my-mcp-server:{command:node,args:[C:/Users/26066/Desktop/workspace/hwq_ai/ai/agent_in_action/mcp-demo/src/my-mcp-server.mjs]}}})// 1. 拉取所有MCP服务暴露的工具consttoolsawaitmcpClient.getTools();// 2. 读取所有静态资源拼接为系统提示词constresourceResawaitmcpClient.listResources();letresourceContent;for(const[serverName,resources]ofObject.entries(resourceRes)){for(constresourceofresources){constcontentawaitmcpClient.readResource(serverName,resource.uri)resourceContentcontent[0].text;}}console.log(加载系统上下文文档,resourceContent,---------------);// 模型绑定MCP工具constmodelWithToolsmodel.bindTools(tools);/** * Agent循环执行核心逻辑 * param {string} query 用户提问 * param {number} maxIterations 最大工具调用轮次防止死循环 */asyncfunctionrunAgentWithTools(query,maxIterations30){constmessages[newSystemMessage(resourceContent),newHumanMessage(query)];for(leti0;imaxIterations;i){console.log(chalk.bgGreen(正在思考第${i1}轮));constresponseawaitmodelWithTools.invoke(messages);messages.push(response);// 无工具调用直接返回最终回答if(!response.tool_calls||response.tool_calls.length0){console.log(\n AI 最终回复 \n${response.content});returnresponse.content;}console.log(chalk.bgBlue(检测到${response.tool_calls.length}个工具调用));console.log(chalk.bgBlue(工具调用:${response.tool_calls.map(tt.name).join(, )}))// 串行执行所有工具调用for(consttoolCallofresponse.tool_calls){constfoundTooltools.find(tt.nametoolCall.name);if(foundTool){consttoolResultawaitfoundTool.invoke(toolCall.args);// 必须携带tool_call_id否则模型无法匹配工具返回结果messages.push(newToolMessage({content:toolResult,tool_call_id:toolCall.id}))}else{console.log(chalk.bgRed(未找到工具:${toolCall.name}));messages.push(newToolMessage({content:未找到工具:${toolCall.name},tool_call_id:toolCall.id}));}}}// 达到最大迭代次数返回最后一轮输出returnmessages[messages.length-1].content;}// 执行测试查询awaitrunAgentWithTools(查一下用户001的信息)// 关键关闭MCP子进程防止僵尸进程残留awaitmcpClient.close();运行流程拆解MultiServerMCPClient根据配置自动执行node命令拉起MCP Server子进程Client通过stdio和子进程建立IPC通信拉取工具列表静态资源文档资源文档自动注入SystemMessage让模型知道工具使用规则Agent循环模型思考→发起工具调用→Client转发给MCP Server→收集结果回传给模型对话结束调用mcpClient.close()销毁子进程释放资源四、开发必看MCP高频踩坑清单坑1忘记调用close()大量僵尸进程残留现象多次启动脚本后任务管理器大量node进程占用内存不会自动销毁原因MCP子进程生命周期依附主进程异常退出时不会自动关闭解决方案无论正常/异常结束都要执行await mcpClient.close()生产建议用try/finally包裹try{awaitrunAgentWithTools(查一下用户001的信息)}finally{awaitmcpClient.close();}坑2工具返回不携带tool_call_id模型丢失上下文现象工具执行成功但模型重复调用工具、无法读取返回结果核心规则ToolMessage必须传入对应tool_call.id模型靠ID匹配工具请求与返回值坑3文件路径写相对路径MCP子进程找不到服务现象启动报错 spawn node ENOENT无法拉起MCP服务解决args中填写MCP Server绝对路径避免工作目录不一致导致路径解析错误坑4工具描述模糊模型不会主动调用工具现象提问需要查询用户但模型直接回答不知道不触发query_user优化完善description描述明确工具适用场景参数describe补充示例坑5循环无最大迭代次数Agent死循环现象模型反复调用同一个工具脚本无限运行解决方案设置maxIterations限制轮次示例30轮超过直接终止循环五、MCP核心优势总结跨语言互通Node/Python/Rust/Java写的MCP Server任意语言Agent均可调用进程隔离工具崩溃不会让主Agent进程挂掉稳定性大幅提升工具复用一套MCP服务Cursor、LangChain、Claude Desktop均可接入上下文托管Resource统一管理文档、配置不用手动拼接Prompt两种部署模式本地stdio低成本开发远程HTTP支持云端共享工具对比传统内置工具MCP彻底解决工具耦合、语言锁定两大核心痛点是AI Agent工程化落地标准方案。