这是一条完整的学习与实战路线不是单个开源项目LangChain MCP。只要在做 LLM 应用开发2026 年大概率绕不开这两个词。LangChain 解决的是 Agent、检索、编排这些上层问题MCP 解决的是 Agent 如何标准化连接外部工具和数据源。把两者打通等于把“AI 能做什么”从聊天扩展到了真正可执行的工具系统。网上讲 LangChain 的教程很多讲 MCP 的也有但能把两者串成一条可落地的学习路径、并且包含可直接运行代码的内容确实少。这篇文章会按照“概念 - 环境 - MCP Server 开发 - LangChain 集成 - Agent 实战 - 批量与 API - 排查清单”的顺序展开每一步都有可复制的代码。看完你能回答这几个问题MCP 在 LangChain 里到底怎么接入Agent 为什么有时候调不到工具LangGraph 和 LangChain 是什么关系怎么把一个 MCP Server 封成批量任务和 HTTP 接口。先说结论这套组合适合做 Agent 工具链、内部知识库问答、办公自动化、业务系统接入 AI 能力等场景不需要本地大模型CPU 机器也能完成代码开发和联调真正消耗资源的是模型推理。下面直接进入内容。1. 核心能力速览能力项说明技术栈LangChain、LangGraph、MCPModel Context Protocol核心目标让 Agent 通过标准化协议调用外部工具和数据源开发语言Python 3.10硬件要求CPU 可开发推理阶段依赖模型服务云端 API 或本地模型模型支持OpenAI 兼容接口、Ollama、vLLM、各类国产模型 API启动方式命令行启动 MCP Server、Python 脚本运行 Agent、FastAPI 暴露 HTTP 接口接口能力可通过 FastAPI 封装为 HTTP API批量任务支持通过遍历任务目录调用 Agent 实现核心依赖langchain、langchain-openai、langgraph、mcp、langchain-mcp-adapters、fastmcp适合场景RAG 问答、Agent 工具调用、办公自动化、业务系统接入、MCP Server 开发测试这里说明一下LangChain 是应用框架MCP 是工具连接协议LangGraph 是有状态的任务编排引擎三者可以组合使用也可以单独使用。下面会逐个讲清楚。2. LangChain、MCP、LangGraph 到底分别解决什么问题2.1 LangChainLLM 应用的组件库LangChain 不是一个大模型也不是一个单独的工具而是把 LLM 应用开发需要的通用能力抽象成了可组合的组件包括模型封装、提示词管理、检索器、记忆、输出解析、Agent 框架等。一个典型 LangChain 应用的流程是用户输入 - 检索相关文档RAG- 拼装提示词 - 调用模型 - 解析输出 - 返回结果。如果只做简单问答LangChain 的优势不明显但一旦涉及工具调用、多轮对话、知识库检索组件化设计的价值就体现出来了。热词里经常有人问“LangChain 过时了吗”。准确地说LangChain 的核心抽象仍然是当前很多生产应用的基础但更复杂的流程编排确实在往 LangGraph 迁移。这不是过时是抽象层级在变。2.2 MCPAgent 连接外部工具的标准协议MCPModel Context Protocol是一个开放协议目标是统一 AI 应用与外部工具、数据源之间的连接方式。在没有 MCP 之前每个 Agent 项目都要自己写工具调用逻辑调用方式各不相同。MCP 定义了 Client、Server、Tool、Resource 这些标准概念让工具提供方实现一次就能被多种支持 MCP 的客户端复用。MCP Server 可以运行在本地通过 stdio 和父进程通信也可以部署为远程服务通过 HTTP/SSE 方式调用。你可以在 MCP Server 里暴露一个查询库存的函数、一个读写文件的工具、一个调用内部 API 的操作然后让 Agent 在需要时自动调用。需要特别注意的是MCP 本身不限制权限。一个 MCP Server 暴露了什么工具Agent 就能调什么工具。权限边界靠开发者在实现 Server 时控制这也是后文会反复强调的安全点。2.3 LangGraph有状态、可控制的任务编排引擎LangGraph 提供了图执行能力支持循环、分支、条件跳转、checkpoint 记忆适合编排多步骤、有状态、需要人工参与确认的复杂任务。它不是替代 LangChain而是在 LangChain 基础上补充了更细粒度的流程控制。热词里有大量“LangChain 和 LangGraph 的区别”。简单区分LangChain 偏组件库适合快速搭一条处理链路。LangGraph 偏编排引擎适合 Agent 循环、人工审批、多分支判断。LangChain 底层已经大量使用 LangGraph两者不是竞争而是不同抽象层。3. 适用场景与使用边界适合用这套组合的场景非常明确Agent 工具接入让 LLM 调用业务 API、数据库查询、文档读取、计算器等外部能力。RAG 知识库问答接入向量库结合 LangChain 的检索组件做带引用的问答。办公自动化用 MCP Server 暴露文件处理和表格操作工具Agent 按指令执行批量操作。内部系统智能助手通过 MCP 接入工单、权限、数据平台实现自然语言操作入口。MCP Server 开发与验证独立开发一个标准 MCP Server再被 LangChain Agent 或其他客户端调用。不适合的场景也要说清楚如果只是单轮普通问答直接调模型 API 即可不需要 LangChain MCP如果工具数量少且固定手写工具函数可能比引入 MCP 更轻如果流程极度简单用 LangGraph 属于过度设计。合规边界非常重要。LangChain 接入 MCP 后Agent 具备了调用外部系统的能力这意味着权限管理、数据隐私、操作审计都必须提前设计调用第三方平台、内部系统接口前必须确认已经获得授权。涉及用户个人信息、企业敏感数据的工具要设置访问白名单和操作审计。使用网络搜索、文件读写、数据库操作类 MCP Server 时要严格限定访问范围。涉及人脸、声音、版权素材等内容生成或处理时必须确认素材来源合法、用途合规。不要随意连接来路不明的远程 MCP 服务避免数据被回传到不可控的第三方。4. 环境准备与前置条件以下环境信息基于常见开发配置编写具体版本以你本机环境为准建议不要直接照抄版本号而是先确认兼容性。4.1 操作系统与 Python开发环境推荐操作系统Windows 10/11、macOS、主流 Linux 发行版均可。Python 版本3.10 或更高推荐 3.11/3.12。包管理工具建议使用uv或venv pip。这里给出使用venv初始化环境的通用命令python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate4.2 安装核心依赖pip install langchain0.3 langchain-openai langgraph mcp langchain-mcp-adapters fastmcp fastapi uvicorn如果部分包安装较慢可以按项目实际需要分步安装。langchain-mcp-adapters是 LangChain 官方提供的 MCP 适配层版本需要和mcp包匹配后面会专门讲兼容性问题。4.3 模型服务LangChain 默认支持 OpenAI 接口也兼容所有实现了 OpenAI 接口的服务。如果你有本地模型环境也可以通过 Ollama、vLLM 等以 OpenAI 兼容协议接入。配置方式推荐使用环境变量export OPENAI_API_KEY你的密钥 export OPENAI_BASE_URLhttps://api.openai.com/v1如果使用其他兼容服务把OPENAI_BASE_URL改成对应服务地址即可。注意不要把真实密钥硬编码在代码里后续排错和权限管理都会更麻烦。4.4 验证安装是否成功python -c import langchain, langgraph, mcp; print(deps ok)能正常打印deps ok说明基础依赖装好了。如果报 ModuleNotFoundError按提示补齐对应包。5. 第一个 MCP Server从零开发可调用工具下面写一个最小可用的 MCP Server。它不依赖 LangChain可以独立运行也可以被任何 MCP Client 连接。5.1 代码实现# mcp_demo_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(demo-tools) mcp.tool() def add(a: int, b: int) - int: 两数相加适合做最简单验证 return a b mcp.tool() def get_city_weather(city: str) - str: 查询指定城市天气。演示接口返回模拟数据。 # 实际项目应改为调用真实天气服务并确认数据使用授权 return f{city} 天气晴26 摄氏度模拟数据 if __name__ __main__: mcp.run()这里用了 FastMCP它是 MCP 官方提供的快速开发封装。mcp.tool()注册的是 Agent 可以直接调用的工具mcp.resource()可以注册资源不在这里展开。5.2 启动与本地验证python mcp_demo_server.py运行后终端没有明显输出这是正常的因为 stdio 传输模式下客户端和 Server 通过标准输入输出通信。可以用官方 MCP Inspector 做可视化验证npx -y modelcontextprotocol/inspector python mcp_demo_server.py这个命令需要本机有 Node.js。如果不想安装也可以写一个最小 Client 连接测试。5.3 写一个最小 Client 验证工具列表# mcp_client_test.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params StdioServerParameters( commandpython, args[mcp_demo_server.py] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() for tool in tools.tools: print(tool.name, -, tool.description) asyncio.run(main())执行后如果能看到add和get_city_weather说明 MCP Server 工作正常。这一步是整个学习路径的第一道关卡先确保工具可以在标准协议下被发现和调用再进入 LangChain 集成。6. LangChain 集成 MCP让 Agent 调用 MCP 工具MCP Server 本身不依赖 LangChain但 LangChain 的 Agent 需要工具。langchain-mcp-adapters负责把 MCP Server 暴露的工具转换成 LangChain 工具对象交给 Agent 使用。6.1 集成代码# langchain_mcp_demo.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent async def main(): server_params StdioServerParameters( commandpython, args[mcp_demo_server.py] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await load_mcp_tools(session) model ChatOpenAI( model你的模型名例如 gpt-4o-mini, api_key你的密钥或从环境变量读取, base_urlOpenAI 兼容接口地址否则留空 ) agent create_react_agent(model, tools) result await agent.ainvoke({ messages: [{role: user, content: 计算 12345 67890}] }) print(result) asyncio.run(main())load_mcp_tools把 MCP 的 Tool 转换成 LangChain Toolcreate_react_agent是 LangGraph 内置的 ReAct Agent可以自动完成“推理 - 调用工具 - 观察结果 - 继续推理”的循环。6.2 效果验证运行上述脚本时模型如果收到“计算 12345 67890”这种请求会触发add工具返回结果后生成最终回答。在终端打印结果中通常可以看到ToolMessage里面包含工具返回值。判断是否成功的标准Agent 能识别需要调用哪个工具。工具调用后能拿到正确结果。Agent 能基于工具结果生成最终回复。如果 Agent 没有调用工具而是直接给了一个错误答案最常见的原因是模型本身不支持工具调用或者工具描述不清晰。6.3 使用 HTTP/SSE 方式连接 MCP Serverstdio 适合本地开发远程部署时更推荐 HTTP/SSE 方式。MCP 客户端连接方式会不同但 LangChain 侧的工具加载逻辑基本不变。示例from mcp.client.streamable_http import streamablehttp_client # 伪代码示意需要按你部署的 MCP Server 地址调整 # async with streamablehttp_client(urlhttp://127.0.0.1:8000/mcp) as (read, write): # async with ClientSession(read, write) as session: # await session.initialize() # tools await load_mcp_tools(session)实际参数以你使用的mcp包版本和 MCP Server 部署方式为准。开发阶段先用 stdio 跑通再迁移到 HTTP 模式更稳妥。7. Agent 实战从 Prompt 模板到多工具调用7.1 工具描述决定 Agent 是否会用很多初学者遇到的问题是工具已经加载但 Agent 就是不调用。观察下来最常见的原因是工具描述写得太模糊。不推荐查询信息推荐根据用户提供的城市名查询该城市当前天气城市名为中文或拼音时先转成标准城市代码再查询工具描述越具体模型就越容易在合适的场景下调用它。如果 Agent 有多个工具描述里要说明工具之间的边界避免模型选错。7.2 多工具协同把第 5 节的 MCP Server 扩展一下让 Agent 可以同时调用多个工具完成复杂任务。例如一个“会议纪要助手”的 MCP Server# mcp_meeting_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(meeting-tools) mcp.tool() def extract_actions(markdown_text: str) - list: 从会议纪要文本中提取待办事项返回列表每一项包含负责人和截止时间演示用简单规则提取 lines [line.strip() for line in markdown_text.splitlines() if line.strip()] actions [line for line in lines if line.startswith(- [ ])] return actions mcp.tool() def summarize_doc(content: str, max_words: int 100) - str: 对传入文本做摘要max_words 控制最大字数。真实项目应该调用模型或摘要服务实现 return content[:max_words] ... if __name__ __main__: mcp.run()这类工具适合演示但要注意真实项目不要用简单截断代替摘要应该调用专门的摘要服务或模型。7.3 控制 Agent 的迭代次数和超时Agent 循环如果设计不好可能陷入反复调用工具的循环消耗大量 token。LangGraph 的create_react_agent可以配置递归限制。更多控制项需要查看当前版本文档但记住一个原则第一次跑通时把最大迭代次数控制在 5 到 10 次避免异常场景下长时间挂起。8. LangChain 与 LangGraph什么时候切到图编排对初学者来说直接用 LangChain 的简化接口最省事比如create_react_agent算是对 LangGraph 的封装。但当需求变成下面这些情况就需要显式使用 LangGraph有状态多轮流程Agent 需要记住前面的步骤并根据中间结果决定分支。人工确认环节执行写操作前需要停下来等待用户确认LangGraph 可以设计专门的确认节点。工具调用失败重试策略需要细粒度控制“失败了就换一个工具”还是“直接结束”。多 Agent 协作一个 Agent 负责规划一个 Agent 负责执行一个 Agent 负责质检用 LangGraph 更容易组织。简单对比对比项LangChain 简化接口LangGraph上手成本低中流程控制少强状态管理基础支持 checkpoint适合场景快速验证、简单链路生产级复杂编排热词里还有一些问题比如“LangChain 中的任务规划能力是怎么实现的”这通常是通过 ReAct 循环或计划-执行模式实现的LangGraph 里可以显式拆分规划节点和执行节点控制力更强。9. 批量任务与 HTTP API 封装工具链跑通之后下一步就是工程化。这里给出两个方向批量任务处理和 HTTP API 封装。9.1 批量任务处理把待处理问题放到tasks/目录每个问题一个 JSON 文件循环调用 Agent输出结果写入results/。示例# batch_runner.py import asyncio import json from pathlib import Path from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent # 这里假设 tools 已经通过前面的 MCP 方式加载 # 实际使用时把 tools 替换成你的工具列表 tools [] model ChatOpenAI( model你的模型名, api_key你的密钥, base_urlOpenAI 兼容接口地址否则留空 ) agent create_react_agent(model, tools) async def process_one(file_path: Path, output_dir: Path): task json.loads(file_path.read_text(encodingutf-8)) try: result await agent.ainvoke({ messages: [{role: user, content: task[question]}] }) answer result.get(messages, [])[-1].content if result.get(messages) else str(result) output_path output_dir / f{file_path.stem}.json output_path.write_text( json.dumps({question: task[question], answer: answer}, ensure_asciiFalse, indent2), encodingutf-8 ) print(f[OK] {file_path.name}) except Exception as exc: print(f[FAIL] {file_path.name}: {exc}) async def main(): input_dir Path(./tasks) output_dir Path(./results) output_dir.mkdir(exist_okTrue) for file_path in sorted(input_dir.glob(*.json)): await process_one(file_path, output_dir) asyncio.run(main())批量任务的关键点不在代码本身而在于每个任务独立记录日志失败不能中断整个批次。控制并发数量避免模型服务限流。输出结果要包含输入、输出、模型名、时间方便回溯。涉及写操作的任务先在小批量样本上验证。9.2 封装 FastAPI 接口# api_server.py from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class AskRequest(BaseModel): question: str # 假设已经创建好了 agent这里省略 MCP 连接代码 agent None app.post(/ask) async def ask(req: AskRequest): result await agent.ainvoke({ messages: [{role: user, content: req.question}] }) answer result.get(messages, [])[-1].content if result.get(messages) else str(result) return {question: req.question, answer: answer} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)启动python api_server.py然后用 curl 测试curl -X POST http://127.0.0.1:8000/ask \ -H Content-Type: application/json \ -d {question: 计算 12345 67890}注意接口服务不要直接暴露到公网至少加一层身份验证。密钥、模型服务地址、MCP Server 地址都应该通过环境变量或配置中心管理。10. 资源占用与性能观察10.1 显存与内存LangChain MCP 本身不直接消耗显存显存占用取决于你使用哪个模型服务。如果调用云端 API本机内存占用很低如果本地跑 Ollama 或 vLLM显存占用由模型大小和推理参数决定。以常见 7B 模型为例FP16 精度通常需要 14GB 左右显存量化后可能降到 6GB 左右但具体要以你本地模型实测为准这里不给死数字。10.2 性能瓶颈这套链路里最耗时的通常是模型推理其次是多次工具调用的往返。假设一个 Agent 任务需要调用 3 次工具每轮推理 3 秒总耗时可能接近 10 秒甚至更高。优化方向减少工具调用次数把多个简单查询合并成一个工具。减少上下文长度工具描述和中间结果不要全量塞进提示词。限制最大迭代次数避免死循环。使用更快的模型工具调用场景对模型要求其实不高响应速度比“智商”更重要。10.3 观察显存占用的方法Linux 下用nvidia-smi -l 1动态查看显存。Windows 下用任务管理器或nvidia-smi命令。本地跑模型时重点观察峰值显存和持续时间判断是否出现显存溢出。11. 常见问题与排查方法问题现象可能原因排查方式解决方案执行 LangChain 脚本时提示 ModuleNotFoundError: langchain_mcp_adapterslangchain-mcp-adapters 未安装或版本不兼容pip listfindstr mcp 查看版本MCP Server 启动后 Client 端连不上stdio 参数 command 或 args 路径错误先手动运行python mcp_demo_server.py确认能启动检查绝对路径Windows 下注意 python 命令对应关系工具已加载但 Agent 不调用工具描述不清、模型不支持 tool calling、上下文太长先单独调用session.list_tools()确认工具存在改写工具描述换支持 function call 的模型缩短上下文批量任务执行到一半卡住单次推理超时、模型服务限流、工具调用死循环加日志观察卡在哪个文件给单任务加超时和重试机制减少并发限制 Agent 最大迭代次数本地模型启动后显存溢出模型过大、量化未开启、并发数过高用 nvidia-smi 观察显存换更小的模型或开启量化降低 batch_size分批处理Windows 下 MCP 输出乱码控制台编码问题查看启动日志编码设置 PYTHONIOENCODINGutf-8脚本开头加编码声明使用 HTTP 方式连接 MCP Server 失败URL 地址错误Server 未开启对应 transport检查 MCP Server 启动参数和网络连通性先用 stdio 本地验证再迁移到 HTTPAPI 服务启动后端口冲突8000 端口被占用netstat -anofindstr 8000Agent 输出不稳定模型随机性、提示词顺序变化固定 temperature 参数对比多次输出对输出加校验和二次处理必要时增加质量校验环节12. 最佳实践与使用建议第一第一次跑通时用最简单的方式。先只加载一个add工具确认 Agent 能调用再逐步增加工具。跳过 MCP 工具加载的单独验证直接调试 Agent会很难定位问题。第二工具权限最小化。MCP Server 暴露的工具越少越好不要为了方便把所有系统操作都暴露出去。文件读写工具限制在指定目录数据库工具只开放只读查询网络请求工具做域名白名单。涉及删除、覆盖、转账、发布一类的高危操作代码里要加二次确认。第三密钥和配置分离。API Key、数据库连接、MCP Server 地址全部走环境变量或配置中心不写进代码仓库。日志里不要打印完整密钥和敏感字段。第四建立可观测性。每个任务记录输入、输出、调用链、耗时、token 消耗、失败原因。批量任务尤其重要失败要能重跑不能丢数据。第五模型选型不要贪大。工具调用任务用中等规模模型往往就够了关键是模型支持 function call 并且指令遵循能力合格。优先在真实任务上做 50 条测试样例验证准确率再决定最终模型。第六数据合规先于功能。涉及个人信息、企业机密、版权素材的数据在使用前确认授权范围对外发布或商用前人工复核 Agent 输出避免出现错误信息和合规风险。13. 总结与后续扩展从这条路线最值得先验证的点是让 LangChain Agent 成功调用一个自己实现的 MCP 工具。能完成这一步后面的批量任务、HTTP API、LangGraph 编排都是加分项。最容易踩的坑是依赖版本不匹配和工具描述不清晰这两个问题占掉初学者大量调试时间。接下来可以继续扩展的方向把 MCP Server 部署成远程 HTTP 服务接入 Dify、Cursor 等支持 MCP 的客户端。增加向量检索把 RAG 和 MCP 工具组合让 Agent 既能查文档又能调系统。用 LangGraph 设计人工确认节点让写操作先经过审核再执行。研究 Skill 与 MCP 的配合Skill 定义任务 SOPMCP 提供执行工具。针对具体业务封装专用 MCP Server沉淀成团队内部可复用的工具市场。以上内容足矣建议按顺序从第 5 节开始本地实践先跑通再扩展。 LangChain与MCP集成实战：Agent工具调用与LLM应用开发指南
这是一条完整的学习与实战路线不是单个开源项目LangChain MCP。只要在做 LLM 应用开发2026 年大概率绕不开这两个词。LangChain 解决的是 Agent、检索、编排这些上层问题MCP 解决的是 Agent 如何标准化连接外部工具和数据源。把两者打通等于把“AI 能做什么”从聊天扩展到了真正可执行的工具系统。网上讲 LangChain 的教程很多讲 MCP 的也有但能把两者串成一条可落地的学习路径、并且包含可直接运行代码的内容确实少。这篇文章会按照“概念 - 环境 - MCP Server 开发 - LangChain 集成 - Agent 实战 - 批量与 API - 排查清单”的顺序展开每一步都有可复制的代码。看完你能回答这几个问题MCP 在 LangChain 里到底怎么接入Agent 为什么有时候调不到工具LangGraph 和 LangChain 是什么关系怎么把一个 MCP Server 封成批量任务和 HTTP 接口。先说结论这套组合适合做 Agent 工具链、内部知识库问答、办公自动化、业务系统接入 AI 能力等场景不需要本地大模型CPU 机器也能完成代码开发和联调真正消耗资源的是模型推理。下面直接进入内容。1. 核心能力速览能力项说明技术栈LangChain、LangGraph、MCPModel Context Protocol核心目标让 Agent 通过标准化协议调用外部工具和数据源开发语言Python 3.10硬件要求CPU 可开发推理阶段依赖模型服务云端 API 或本地模型模型支持OpenAI 兼容接口、Ollama、vLLM、各类国产模型 API启动方式命令行启动 MCP Server、Python 脚本运行 Agent、FastAPI 暴露 HTTP 接口接口能力可通过 FastAPI 封装为 HTTP API批量任务支持通过遍历任务目录调用 Agent 实现核心依赖langchain、langchain-openai、langgraph、mcp、langchain-mcp-adapters、fastmcp适合场景RAG 问答、Agent 工具调用、办公自动化、业务系统接入、MCP Server 开发测试这里说明一下LangChain 是应用框架MCP 是工具连接协议LangGraph 是有状态的任务编排引擎三者可以组合使用也可以单独使用。下面会逐个讲清楚。2. LangChain、MCP、LangGraph 到底分别解决什么问题2.1 LangChainLLM 应用的组件库LangChain 不是一个大模型也不是一个单独的工具而是把 LLM 应用开发需要的通用能力抽象成了可组合的组件包括模型封装、提示词管理、检索器、记忆、输出解析、Agent 框架等。一个典型 LangChain 应用的流程是用户输入 - 检索相关文档RAG- 拼装提示词 - 调用模型 - 解析输出 - 返回结果。如果只做简单问答LangChain 的优势不明显但一旦涉及工具调用、多轮对话、知识库检索组件化设计的价值就体现出来了。热词里经常有人问“LangChain 过时了吗”。准确地说LangChain 的核心抽象仍然是当前很多生产应用的基础但更复杂的流程编排确实在往 LangGraph 迁移。这不是过时是抽象层级在变。2.2 MCPAgent 连接外部工具的标准协议MCPModel Context Protocol是一个开放协议目标是统一 AI 应用与外部工具、数据源之间的连接方式。在没有 MCP 之前每个 Agent 项目都要自己写工具调用逻辑调用方式各不相同。MCP 定义了 Client、Server、Tool、Resource 这些标准概念让工具提供方实现一次就能被多种支持 MCP 的客户端复用。MCP Server 可以运行在本地通过 stdio 和父进程通信也可以部署为远程服务通过 HTTP/SSE 方式调用。你可以在 MCP Server 里暴露一个查询库存的函数、一个读写文件的工具、一个调用内部 API 的操作然后让 Agent 在需要时自动调用。需要特别注意的是MCP 本身不限制权限。一个 MCP Server 暴露了什么工具Agent 就能调什么工具。权限边界靠开发者在实现 Server 时控制这也是后文会反复强调的安全点。2.3 LangGraph有状态、可控制的任务编排引擎LangGraph 提供了图执行能力支持循环、分支、条件跳转、checkpoint 记忆适合编排多步骤、有状态、需要人工参与确认的复杂任务。它不是替代 LangChain而是在 LangChain 基础上补充了更细粒度的流程控制。热词里有大量“LangChain 和 LangGraph 的区别”。简单区分LangChain 偏组件库适合快速搭一条处理链路。LangGraph 偏编排引擎适合 Agent 循环、人工审批、多分支判断。LangChain 底层已经大量使用 LangGraph两者不是竞争而是不同抽象层。3. 适用场景与使用边界适合用这套组合的场景非常明确Agent 工具接入让 LLM 调用业务 API、数据库查询、文档读取、计算器等外部能力。RAG 知识库问答接入向量库结合 LangChain 的检索组件做带引用的问答。办公自动化用 MCP Server 暴露文件处理和表格操作工具Agent 按指令执行批量操作。内部系统智能助手通过 MCP 接入工单、权限、数据平台实现自然语言操作入口。MCP Server 开发与验证独立开发一个标准 MCP Server再被 LangChain Agent 或其他客户端调用。不适合的场景也要说清楚如果只是单轮普通问答直接调模型 API 即可不需要 LangChain MCP如果工具数量少且固定手写工具函数可能比引入 MCP 更轻如果流程极度简单用 LangGraph 属于过度设计。合规边界非常重要。LangChain 接入 MCP 后Agent 具备了调用外部系统的能力这意味着权限管理、数据隐私、操作审计都必须提前设计调用第三方平台、内部系统接口前必须确认已经获得授权。涉及用户个人信息、企业敏感数据的工具要设置访问白名单和操作审计。使用网络搜索、文件读写、数据库操作类 MCP Server 时要严格限定访问范围。涉及人脸、声音、版权素材等内容生成或处理时必须确认素材来源合法、用途合规。不要随意连接来路不明的远程 MCP 服务避免数据被回传到不可控的第三方。4. 环境准备与前置条件以下环境信息基于常见开发配置编写具体版本以你本机环境为准建议不要直接照抄版本号而是先确认兼容性。4.1 操作系统与 Python开发环境推荐操作系统Windows 10/11、macOS、主流 Linux 发行版均可。Python 版本3.10 或更高推荐 3.11/3.12。包管理工具建议使用uv或venv pip。这里给出使用venv初始化环境的通用命令python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate4.2 安装核心依赖pip install langchain0.3 langchain-openai langgraph mcp langchain-mcp-adapters fastmcp fastapi uvicorn如果部分包安装较慢可以按项目实际需要分步安装。langchain-mcp-adapters是 LangChain 官方提供的 MCP 适配层版本需要和mcp包匹配后面会专门讲兼容性问题。4.3 模型服务LangChain 默认支持 OpenAI 接口也兼容所有实现了 OpenAI 接口的服务。如果你有本地模型环境也可以通过 Ollama、vLLM 等以 OpenAI 兼容协议接入。配置方式推荐使用环境变量export OPENAI_API_KEY你的密钥 export OPENAI_BASE_URLhttps://api.openai.com/v1如果使用其他兼容服务把OPENAI_BASE_URL改成对应服务地址即可。注意不要把真实密钥硬编码在代码里后续排错和权限管理都会更麻烦。4.4 验证安装是否成功python -c import langchain, langgraph, mcp; print(deps ok)能正常打印deps ok说明基础依赖装好了。如果报 ModuleNotFoundError按提示补齐对应包。5. 第一个 MCP Server从零开发可调用工具下面写一个最小可用的 MCP Server。它不依赖 LangChain可以独立运行也可以被任何 MCP Client 连接。5.1 代码实现# mcp_demo_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(demo-tools) mcp.tool() def add(a: int, b: int) - int: 两数相加适合做最简单验证 return a b mcp.tool() def get_city_weather(city: str) - str: 查询指定城市天气。演示接口返回模拟数据。 # 实际项目应改为调用真实天气服务并确认数据使用授权 return f{city} 天气晴26 摄氏度模拟数据 if __name__ __main__: mcp.run()这里用了 FastMCP它是 MCP 官方提供的快速开发封装。mcp.tool()注册的是 Agent 可以直接调用的工具mcp.resource()可以注册资源不在这里展开。5.2 启动与本地验证python mcp_demo_server.py运行后终端没有明显输出这是正常的因为 stdio 传输模式下客户端和 Server 通过标准输入输出通信。可以用官方 MCP Inspector 做可视化验证npx -y modelcontextprotocol/inspector python mcp_demo_server.py这个命令需要本机有 Node.js。如果不想安装也可以写一个最小 Client 连接测试。5.3 写一个最小 Client 验证工具列表# mcp_client_test.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params StdioServerParameters( commandpython, args[mcp_demo_server.py] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() for tool in tools.tools: print(tool.name, -, tool.description) asyncio.run(main())执行后如果能看到add和get_city_weather说明 MCP Server 工作正常。这一步是整个学习路径的第一道关卡先确保工具可以在标准协议下被发现和调用再进入 LangChain 集成。6. LangChain 集成 MCP让 Agent 调用 MCP 工具MCP Server 本身不依赖 LangChain但 LangChain 的 Agent 需要工具。langchain-mcp-adapters负责把 MCP Server 暴露的工具转换成 LangChain 工具对象交给 Agent 使用。6.1 集成代码# langchain_mcp_demo.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent async def main(): server_params StdioServerParameters( commandpython, args[mcp_demo_server.py] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await load_mcp_tools(session) model ChatOpenAI( model你的模型名例如 gpt-4o-mini, api_key你的密钥或从环境变量读取, base_urlOpenAI 兼容接口地址否则留空 ) agent create_react_agent(model, tools) result await agent.ainvoke({ messages: [{role: user, content: 计算 12345 67890}] }) print(result) asyncio.run(main())load_mcp_tools把 MCP 的 Tool 转换成 LangChain Toolcreate_react_agent是 LangGraph 内置的 ReAct Agent可以自动完成“推理 - 调用工具 - 观察结果 - 继续推理”的循环。6.2 效果验证运行上述脚本时模型如果收到“计算 12345 67890”这种请求会触发add工具返回结果后生成最终回答。在终端打印结果中通常可以看到ToolMessage里面包含工具返回值。判断是否成功的标准Agent 能识别需要调用哪个工具。工具调用后能拿到正确结果。Agent 能基于工具结果生成最终回复。如果 Agent 没有调用工具而是直接给了一个错误答案最常见的原因是模型本身不支持工具调用或者工具描述不清晰。6.3 使用 HTTP/SSE 方式连接 MCP Serverstdio 适合本地开发远程部署时更推荐 HTTP/SSE 方式。MCP 客户端连接方式会不同但 LangChain 侧的工具加载逻辑基本不变。示例from mcp.client.streamable_http import streamablehttp_client # 伪代码示意需要按你部署的 MCP Server 地址调整 # async with streamablehttp_client(urlhttp://127.0.0.1:8000/mcp) as (read, write): # async with ClientSession(read, write) as session: # await session.initialize() # tools await load_mcp_tools(session)实际参数以你使用的mcp包版本和 MCP Server 部署方式为准。开发阶段先用 stdio 跑通再迁移到 HTTP 模式更稳妥。7. Agent 实战从 Prompt 模板到多工具调用7.1 工具描述决定 Agent 是否会用很多初学者遇到的问题是工具已经加载但 Agent 就是不调用。观察下来最常见的原因是工具描述写得太模糊。不推荐查询信息推荐根据用户提供的城市名查询该城市当前天气城市名为中文或拼音时先转成标准城市代码再查询工具描述越具体模型就越容易在合适的场景下调用它。如果 Agent 有多个工具描述里要说明工具之间的边界避免模型选错。7.2 多工具协同把第 5 节的 MCP Server 扩展一下让 Agent 可以同时调用多个工具完成复杂任务。例如一个“会议纪要助手”的 MCP Server# mcp_meeting_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(meeting-tools) mcp.tool() def extract_actions(markdown_text: str) - list: 从会议纪要文本中提取待办事项返回列表每一项包含负责人和截止时间演示用简单规则提取 lines [line.strip() for line in markdown_text.splitlines() if line.strip()] actions [line for line in lines if line.startswith(- [ ])] return actions mcp.tool() def summarize_doc(content: str, max_words: int 100) - str: 对传入文本做摘要max_words 控制最大字数。真实项目应该调用模型或摘要服务实现 return content[:max_words] ... if __name__ __main__: mcp.run()这类工具适合演示但要注意真实项目不要用简单截断代替摘要应该调用专门的摘要服务或模型。7.3 控制 Agent 的迭代次数和超时Agent 循环如果设计不好可能陷入反复调用工具的循环消耗大量 token。LangGraph 的create_react_agent可以配置递归限制。更多控制项需要查看当前版本文档但记住一个原则第一次跑通时把最大迭代次数控制在 5 到 10 次避免异常场景下长时间挂起。8. LangChain 与 LangGraph什么时候切到图编排对初学者来说直接用 LangChain 的简化接口最省事比如create_react_agent算是对 LangGraph 的封装。但当需求变成下面这些情况就需要显式使用 LangGraph有状态多轮流程Agent 需要记住前面的步骤并根据中间结果决定分支。人工确认环节执行写操作前需要停下来等待用户确认LangGraph 可以设计专门的确认节点。工具调用失败重试策略需要细粒度控制“失败了就换一个工具”还是“直接结束”。多 Agent 协作一个 Agent 负责规划一个 Agent 负责执行一个 Agent 负责质检用 LangGraph 更容易组织。简单对比对比项LangChain 简化接口LangGraph上手成本低中流程控制少强状态管理基础支持 checkpoint适合场景快速验证、简单链路生产级复杂编排热词里还有一些问题比如“LangChain 中的任务规划能力是怎么实现的”这通常是通过 ReAct 循环或计划-执行模式实现的LangGraph 里可以显式拆分规划节点和执行节点控制力更强。9. 批量任务与 HTTP API 封装工具链跑通之后下一步就是工程化。这里给出两个方向批量任务处理和 HTTP API 封装。9.1 批量任务处理把待处理问题放到tasks/目录每个问题一个 JSON 文件循环调用 Agent输出结果写入results/。示例# batch_runner.py import asyncio import json from pathlib import Path from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent # 这里假设 tools 已经通过前面的 MCP 方式加载 # 实际使用时把 tools 替换成你的工具列表 tools [] model ChatOpenAI( model你的模型名, api_key你的密钥, base_urlOpenAI 兼容接口地址否则留空 ) agent create_react_agent(model, tools) async def process_one(file_path: Path, output_dir: Path): task json.loads(file_path.read_text(encodingutf-8)) try: result await agent.ainvoke({ messages: [{role: user, content: task[question]}] }) answer result.get(messages, [])[-1].content if result.get(messages) else str(result) output_path output_dir / f{file_path.stem}.json output_path.write_text( json.dumps({question: task[question], answer: answer}, ensure_asciiFalse, indent2), encodingutf-8 ) print(f[OK] {file_path.name}) except Exception as exc: print(f[FAIL] {file_path.name}: {exc}) async def main(): input_dir Path(./tasks) output_dir Path(./results) output_dir.mkdir(exist_okTrue) for file_path in sorted(input_dir.glob(*.json)): await process_one(file_path, output_dir) asyncio.run(main())批量任务的关键点不在代码本身而在于每个任务独立记录日志失败不能中断整个批次。控制并发数量避免模型服务限流。输出结果要包含输入、输出、模型名、时间方便回溯。涉及写操作的任务先在小批量样本上验证。9.2 封装 FastAPI 接口# api_server.py from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class AskRequest(BaseModel): question: str # 假设已经创建好了 agent这里省略 MCP 连接代码 agent None app.post(/ask) async def ask(req: AskRequest): result await agent.ainvoke({ messages: [{role: user, content: req.question}] }) answer result.get(messages, [])[-1].content if result.get(messages) else str(result) return {question: req.question, answer: answer} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)启动python api_server.py然后用 curl 测试curl -X POST http://127.0.0.1:8000/ask \ -H Content-Type: application/json \ -d {question: 计算 12345 67890}注意接口服务不要直接暴露到公网至少加一层身份验证。密钥、模型服务地址、MCP Server 地址都应该通过环境变量或配置中心管理。10. 资源占用与性能观察10.1 显存与内存LangChain MCP 本身不直接消耗显存显存占用取决于你使用哪个模型服务。如果调用云端 API本机内存占用很低如果本地跑 Ollama 或 vLLM显存占用由模型大小和推理参数决定。以常见 7B 模型为例FP16 精度通常需要 14GB 左右显存量化后可能降到 6GB 左右但具体要以你本地模型实测为准这里不给死数字。10.2 性能瓶颈这套链路里最耗时的通常是模型推理其次是多次工具调用的往返。假设一个 Agent 任务需要调用 3 次工具每轮推理 3 秒总耗时可能接近 10 秒甚至更高。优化方向减少工具调用次数把多个简单查询合并成一个工具。减少上下文长度工具描述和中间结果不要全量塞进提示词。限制最大迭代次数避免死循环。使用更快的模型工具调用场景对模型要求其实不高响应速度比“智商”更重要。10.3 观察显存占用的方法Linux 下用nvidia-smi -l 1动态查看显存。Windows 下用任务管理器或nvidia-smi命令。本地跑模型时重点观察峰值显存和持续时间判断是否出现显存溢出。11. 常见问题与排查方法问题现象可能原因排查方式解决方案执行 LangChain 脚本时提示 ModuleNotFoundError: langchain_mcp_adapterslangchain-mcp-adapters 未安装或版本不兼容pip listfindstr mcp 查看版本MCP Server 启动后 Client 端连不上stdio 参数 command 或 args 路径错误先手动运行python mcp_demo_server.py确认能启动检查绝对路径Windows 下注意 python 命令对应关系工具已加载但 Agent 不调用工具描述不清、模型不支持 tool calling、上下文太长先单独调用session.list_tools()确认工具存在改写工具描述换支持 function call 的模型缩短上下文批量任务执行到一半卡住单次推理超时、模型服务限流、工具调用死循环加日志观察卡在哪个文件给单任务加超时和重试机制减少并发限制 Agent 最大迭代次数本地模型启动后显存溢出模型过大、量化未开启、并发数过高用 nvidia-smi 观察显存换更小的模型或开启量化降低 batch_size分批处理Windows 下 MCP 输出乱码控制台编码问题查看启动日志编码设置 PYTHONIOENCODINGutf-8脚本开头加编码声明使用 HTTP 方式连接 MCP Server 失败URL 地址错误Server 未开启对应 transport检查 MCP Server 启动参数和网络连通性先用 stdio 本地验证再迁移到 HTTPAPI 服务启动后端口冲突8000 端口被占用netstat -anofindstr 8000Agent 输出不稳定模型随机性、提示词顺序变化固定 temperature 参数对比多次输出对输出加校验和二次处理必要时增加质量校验环节12. 最佳实践与使用建议第一第一次跑通时用最简单的方式。先只加载一个add工具确认 Agent 能调用再逐步增加工具。跳过 MCP 工具加载的单独验证直接调试 Agent会很难定位问题。第二工具权限最小化。MCP Server 暴露的工具越少越好不要为了方便把所有系统操作都暴露出去。文件读写工具限制在指定目录数据库工具只开放只读查询网络请求工具做域名白名单。涉及删除、覆盖、转账、发布一类的高危操作代码里要加二次确认。第三密钥和配置分离。API Key、数据库连接、MCP Server 地址全部走环境变量或配置中心不写进代码仓库。日志里不要打印完整密钥和敏感字段。第四建立可观测性。每个任务记录输入、输出、调用链、耗时、token 消耗、失败原因。批量任务尤其重要失败要能重跑不能丢数据。第五模型选型不要贪大。工具调用任务用中等规模模型往往就够了关键是模型支持 function call 并且指令遵循能力合格。优先在真实任务上做 50 条测试样例验证准确率再决定最终模型。第六数据合规先于功能。涉及个人信息、企业机密、版权素材的数据在使用前确认授权范围对外发布或商用前人工复核 Agent 输出避免出现错误信息和合规风险。13. 总结与后续扩展从这条路线最值得先验证的点是让 LangChain Agent 成功调用一个自己实现的 MCP 工具。能完成这一步后面的批量任务、HTTP API、LangGraph 编排都是加分项。最容易踩的坑是依赖版本不匹配和工具描述不清晰这两个问题占掉初学者大量调试时间。接下来可以继续扩展的方向把 MCP Server 部署成远程 HTTP 服务接入 Dify、Cursor 等支持 MCP 的客户端。增加向量检索把 RAG 和 MCP 工具组合让 Agent 既能查文档又能调系统。用 LangGraph 设计人工确认节点让写操作先经过审核再执行。研究 Skill 与 MCP 的配合Skill 定义任务 SOPMCP 提供执行工具。针对具体业务封装专用 MCP Server沉淀成团队内部可复用的工具市场。以上内容足矣建议按顺序从第 5 节开始本地实践先跑通再扩展。