在实际的 AI Agent 开发中真正让人卡住的往往不是大模型 API 怎么调而是 Agent 如何安全、稳定、可复用地把外部工具接进来。LangChain 提供了模型、工具、记忆和编排的抽象MCPModel Context Protocol则统一了工具暴露和调用的协议LangGraph 又进一步把“调几次模型、什么时候调用工具、调用哪个工具”变成了可控制的图执行流程。这篇文章围绕“LangChain 结合 MCP 完成 Agent 工具开发”这一条主线从原理、环境、代码到排错带你把一个最小可运行的 Agent 工具项目从零搭起来并说明如何接入 DeepSeek 模型、如何在 Claude Code 中注册 MCP Server。文章适合已经写过基础 Python 和简单大模型 API 调用、但还没有系统接触 Agent 和工具协议的开发者。最终你会得到一个可运行的 MCP Server、一个能自己决定是否调用工具的 LangChain Agent以及一个用 LangGraph 实现的多轮工具调用案例。过程中会给出环境依赖、代码片段、验证命令、常见报错和排查清单方便之后迁移到自己业务中。1. 先理清 Agent、MCP、LangChain 和 LangGraph 之间的关系1.1 Agent 到底在解决什么问题普通的大模型应用是一次性问答用户输入一句话模型直接输出一段文本。它的限制在于模型训练数据有截止时间也不具备访问实时数据、读写外部系统、执行计算或操作业务系统的能力。Agent 的思路是让模型不再是“直接输出答案”而是“输出行动计划”由程序去执行工具调用把工具结果返回给模型再由模型生成最终回答。这里的关键是“决策循环”。模型要判断这个问题需不需要查时间需不需要算公式需不需要调用数据库如果不需要就直接回答如果需要就生成一个工具调用请求。程序拿到请求后执行真实函数把结果拼进对话上下文继续交给模型推理。这样一个“思考-调用-观察-再思考”的过程就是 ReAct 模式。在代码层面Agent 通常由三部分组成大模型、工具列表、执行循环。大模型负责生成自然语言和结构化工具调用参数工具列表告诉模型有哪些能力可用执行循环负责把模型输出的工具调用翻译成真实函数调用并把结果回填。1.2 MCP 解决了工具接入的什么问题在没有 MCP 之前每个 Agent 项目接入新工具通常要写一层自定义封装。比如给模型加一个天气工具需要自己定义 JSON Schema、自己实现调用入口、自己处理鉴权和错误返回。工具一多接口风格就会混乱而且不同框架之间很难复用。MCP 出现后工具提供方只需要按统一协议暴露工具Agent 端按统一客户端去连接和发现工具就能拿到工具描述和调用入口。MCP 采用客户端-服务端模型。MCP Server 负责暴露工具、提示词和资源MCP Client 负责连接 Server 并获取可用工具。传输方式上本地开发常用 stdio也就是 Agent 通过启动一个子进程与 Server 通信远程部署还可以使用 Streamable HTTP 等方式。在 Agent 项目里MCP 的价值不是让模型更聪明而是让工具接入变得标准化工具能力由独立 Server 维护Agent 只需要关心“连接到哪个 Server、拿到哪些工具”。1.3 LangChain 与 LangGraph 的关系LangChain 是一套面向大模型应用的组件库包含模型封装、Prompt 模板、输出解析、向量存储、工具抽象、记忆等模块。它的定位是“提供构建块”开发者可以用它快速拼装一个 Agent。LangGraph 是建立在 LangChain 组件之上的低层编排框架。它把 Agent 的执行过程建模成一张图节点代表一段逻辑比如调用模型、调用工具、检查状态边代表流转关系。相比 LangChain 早期 AgentExecutor 那种黑盒循环LangGraph 能让你看到每一步的状态变化也能显式控制条件路由、分支、循环和子图。一个简单的区分方式LangChain 更适合快速调用模型和处理组件LangGraph 更适合需要精确控制的 Agent 流程。实际项目可以把两者混用用 LangChain 的模型和工具抽象用 LangGraph 控制执行图。这篇文章后面的代码也是这个组合。1.4 一次完整的 Agent 调用链路一个基于 LangChain MCP 的 Agent 请求内部通常按下面这条链路执行用户输入消息进入 Agent。Agent 读取当前可用的 MCP 工具列表工具列表包含工具名称、描述、参数 Schema。模型根据用户问题决定是否调用工具如果调用则输出结构化 tool_call。LangChain 的工具执行器根据 tool_call 中的名称和参数调用对应 MCP 工具。MCP Client 把调用请求发送给 MCP ServerServer 执行真实逻辑并返回结果。工具结果作为新消息继续传给模型。模型基于工具结果生成最终答案。这条链路里最容易出题的点是第四步和第五步的衔接。工具名称不匹配、参数格式传错、Server 启动失败、返回值太长、模型不支持 function calling都会导致 Agent 卡住或报错。2. 环境准备与依赖对齐避免后面每一步都踩版本坑2.1 Python 版本与虚拟环境MCP Python SDK 和 LangChain 生态对 Python 版本有要求推荐使用 Python 3.10 以上。这里强调版本是因为 MCP 的异步通信、类型注解和部分依赖需要较新的解释器支持。项目根目录下执行mkdir langchain-mcp-agent cd langchain-mcp-agent python -m venv .venv source .venv/bin/activateWindows 下激活命令是.venv\Scripts\activate每一步完成后都可以用python --version确认当前解释器。不要在基础环境里直接安装一堆包否则不同项目之间很容易出现依赖冲突。2.2 安装依赖包先把核心依赖装好。由于 MCP、LangChain 和 LangGraph 的版本更新比较频繁下面的包名以当前主流写法为例实际安装时以官方最新的稳定版本为准。pip install --upgrade pip pip install mcp[cli] pip install langchain langchain-openai langgraph langchain-mcp-adapters如果使用 DeepSeek 模型需要安装langchain-openai因为 DeepSeek 的 API 是 OpenAI 兼容格式。安装完成后可以查看关键包版本pip show mcp langchain langchain-openai langgraph langchain-mcp-adapters这里特别说明不要只安装langchain就以为万事大吉。langchain-mcp-adapters负责把 MCP 工具转成 LangChain 工具langgraph负责提供 Agent 执行循环缺少任何一个后面都会在 import 时报错。2.3 DeepSeek 模型配置DeepSeek 通过 OpenAI 兼容接口提供模型服务。使用前需要在 DeepSeek 开放平台申请 API Key。为了避免 API Key 写死在代码里推荐使用环境变量export DEEPSEEK_API_KEY你的key export DEEPSEEK_BASE_URLhttps://api.deepseek.com/v1 export DEEPSEEK_MODELdeepseek-chatWindows PowerShell 下使用$env:DEEPSEEK_API_KEY你的key $env:DEEPSEEK_BASE_URLhttps://api.deepseek.com/v1 $env:DEEPSEEK_MODELdeepseek-chat选择模型名时要注意不同时段开放的模型名可能不同最新模型名要以平台控制台为准。工具调用场景建议选择支持 function calling 的模型并在测试前确认模型名正确。如果模型名写错通常会在请求阶段直接返回 401 或 400 错误。2.4 项目结构与凭证管理这个最小项目建议按下面的结构组织langchain-mcp-agent/ ├── .venv/ ├── .env ├── mcp_time_server.py ├── agent_langchain.py └── agent_langgraph.py.env文件只保存本地配置不要提交到 Git。Python 代码中加载.env可以直接使用python-dotenv也可以手动读取。更稳妥的做法是使用os.environ.get并在缺失时给出明确错误提示。import os from dotenv import load_dotenv load_dotenv() api_key os.environ.get(DEEPSEEK_API_KEY) if not api_key: raise ValueError(缺少 DEEPSEEK_API_KEY请检查 .env 文件)这样做的原因是模型调用报错时第一优先排查的不是代码逻辑而是环境变量是否真的被读到。3. 从零实现一个 MCP Server让 Agent 拥有第一个工具3.1 为什么先写 MCP Server 而不是直接写 Agent如果把 Agent 先写出来再临时去接工具代码会写得很乱例如在 Agent 执行循环里直接塞 if-else 判断。MCP 的设计思路是先把工具独立出来Agent 端通过协议发现工具。因此先写 Server能让你在完全不依赖大模型的情况下先验证工具本身可用再逐步接入模型。这一节实现一个非常简单的 MCP Server暴露两个工具一个是获取当前时间一个是做简单四则运算。这样不需要申请任何外部 API本地就能验证完整链路。3.2 用 FastMCP 实现一个 ServerMCP Python SDK 提供了FastMCP。它的写法类似 FastAPI用装饰器就能暴露工具。下面代码保存为mcp_time_server.pyfrom datetime import datetime from mcp.server.fastmcp import FastMCP mcp FastMCP(demo-time-server) mcp.tool() def get_current_time(timezone: str local) - str: 获取当前时间。timezone 目前只支持 local返回本地服务器时间。 if timezone ! local: return f当前版本仅支持 local无法处理 {timezone} return datetime.now().isoformat() mcp.tool() def calculator(expression: str) - str: 对简单的四则运算表达式求值例如 1 2 * 3。 allowed set(0123456789-*/(). ) if any(c not in allowed for c in expression): return 表达式包含非法字符 try: result eval(expression, {__builtins__: {}}, {}) return str(result) except Exception as exc: return f计算失败: {exc} if __name__ __main__: mcp.run(transportstdio)这里需要注意几个工程点。get_current_time用一个简单字符串参数演示工具入参传递calculator使用了eval仅用于本地学习示例生产环境绝对不要直接eval用户输入应该换成表达式解析库或只做有限规则校验。真正落地时工具内部还要补充日志、异常分类、超时控制和返回长度限制。3.3 配置 stdio 传输方式上面代码最后一行已经指定了transportstdio。stdio 模式下的工作方式是Agent 端启动一个 Python 子进程执行mcp_time_server.pyMCP SDK 通过标准输入和标准输出与子进程通信。因此这个文件不要写任何无关的print输出否则 print 内容会混入 MCP 协议消息导致客户端解析失败。调试时如果需要打印日志应使用logging模块并输出到 stderr 或文件import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(mcp-time-server) logger.info(server starting)标准输出保留给 MCP 协议标准错误和日志文件用于开发排查。3.4 启动并验证 MCP Server可以直接用 MCP CLI 检查 Server 是否能列出工具。安装mcp[cli]后在项目目录执行mcp dev mcp_time_server.py在打开的调试页面里可以看到暴露出的get_current_time和calculator。也可以使用命令行方式做一次快速检查python mcp_time_server.py这个命令会阻塞因为它正在等待 stdio 输入。看到进程不退出说明 Server 脚本本身没有语法错误。更规范的验证方式是用 MCP Inspector 或写一个临时客户端去连接 Server 并列出工具。这一步通过后可以确认工具层是完好的接下来再写 Agent。4. 使用 LangChain 接入 MCP 工具并跑通第一个 Agent4.1 加载 MCP 工具LangChain 通过langchain-mcp-adapters提供 MCP 工具到 LangChain 工具的转换能力。加载工具前需要先建立 MCP 客户端会话。下面是加载单个 MCP Server 工具的示例使用异步方式import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools async def load_tools(): server_params StdioServerParameters( commandpython, args[mcp_time_server.py], cwd., ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: tools await load_mcp_tools(session) for tool in tools: print(tool.name, tool.description) return tools if __name__ __main__: asyncio.run(load_tools())关键点有两个StdioServerParameters中的command和args要能和命令行启动方式对应整个客户端生命周期要放在async with中确保退出时子进程被正确关闭。如果项目要接入多个 MCP Server可以使用MultiServerMCPClient它允许在一个 Agent 里同时连接时间服务、数据库服务、搜索服务等from langchain_mcp_adapters.client import MultiServerMCPClient client MultiServerMCPClient( { time: { command: python, args: [mcp_time_server.py], transport: stdio, } } )具体使用方式与当前版本的langchain-mcp-adapters有关项目落地前建议查看该库的 README确认是同步还是异步用法。4.2 创建调用 DeepSeek 模型的 Agent有了工具列表后创建 Agent 就变得简单。先创建模型实例再通过create_react_agent组装模型和工具。下面是完整的agent_langchain.pyimport asyncio import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools load_dotenv() def build_llm(): return ChatOpenAI( modelos.getenv(DEEPSEEK_MODEL, deepseek-chat), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com/v1), api_keyos.getenv(DEEPSEEK_API_KEY), temperature0, ) async def main(): llm build_llm() server_params StdioServerParameters( commandpython, args[mcp_time_server.py], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: tools await load_mcp_tools(session) agent create_react_agent(llm, tools) result await agent.ainvoke({ messages: [{role: user, content: 现在几点了}] }) print(result[messages][-1].content) if __name__ __main__: asyncio.run(main())这段代码的核心是create_react_agent。它内部已经实现了 ReAct 循环模型输出工具调用 - 工具执行 - 结果返回模型。不需要自己写 while 循环。temperature0是工具调用场景的常用配置因为工具调用需要确定性而不是创造性。4.3 运行 Agent 并观察工具调用日志执行python agent_langchain.py如果一切正常控制台会输出类似“当前时间是 2026-xx-xxTxx:xx:xx”的结果。如果希望看到模型内部思考过程可以给模型实例开启 verbosellm ChatOpenAI( ..., verboseTrue, )更多日志可以通过langchain的调试模式开启export LANGCHAIN_TRACING_V2false export LANGCHAIN_DEBUGtrue在开发环境打开调试日志能直观看到模型有没有生成 tool_call、工具名称是什么、工具返回了什么。这是排查 Agent 问题最有效的方式。4.4 常见错误工具返回格式、超时和默认值运行过程中最常见的三类问题如下。第一模型没有生成工具调用。可能原因模型本身不支持 function calling或者 Prompt 中没有足够的工具说明。这时候先确认tools非空再确认模型实例没有写错模型名。可以先单独用模型问一个必须查时间的问题观察返回内容。第二工具返回内容异常。MCP 工具返回值会被直接塞进模型上下文如果返回超大正文或包含大量特殊字符模型可能无法生成正确回答。工具内应尽量返回精简文本并截断长内容。第三Agent 等待工具执行超时。MCP Server 启动很慢、脚本路径错误、Python 解释器路径不对都会导致工具调用迟迟没有结果。排查方法是在StdioServerParameters中确认command使用的是虚拟环境里的 Python 绝对路径which python如果项目使用的是.venv需要把 command 写成command/path/to/project/.venv/bin/pythonWindows 下使用类似commandC:\\path\\to\\project\\.venv\\Scripts\\python.exe5. 用 LangGraph 实现多步 Agent条件路由与记忆5.1 为什么单轮 Agent 不够用create_react_agent已经覆盖了“调用工具-回填-再回答”的基本循环但它内部是一条固定链路。真实业务往往有更复杂的要求模型判断结果不满足条件时应该继续调用另一个工具而不是直接结束。用户多轮对话中工具结果需要和历史消息一起参与推理。某些分支需要并行执行多个工具某些分支需要进入子图处理。LangGraph 把流程拆成节点和边开发者可以控制每一步。下面实现一个最小示例模型节点负责生成回答或工具调用工具节点负责执行 MCP 工具条件边根据模型结果决定是继续调用工具还是结束。5.2 节点、边与状态先定义 Agent 状态。状态会在每个节点间传递这里使用messages字段保存对话历史from typing import Annotated, TypedDict from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages]Annotated[list, add_messages]表示每次更新消息时使用add_messages合并策略。这样每个节点返回的新消息会自动追加到历史列表而不是覆盖旧消息。模型节点和执行工具节点的代码如下from langchain_core.messages import AIMessage, ToolMessage def call_model(state: AgentState, config): messages state[messages] response llm_with_tools.invoke(messages, config) return {messages: [response]} def call_tool(state: AgentState): last_message state[messages][-1] tool_calls last_message.tool_calls results [] for tool_call in tool_calls: tool_result tools_by_name[tool_call[name]].invoke(tool_call[args]) results.append(ToolMessage(contenttool_result, tool_call_idtool_call[id])) return {messages: results}这里的tools_by_name是从 MCP 加载出的工具列表转换成的字典方便按名称查找。5.3 加入条件路由和工具循环条件路由函数判断模型输出中是否存在工具调用def should_continue(state: AgentState): last_message state[messages][-1] if hasattr(last_message, tool_calls) and len(last_message.tool_calls) 0: return continue return end然后构建图from langgraph.graph import StateGraph, START, END graph StateGraph(AgentState) graph.add_node(agent, call_model) graph.add_node(tools, call_tool) graph.add_edge(START, agent) graph.add_conditional_edges( agent, should_continue, {continue: tools, end: END}, ) graph.add_edge(tools, agent) app graph.compile()这段图表达的含义是从 START 进入 agent 节点agent 节点如果返回工具调用就进入 tools 节点执行tools 节点执行完回到 agent如果 agent 节点没有工具调用就直接结束。工具执行结果会作为新的消息传递给模型这样模型能基于最新结果继续推理。5.4 运行与结果验证把图构建逻辑封装到agent_langgraph.py然后执行async def run(): ... result await app.ainvoke({ messages: [{role: user, content: 先计算 123 * 456再告诉我当前时间}] }) for message in result[messages]: print(message.type, str(message.content)[:200])如果图流程正确输出中应该能看到 AIMessage、ToolMessage、再 AIMessage 的交替序列。这也是一种验证方式观察消息类型序列是否符合预期。LangGraph 的优势在这一步体现出来。如果想要在模型判断某个条件后进入不同分支只需要修改条件边的映射如果想要把一组节点封装成子图可以在父图节点中调用子图如果想要并行执行多个工具可以把tools节点改成并行调用。执行流程变成可控制、可测试的状态图而不是黑盒循环。6. 在 Claude Code 中注册 MCP Server并接入 DeepSeek6.1 Claude Code 是什么场景Claude Code 是一个终端环境里的 AI 编程助手类工具它也能通过 MCP 协议使用外部工具。把前面写好的 MCP Server 注册到 Claude Code 后就可以在对话中直接触发 get_current_time、calculator 这类工具。这里关注的不是如何安装 Claude Code而是如何把自定义 MCP Server 接入到现有工具流程中。需要注意Claude Code 对模型名和版本的管理比较严格。如果你通过配置方式接入 DeepSeek 或其他 OpenAI 兼容模型模型名必须是该环境下能识别的名称。社区中把 DeepSeek 接入 Claude Code 的做法通常是通过环境变量指定 API 地址和模型名但具体是否被当前版本支持需要以官方文档和实际运行结果为准。6.2 注册 MCP Server 配置文件Claude Code 支持在配置中增加 MCP Server。配置文件通常是一个 JSON 文件结构类似{ mcpServers: { time-server: { command: python, args: [/absolute/path/to/mcp_time_server.py], env: {} } } }注册完成后重启 Claude Code 的会话让配置重新加载。然后在对话中询问“现在几点”如果配置正确工具调用会出现在执行链路中。这里最容易踩的坑是路径问题。command和args中的路径必须写绝对路径否则 Claude Code 启动子进程时找不到脚本文件。如果 Python 环境是虚拟环境command也要指向虚拟环境内的 Python 可执行文件而不是裸python否则可能因为包没装全而启动失败。6.3 在 Claude Code 中使用 DeepSeek 的注意事项接入 DeepSeek 时如果出现类似“某个模型名不是当前版本 Claude Code 能识别的模型”的错误需要按下面的顺序排查确认模型名是否与 DeepSeek 控制台开放的模型名一致。确认环境变量是否在 Claude Code 启动前已经设置例如 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL。确认当前 Claude Code 版本是否支持自定义模型网关地址。如果 Claude Code 只接受内置模型名可以考虑在 LangChain 侧使用 DeepSeek而 Claude Code 只负责作为 MCP Client 消费工具。不要把“模型能在 LangChain 里调用成功”和“模型能在 Claude Code 里用同样名字调用成功”画等号。不同工具有不同的模型白名单和配置入口报错时要按工具自身文档排查。6.4 验证结果与错误定位注册完成后建议先做一次不依赖模型的工具测试也就是直接通过 MCP Inspector 连接mcp_time_server.py确认 Server 能输出工具列表。然后再回到 Claude Code 中测试对话。如果 Claude Code 中看不到自定义 MCP 工具优先检查配置文件路径和 JSON 格式。如果看到工具但调用失败优先查看 Claude Code 的日志输出确认是子进程启动失败、协议解析失败还是参数传错。这类问题通常和 LangChain 集成无关是 MCP 传输层的通用问题。7. 排错清单与常见坑7.1 MCP 连接失败现象Agent 启动时报错提示无法连接 MCP Server。排查步骤手工在终端执行python mcp_time_server.py确认脚本不会立刻退出。使用mcp dev mcp_time_server.py打开调试面板确认工具列表可见。检查StdioServerParameters中的 command 和 args 是否写对。检查 Python 解释器是否使用虚拟环境里的那个。确认项目中没有任何print输出到 stdout。7.2 Agent 工具调用超时现象模型已经生成 tool_call但 Agent 长时间不返回最后提示the agent execution provider did not respond in time或类似超时信息。这种报错提示“执行提供方没有及时响应”常见原因不是模型服务而是工具执行链路没有及时完成。重点检查MCP Server 启动时是否因为缺少依赖而卡住。工具函数内部是否有阻塞操作比如网络请求没有设置超时。Agent 是否尝试调用一个返回超大结果的工具。模型服务本身响应慢导致整个 ReAct 循环多次等待。建议在工具函数内部给外部调用设置超时例如使用httpx时配置timeout数据库查询设置语句超时。同时在 Agent 外层设置整体超时避免单次请求无限等待。7.3 模型不支持 function calling现象模型返回一段文字而不是结构化 tool_callAgent 永远不会调用工具。可能原因模型版本不支持工具调用。使用的模型名指向了不支持 function calling 的模型。工具 Schema 格式不符合模型要求。检查方式是直接打印工具列表和模型输出。先让模型接收一个带工具列表的请求观察response中是否包含tool_calls字段。如果模型始终不输出该字段需要更换支持工具调用的模型或检查base_url是否正确。7.4 环境变量未传递现象本地运行正常但通过 Claude Code 或其他进程启动 MCP Server 后工具内部读取不到 DEEPSEEK_API_KEY 等环境变量。原因通常是子进程没有继承父进程的环境。MCP Server 子进程是 Agent 进程启动的Agent 进程本身需要有这些变量。如果 Agent 由 Claude Code 启动那么变量需要在 Claude Code 的启动环境中设置而不仅是在某个终端窗口里 export。处理方式是在 MCP Server 配置的env字段中显式传入{ mcpServers: { time-server: { command: /path/.venv/bin/python, args: [/path/mcp_time_server.py], env: { DEEPSEEK_API_KEY: your-key } } } }也可以让 MCP Server 内部从独立配置文件读取密钥但要注意不要把密钥提交到版本库。7.5 工具结果太长导致模型生成错误现象工具返回大量内容模型生成答案时重复或截断。工具设计时应遵循“返回精炼状态优先”原则。比如数据库查询工具返回前 50 行并在文本中补充总行数文件读取工具限制读取大小搜索工具只返回标题和摘要。模型上下文是有限的把原始数据全部塞进上下文既浪费 token也容易让模型抓不住重点。8. 生产环境建议与扩展方向8.1 从 demo 到生产需要的改动当前代码已经能跑通原理但直接用于生产风险较高。生产环境至少需要补上以下能力配置外置化API Key、模型名、MCP Server 地址全部放到配置中心或环境变量管理平台不允许写死在代码里。日志与监控记录每次 Agent 请求的模型名、工具名、参数、返回结果、耗时、错误类型。超时控制给模型调用、工具调用、整个 Agent 执行分别设置超时。审计与权限哪些用户能调用哪些工具工具执行前是否需要审批都需要单独设计。回滚方案如果新模型或新工具出现问题能迅速切换回旧版本。下面的表格总结了学习和生产环境的关键差异关注点本地学习环境生产环境密钥管理.env 文件配置中心或密钥管理平台日志终端 print结构化日志 全链路追踪超时不设置模型、工具、总链路分别设置工具权限所有人可调按角色和场景控制MCP Server 部署本机 stdio远程 HTTP 服务或容器化部署上下文长度不限制设定最大消息数和 token 上限8.2 安全检查与权限控制MCP 工具一旦接入 Agent就相当于给模型开放了一组“可执行操作”。工具越强风险越高。一个能执行任意表达式的计算工具在本地学习没问题生产上就是严重漏洞。生产环境应该对工具入参做白名单校验而不是直接传给 Python 内置函数。所有涉及写入、删除、发送消息的工具增加二次确认或权限校验。记录工具调用的用户、会话、参数、结果便于审计。对工具返回内容做脱敏处理避免把密钥、手机号等敏感信息返回给模型。8.3 下一步可以做什么跑通最小案例后可以朝几个方向继续深入多 MCP Server 集成用 MultiServerMCPClient 同时加载数据库工具、搜索工具、文档工具。LangGraph 高级流程实现子图、并行分支、人工确认节点、循环检测。Agent 记忆增强把历史工具调用结果持久化支持跨会话复用。评估与测试构造一组固定问题自动验证 Agent 是否在应该调用工具时调用工具并在工具失败时给出合理回答。RAG 与 MCP 结合把向量检索包装成 MCP 工具让 Agent 具备查找私有知识库的能力。实际项目里最值得关注的一点是不要一开始就追求工具数量多而是先把两三个工具的调用链路跑稳再把控制逻辑从黑盒循环切到 LangGraph。工具接入标准化之后扩展新能力只是增加一个 MCP Server 的事。 LangChain结合MCP开发Agent工具：从原理到实践指南
在实际的 AI Agent 开发中真正让人卡住的往往不是大模型 API 怎么调而是 Agent 如何安全、稳定、可复用地把外部工具接进来。LangChain 提供了模型、工具、记忆和编排的抽象MCPModel Context Protocol则统一了工具暴露和调用的协议LangGraph 又进一步把“调几次模型、什么时候调用工具、调用哪个工具”变成了可控制的图执行流程。这篇文章围绕“LangChain 结合 MCP 完成 Agent 工具开发”这一条主线从原理、环境、代码到排错带你把一个最小可运行的 Agent 工具项目从零搭起来并说明如何接入 DeepSeek 模型、如何在 Claude Code 中注册 MCP Server。文章适合已经写过基础 Python 和简单大模型 API 调用、但还没有系统接触 Agent 和工具协议的开发者。最终你会得到一个可运行的 MCP Server、一个能自己决定是否调用工具的 LangChain Agent以及一个用 LangGraph 实现的多轮工具调用案例。过程中会给出环境依赖、代码片段、验证命令、常见报错和排查清单方便之后迁移到自己业务中。1. 先理清 Agent、MCP、LangChain 和 LangGraph 之间的关系1.1 Agent 到底在解决什么问题普通的大模型应用是一次性问答用户输入一句话模型直接输出一段文本。它的限制在于模型训练数据有截止时间也不具备访问实时数据、读写外部系统、执行计算或操作业务系统的能力。Agent 的思路是让模型不再是“直接输出答案”而是“输出行动计划”由程序去执行工具调用把工具结果返回给模型再由模型生成最终回答。这里的关键是“决策循环”。模型要判断这个问题需不需要查时间需不需要算公式需不需要调用数据库如果不需要就直接回答如果需要就生成一个工具调用请求。程序拿到请求后执行真实函数把结果拼进对话上下文继续交给模型推理。这样一个“思考-调用-观察-再思考”的过程就是 ReAct 模式。在代码层面Agent 通常由三部分组成大模型、工具列表、执行循环。大模型负责生成自然语言和结构化工具调用参数工具列表告诉模型有哪些能力可用执行循环负责把模型输出的工具调用翻译成真实函数调用并把结果回填。1.2 MCP 解决了工具接入的什么问题在没有 MCP 之前每个 Agent 项目接入新工具通常要写一层自定义封装。比如给模型加一个天气工具需要自己定义 JSON Schema、自己实现调用入口、自己处理鉴权和错误返回。工具一多接口风格就会混乱而且不同框架之间很难复用。MCP 出现后工具提供方只需要按统一协议暴露工具Agent 端按统一客户端去连接和发现工具就能拿到工具描述和调用入口。MCP 采用客户端-服务端模型。MCP Server 负责暴露工具、提示词和资源MCP Client 负责连接 Server 并获取可用工具。传输方式上本地开发常用 stdio也就是 Agent 通过启动一个子进程与 Server 通信远程部署还可以使用 Streamable HTTP 等方式。在 Agent 项目里MCP 的价值不是让模型更聪明而是让工具接入变得标准化工具能力由独立 Server 维护Agent 只需要关心“连接到哪个 Server、拿到哪些工具”。1.3 LangChain 与 LangGraph 的关系LangChain 是一套面向大模型应用的组件库包含模型封装、Prompt 模板、输出解析、向量存储、工具抽象、记忆等模块。它的定位是“提供构建块”开发者可以用它快速拼装一个 Agent。LangGraph 是建立在 LangChain 组件之上的低层编排框架。它把 Agent 的执行过程建模成一张图节点代表一段逻辑比如调用模型、调用工具、检查状态边代表流转关系。相比 LangChain 早期 AgentExecutor 那种黑盒循环LangGraph 能让你看到每一步的状态变化也能显式控制条件路由、分支、循环和子图。一个简单的区分方式LangChain 更适合快速调用模型和处理组件LangGraph 更适合需要精确控制的 Agent 流程。实际项目可以把两者混用用 LangChain 的模型和工具抽象用 LangGraph 控制执行图。这篇文章后面的代码也是这个组合。1.4 一次完整的 Agent 调用链路一个基于 LangChain MCP 的 Agent 请求内部通常按下面这条链路执行用户输入消息进入 Agent。Agent 读取当前可用的 MCP 工具列表工具列表包含工具名称、描述、参数 Schema。模型根据用户问题决定是否调用工具如果调用则输出结构化 tool_call。LangChain 的工具执行器根据 tool_call 中的名称和参数调用对应 MCP 工具。MCP Client 把调用请求发送给 MCP ServerServer 执行真实逻辑并返回结果。工具结果作为新消息继续传给模型。模型基于工具结果生成最终答案。这条链路里最容易出题的点是第四步和第五步的衔接。工具名称不匹配、参数格式传错、Server 启动失败、返回值太长、模型不支持 function calling都会导致 Agent 卡住或报错。2. 环境准备与依赖对齐避免后面每一步都踩版本坑2.1 Python 版本与虚拟环境MCP Python SDK 和 LangChain 生态对 Python 版本有要求推荐使用 Python 3.10 以上。这里强调版本是因为 MCP 的异步通信、类型注解和部分依赖需要较新的解释器支持。项目根目录下执行mkdir langchain-mcp-agent cd langchain-mcp-agent python -m venv .venv source .venv/bin/activateWindows 下激活命令是.venv\Scripts\activate每一步完成后都可以用python --version确认当前解释器。不要在基础环境里直接安装一堆包否则不同项目之间很容易出现依赖冲突。2.2 安装依赖包先把核心依赖装好。由于 MCP、LangChain 和 LangGraph 的版本更新比较频繁下面的包名以当前主流写法为例实际安装时以官方最新的稳定版本为准。pip install --upgrade pip pip install mcp[cli] pip install langchain langchain-openai langgraph langchain-mcp-adapters如果使用 DeepSeek 模型需要安装langchain-openai因为 DeepSeek 的 API 是 OpenAI 兼容格式。安装完成后可以查看关键包版本pip show mcp langchain langchain-openai langgraph langchain-mcp-adapters这里特别说明不要只安装langchain就以为万事大吉。langchain-mcp-adapters负责把 MCP 工具转成 LangChain 工具langgraph负责提供 Agent 执行循环缺少任何一个后面都会在 import 时报错。2.3 DeepSeek 模型配置DeepSeek 通过 OpenAI 兼容接口提供模型服务。使用前需要在 DeepSeek 开放平台申请 API Key。为了避免 API Key 写死在代码里推荐使用环境变量export DEEPSEEK_API_KEY你的key export DEEPSEEK_BASE_URLhttps://api.deepseek.com/v1 export DEEPSEEK_MODELdeepseek-chatWindows PowerShell 下使用$env:DEEPSEEK_API_KEY你的key $env:DEEPSEEK_BASE_URLhttps://api.deepseek.com/v1 $env:DEEPSEEK_MODELdeepseek-chat选择模型名时要注意不同时段开放的模型名可能不同最新模型名要以平台控制台为准。工具调用场景建议选择支持 function calling 的模型并在测试前确认模型名正确。如果模型名写错通常会在请求阶段直接返回 401 或 400 错误。2.4 项目结构与凭证管理这个最小项目建议按下面的结构组织langchain-mcp-agent/ ├── .venv/ ├── .env ├── mcp_time_server.py ├── agent_langchain.py └── agent_langgraph.py.env文件只保存本地配置不要提交到 Git。Python 代码中加载.env可以直接使用python-dotenv也可以手动读取。更稳妥的做法是使用os.environ.get并在缺失时给出明确错误提示。import os from dotenv import load_dotenv load_dotenv() api_key os.environ.get(DEEPSEEK_API_KEY) if not api_key: raise ValueError(缺少 DEEPSEEK_API_KEY请检查 .env 文件)这样做的原因是模型调用报错时第一优先排查的不是代码逻辑而是环境变量是否真的被读到。3. 从零实现一个 MCP Server让 Agent 拥有第一个工具3.1 为什么先写 MCP Server 而不是直接写 Agent如果把 Agent 先写出来再临时去接工具代码会写得很乱例如在 Agent 执行循环里直接塞 if-else 判断。MCP 的设计思路是先把工具独立出来Agent 端通过协议发现工具。因此先写 Server能让你在完全不依赖大模型的情况下先验证工具本身可用再逐步接入模型。这一节实现一个非常简单的 MCP Server暴露两个工具一个是获取当前时间一个是做简单四则运算。这样不需要申请任何外部 API本地就能验证完整链路。3.2 用 FastMCP 实现一个 ServerMCP Python SDK 提供了FastMCP。它的写法类似 FastAPI用装饰器就能暴露工具。下面代码保存为mcp_time_server.pyfrom datetime import datetime from mcp.server.fastmcp import FastMCP mcp FastMCP(demo-time-server) mcp.tool() def get_current_time(timezone: str local) - str: 获取当前时间。timezone 目前只支持 local返回本地服务器时间。 if timezone ! local: return f当前版本仅支持 local无法处理 {timezone} return datetime.now().isoformat() mcp.tool() def calculator(expression: str) - str: 对简单的四则运算表达式求值例如 1 2 * 3。 allowed set(0123456789-*/(). ) if any(c not in allowed for c in expression): return 表达式包含非法字符 try: result eval(expression, {__builtins__: {}}, {}) return str(result) except Exception as exc: return f计算失败: {exc} if __name__ __main__: mcp.run(transportstdio)这里需要注意几个工程点。get_current_time用一个简单字符串参数演示工具入参传递calculator使用了eval仅用于本地学习示例生产环境绝对不要直接eval用户输入应该换成表达式解析库或只做有限规则校验。真正落地时工具内部还要补充日志、异常分类、超时控制和返回长度限制。3.3 配置 stdio 传输方式上面代码最后一行已经指定了transportstdio。stdio 模式下的工作方式是Agent 端启动一个 Python 子进程执行mcp_time_server.pyMCP SDK 通过标准输入和标准输出与子进程通信。因此这个文件不要写任何无关的print输出否则 print 内容会混入 MCP 协议消息导致客户端解析失败。调试时如果需要打印日志应使用logging模块并输出到 stderr 或文件import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(mcp-time-server) logger.info(server starting)标准输出保留给 MCP 协议标准错误和日志文件用于开发排查。3.4 启动并验证 MCP Server可以直接用 MCP CLI 检查 Server 是否能列出工具。安装mcp[cli]后在项目目录执行mcp dev mcp_time_server.py在打开的调试页面里可以看到暴露出的get_current_time和calculator。也可以使用命令行方式做一次快速检查python mcp_time_server.py这个命令会阻塞因为它正在等待 stdio 输入。看到进程不退出说明 Server 脚本本身没有语法错误。更规范的验证方式是用 MCP Inspector 或写一个临时客户端去连接 Server 并列出工具。这一步通过后可以确认工具层是完好的接下来再写 Agent。4. 使用 LangChain 接入 MCP 工具并跑通第一个 Agent4.1 加载 MCP 工具LangChain 通过langchain-mcp-adapters提供 MCP 工具到 LangChain 工具的转换能力。加载工具前需要先建立 MCP 客户端会话。下面是加载单个 MCP Server 工具的示例使用异步方式import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools async def load_tools(): server_params StdioServerParameters( commandpython, args[mcp_time_server.py], cwd., ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: tools await load_mcp_tools(session) for tool in tools: print(tool.name, tool.description) return tools if __name__ __main__: asyncio.run(load_tools())关键点有两个StdioServerParameters中的command和args要能和命令行启动方式对应整个客户端生命周期要放在async with中确保退出时子进程被正确关闭。如果项目要接入多个 MCP Server可以使用MultiServerMCPClient它允许在一个 Agent 里同时连接时间服务、数据库服务、搜索服务等from langchain_mcp_adapters.client import MultiServerMCPClient client MultiServerMCPClient( { time: { command: python, args: [mcp_time_server.py], transport: stdio, } } )具体使用方式与当前版本的langchain-mcp-adapters有关项目落地前建议查看该库的 README确认是同步还是异步用法。4.2 创建调用 DeepSeek 模型的 Agent有了工具列表后创建 Agent 就变得简单。先创建模型实例再通过create_react_agent组装模型和工具。下面是完整的agent_langchain.pyimport asyncio import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools load_dotenv() def build_llm(): return ChatOpenAI( modelos.getenv(DEEPSEEK_MODEL, deepseek-chat), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com/v1), api_keyos.getenv(DEEPSEEK_API_KEY), temperature0, ) async def main(): llm build_llm() server_params StdioServerParameters( commandpython, args[mcp_time_server.py], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: tools await load_mcp_tools(session) agent create_react_agent(llm, tools) result await agent.ainvoke({ messages: [{role: user, content: 现在几点了}] }) print(result[messages][-1].content) if __name__ __main__: asyncio.run(main())这段代码的核心是create_react_agent。它内部已经实现了 ReAct 循环模型输出工具调用 - 工具执行 - 结果返回模型。不需要自己写 while 循环。temperature0是工具调用场景的常用配置因为工具调用需要确定性而不是创造性。4.3 运行 Agent 并观察工具调用日志执行python agent_langchain.py如果一切正常控制台会输出类似“当前时间是 2026-xx-xxTxx:xx:xx”的结果。如果希望看到模型内部思考过程可以给模型实例开启 verbosellm ChatOpenAI( ..., verboseTrue, )更多日志可以通过langchain的调试模式开启export LANGCHAIN_TRACING_V2false export LANGCHAIN_DEBUGtrue在开发环境打开调试日志能直观看到模型有没有生成 tool_call、工具名称是什么、工具返回了什么。这是排查 Agent 问题最有效的方式。4.4 常见错误工具返回格式、超时和默认值运行过程中最常见的三类问题如下。第一模型没有生成工具调用。可能原因模型本身不支持 function calling或者 Prompt 中没有足够的工具说明。这时候先确认tools非空再确认模型实例没有写错模型名。可以先单独用模型问一个必须查时间的问题观察返回内容。第二工具返回内容异常。MCP 工具返回值会被直接塞进模型上下文如果返回超大正文或包含大量特殊字符模型可能无法生成正确回答。工具内应尽量返回精简文本并截断长内容。第三Agent 等待工具执行超时。MCP Server 启动很慢、脚本路径错误、Python 解释器路径不对都会导致工具调用迟迟没有结果。排查方法是在StdioServerParameters中确认command使用的是虚拟环境里的 Python 绝对路径which python如果项目使用的是.venv需要把 command 写成command/path/to/project/.venv/bin/pythonWindows 下使用类似commandC:\\path\\to\\project\\.venv\\Scripts\\python.exe5. 用 LangGraph 实现多步 Agent条件路由与记忆5.1 为什么单轮 Agent 不够用create_react_agent已经覆盖了“调用工具-回填-再回答”的基本循环但它内部是一条固定链路。真实业务往往有更复杂的要求模型判断结果不满足条件时应该继续调用另一个工具而不是直接结束。用户多轮对话中工具结果需要和历史消息一起参与推理。某些分支需要并行执行多个工具某些分支需要进入子图处理。LangGraph 把流程拆成节点和边开发者可以控制每一步。下面实现一个最小示例模型节点负责生成回答或工具调用工具节点负责执行 MCP 工具条件边根据模型结果决定是继续调用工具还是结束。5.2 节点、边与状态先定义 Agent 状态。状态会在每个节点间传递这里使用messages字段保存对话历史from typing import Annotated, TypedDict from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages]Annotated[list, add_messages]表示每次更新消息时使用add_messages合并策略。这样每个节点返回的新消息会自动追加到历史列表而不是覆盖旧消息。模型节点和执行工具节点的代码如下from langchain_core.messages import AIMessage, ToolMessage def call_model(state: AgentState, config): messages state[messages] response llm_with_tools.invoke(messages, config) return {messages: [response]} def call_tool(state: AgentState): last_message state[messages][-1] tool_calls last_message.tool_calls results [] for tool_call in tool_calls: tool_result tools_by_name[tool_call[name]].invoke(tool_call[args]) results.append(ToolMessage(contenttool_result, tool_call_idtool_call[id])) return {messages: results}这里的tools_by_name是从 MCP 加载出的工具列表转换成的字典方便按名称查找。5.3 加入条件路由和工具循环条件路由函数判断模型输出中是否存在工具调用def should_continue(state: AgentState): last_message state[messages][-1] if hasattr(last_message, tool_calls) and len(last_message.tool_calls) 0: return continue return end然后构建图from langgraph.graph import StateGraph, START, END graph StateGraph(AgentState) graph.add_node(agent, call_model) graph.add_node(tools, call_tool) graph.add_edge(START, agent) graph.add_conditional_edges( agent, should_continue, {continue: tools, end: END}, ) graph.add_edge(tools, agent) app graph.compile()这段图表达的含义是从 START 进入 agent 节点agent 节点如果返回工具调用就进入 tools 节点执行tools 节点执行完回到 agent如果 agent 节点没有工具调用就直接结束。工具执行结果会作为新的消息传递给模型这样模型能基于最新结果继续推理。5.4 运行与结果验证把图构建逻辑封装到agent_langgraph.py然后执行async def run(): ... result await app.ainvoke({ messages: [{role: user, content: 先计算 123 * 456再告诉我当前时间}] }) for message in result[messages]: print(message.type, str(message.content)[:200])如果图流程正确输出中应该能看到 AIMessage、ToolMessage、再 AIMessage 的交替序列。这也是一种验证方式观察消息类型序列是否符合预期。LangGraph 的优势在这一步体现出来。如果想要在模型判断某个条件后进入不同分支只需要修改条件边的映射如果想要把一组节点封装成子图可以在父图节点中调用子图如果想要并行执行多个工具可以把tools节点改成并行调用。执行流程变成可控制、可测试的状态图而不是黑盒循环。6. 在 Claude Code 中注册 MCP Server并接入 DeepSeek6.1 Claude Code 是什么场景Claude Code 是一个终端环境里的 AI 编程助手类工具它也能通过 MCP 协议使用外部工具。把前面写好的 MCP Server 注册到 Claude Code 后就可以在对话中直接触发 get_current_time、calculator 这类工具。这里关注的不是如何安装 Claude Code而是如何把自定义 MCP Server 接入到现有工具流程中。需要注意Claude Code 对模型名和版本的管理比较严格。如果你通过配置方式接入 DeepSeek 或其他 OpenAI 兼容模型模型名必须是该环境下能识别的名称。社区中把 DeepSeek 接入 Claude Code 的做法通常是通过环境变量指定 API 地址和模型名但具体是否被当前版本支持需要以官方文档和实际运行结果为准。6.2 注册 MCP Server 配置文件Claude Code 支持在配置中增加 MCP Server。配置文件通常是一个 JSON 文件结构类似{ mcpServers: { time-server: { command: python, args: [/absolute/path/to/mcp_time_server.py], env: {} } } }注册完成后重启 Claude Code 的会话让配置重新加载。然后在对话中询问“现在几点”如果配置正确工具调用会出现在执行链路中。这里最容易踩的坑是路径问题。command和args中的路径必须写绝对路径否则 Claude Code 启动子进程时找不到脚本文件。如果 Python 环境是虚拟环境command也要指向虚拟环境内的 Python 可执行文件而不是裸python否则可能因为包没装全而启动失败。6.3 在 Claude Code 中使用 DeepSeek 的注意事项接入 DeepSeek 时如果出现类似“某个模型名不是当前版本 Claude Code 能识别的模型”的错误需要按下面的顺序排查确认模型名是否与 DeepSeek 控制台开放的模型名一致。确认环境变量是否在 Claude Code 启动前已经设置例如 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL。确认当前 Claude Code 版本是否支持自定义模型网关地址。如果 Claude Code 只接受内置模型名可以考虑在 LangChain 侧使用 DeepSeek而 Claude Code 只负责作为 MCP Client 消费工具。不要把“模型能在 LangChain 里调用成功”和“模型能在 Claude Code 里用同样名字调用成功”画等号。不同工具有不同的模型白名单和配置入口报错时要按工具自身文档排查。6.4 验证结果与错误定位注册完成后建议先做一次不依赖模型的工具测试也就是直接通过 MCP Inspector 连接mcp_time_server.py确认 Server 能输出工具列表。然后再回到 Claude Code 中测试对话。如果 Claude Code 中看不到自定义 MCP 工具优先检查配置文件路径和 JSON 格式。如果看到工具但调用失败优先查看 Claude Code 的日志输出确认是子进程启动失败、协议解析失败还是参数传错。这类问题通常和 LangChain 集成无关是 MCP 传输层的通用问题。7. 排错清单与常见坑7.1 MCP 连接失败现象Agent 启动时报错提示无法连接 MCP Server。排查步骤手工在终端执行python mcp_time_server.py确认脚本不会立刻退出。使用mcp dev mcp_time_server.py打开调试面板确认工具列表可见。检查StdioServerParameters中的 command 和 args 是否写对。检查 Python 解释器是否使用虚拟环境里的那个。确认项目中没有任何print输出到 stdout。7.2 Agent 工具调用超时现象模型已经生成 tool_call但 Agent 长时间不返回最后提示the agent execution provider did not respond in time或类似超时信息。这种报错提示“执行提供方没有及时响应”常见原因不是模型服务而是工具执行链路没有及时完成。重点检查MCP Server 启动时是否因为缺少依赖而卡住。工具函数内部是否有阻塞操作比如网络请求没有设置超时。Agent 是否尝试调用一个返回超大结果的工具。模型服务本身响应慢导致整个 ReAct 循环多次等待。建议在工具函数内部给外部调用设置超时例如使用httpx时配置timeout数据库查询设置语句超时。同时在 Agent 外层设置整体超时避免单次请求无限等待。7.3 模型不支持 function calling现象模型返回一段文字而不是结构化 tool_callAgent 永远不会调用工具。可能原因模型版本不支持工具调用。使用的模型名指向了不支持 function calling 的模型。工具 Schema 格式不符合模型要求。检查方式是直接打印工具列表和模型输出。先让模型接收一个带工具列表的请求观察response中是否包含tool_calls字段。如果模型始终不输出该字段需要更换支持工具调用的模型或检查base_url是否正确。7.4 环境变量未传递现象本地运行正常但通过 Claude Code 或其他进程启动 MCP Server 后工具内部读取不到 DEEPSEEK_API_KEY 等环境变量。原因通常是子进程没有继承父进程的环境。MCP Server 子进程是 Agent 进程启动的Agent 进程本身需要有这些变量。如果 Agent 由 Claude Code 启动那么变量需要在 Claude Code 的启动环境中设置而不仅是在某个终端窗口里 export。处理方式是在 MCP Server 配置的env字段中显式传入{ mcpServers: { time-server: { command: /path/.venv/bin/python, args: [/path/mcp_time_server.py], env: { DEEPSEEK_API_KEY: your-key } } } }也可以让 MCP Server 内部从独立配置文件读取密钥但要注意不要把密钥提交到版本库。7.5 工具结果太长导致模型生成错误现象工具返回大量内容模型生成答案时重复或截断。工具设计时应遵循“返回精炼状态优先”原则。比如数据库查询工具返回前 50 行并在文本中补充总行数文件读取工具限制读取大小搜索工具只返回标题和摘要。模型上下文是有限的把原始数据全部塞进上下文既浪费 token也容易让模型抓不住重点。8. 生产环境建议与扩展方向8.1 从 demo 到生产需要的改动当前代码已经能跑通原理但直接用于生产风险较高。生产环境至少需要补上以下能力配置外置化API Key、模型名、MCP Server 地址全部放到配置中心或环境变量管理平台不允许写死在代码里。日志与监控记录每次 Agent 请求的模型名、工具名、参数、返回结果、耗时、错误类型。超时控制给模型调用、工具调用、整个 Agent 执行分别设置超时。审计与权限哪些用户能调用哪些工具工具执行前是否需要审批都需要单独设计。回滚方案如果新模型或新工具出现问题能迅速切换回旧版本。下面的表格总结了学习和生产环境的关键差异关注点本地学习环境生产环境密钥管理.env 文件配置中心或密钥管理平台日志终端 print结构化日志 全链路追踪超时不设置模型、工具、总链路分别设置工具权限所有人可调按角色和场景控制MCP Server 部署本机 stdio远程 HTTP 服务或容器化部署上下文长度不限制设定最大消息数和 token 上限8.2 安全检查与权限控制MCP 工具一旦接入 Agent就相当于给模型开放了一组“可执行操作”。工具越强风险越高。一个能执行任意表达式的计算工具在本地学习没问题生产上就是严重漏洞。生产环境应该对工具入参做白名单校验而不是直接传给 Python 内置函数。所有涉及写入、删除、发送消息的工具增加二次确认或权限校验。记录工具调用的用户、会话、参数、结果便于审计。对工具返回内容做脱敏处理避免把密钥、手机号等敏感信息返回给模型。8.3 下一步可以做什么跑通最小案例后可以朝几个方向继续深入多 MCP Server 集成用 MultiServerMCPClient 同时加载数据库工具、搜索工具、文档工具。LangGraph 高级流程实现子图、并行分支、人工确认节点、循环检测。Agent 记忆增强把历史工具调用结果持久化支持跨会话复用。评估与测试构造一组固定问题自动验证 Agent 是否在应该调用工具时调用工具并在工具失败时给出合理回答。RAG 与 MCP 结合把向量检索包装成 MCP 工具让 Agent 具备查找私有知识库的能力。实际项目里最值得关注的一点是不要一开始就追求工具数量多而是先把两三个工具的调用链路跑稳再把控制逻辑从黑盒循环切到 LangGraph。工具接入标准化之后扩展新能力只是增加一个 MCP Server 的事。