LangChain Agent 接入 MCP 与 Skills：构建可插拔 AI 智能体的核心架构与实践

1. 先搞清楚 LangChain Agent 接入 MCP 和 Skills 到底解决了什么核心问题

如果你正在用 LangChain 开发 AI Agent，大概率遇到过两个头疼的问题：一是想让 Agent 调用外部工具（比如查数据库、操作文件、调用 API）时，得自己写一堆适配代码，流程繁琐且不易复用；二是当你想给 Agent 增加新能力时，要么得改核心逻辑，要么得等社区或官方更新。LangChain Agent 接入MCP和Skills，就是为了解决这两个核心痛点。

简单来说，MCP是一个标准化的“工具接入协议”，它让 Agent 能像插拔 USB 设备一样，动态地发现和使用各种外部工具（Server），而无需修改 Agent 本身的代码。Skills则可以理解为封装好的、更高级的“能力包”或“工作流”，它可能基于一个或多个 MCP 工具，组合成解决特定复杂任务（如数据分析、内容生成）的完整方案。

所以，这个组合带来的最直接价值是：解耦与扩展性。你的 Agent 核心逻辑可以保持稳定，而通过 MCP 接入的工具和 Skills 定义的能力，可以随时增减、替换。这特别适合需要快速迭代、整合多种外部服务的场景，比如企业内部的知识问答助手、自动化流程机器人等。

对于开发者而言，这意味着你不用再重复造轮子去为每个 API 写包装器，也不用担心工具链变动导致 Agent 大改。你只需要关注 Agent 的“大脑”（LLM 的提示词和推理逻辑），而“手脚”（工具）和“技能组合”（Skills）可以通过标准协议动态配置。接下来，我会从原理、环境搭建、实战接入和避坑指南四个部分，带你完整走一遍。

2. 理解 MCP 与 Skills 的核心原理：协议层与能力层的分工

在动手之前，必须理清 MCP 和 Skills 各自扮演的角色，以及它们如何与 LangChain Agent 协同工作。很多人容易把它们混为一谈，导致配置时思路混乱。

2.1 MCP：标准化的工具通信协议

MCP的核心思想是定义了一套 Client-Server 通信规范。

• MCP Server： 这是工具的提供方。任何一个能通过 HTTP 或 stdio 对外提供服务的程序，只要按照 MCP 协议格式（通常是 JSON-RPC）暴露工具列表和调用接口，就可以成为一个 MCP Server。例如，一个查询数据库的微服务、一个文件操作脚本，甚至一个调用 Claude API 的封装程序，都可以包装成 MCP Server。
• MCP Client： 这是工具的使用方。LangChain Agent 通过一个 MCP Client 来与一个或多个 MCP Server 通信。Client 负责向 Server 查询“你有什么工具可用”，并在 Agent 决策需要时，按照协议格式调用指定的工具。

这种架构的好处是屏蔽了异构性。无论后端工具是用 Python、Go、Node.js 写的，部署在本地还是远程，只要它遵循 MCP 协议，你的 Agent 就能用统一的方式调用它。这极大地降低了集成成本。

2.2 Skills：面向任务的高级能力封装

如果说 MCP 提供了“原子操作”（如读文件、执行 SQL），那么Skills就是由这些原子操作组合而成的“分子”或“工作流”。一个 Skill 描述了一个解决特定问题所需的一系列步骤、工具调用逻辑和数据处理流程。

例如，一个“生成周报”的 Skill，其内部可能依次调用：

1. MCP Tool A: 从数据库查询本周任务数据。
2. MCP Tool B: 从文件系统读取上周报告模板。
3. 内部逻辑： 将数据填充进模板，并调用 LLM 进行润色总结。
4. MCP Tool C: 将最终报告保存到指定位置，并发送通知。

在 LangChain 的语境下，Skills 可以通过Chain或AgentExecutor来实现，其核心是预定义的提示词（Prompt）和工具调用顺序。它让 Agent 不必每次都从零开始规划如何解决一个复杂问题，而是可以直接启用一个现成的、优化过的解决方案。

2.3 三者协同工作流

一个典型的增强型 Agent 工作流如下：

1. 初始化： LangChain Agent 启动，并加载配置好的 MCP Client。该 Client 连接到若干个 MCP Server（如数据库 Server、文件操作 Server、网络搜索 Server）。
2. 能力发现： Agent 通过 MCP Client 获取所有可用工具的列表和描述。这些描述会被自动整合到给 LLM（如 Claude）的提示词中，告诉 LLM“你现在拥有这些工具”。
3. 任务规划与执行：
   • 对于简单或通用任务，Agent 的 LLM 大脑根据当前对话和工具描述，自主决定调用哪个 MCP 工具。
   • 对于复杂或特定任务，用户可以指示 Agent“使用那个‘生成周报’的 Skill”。Agent 则会转入该 Skill 预定义的工作流，按步骤调用一系列 MCP 工具和 LLM。
4. 结果整合： 工具或 Skill 执行的结果返回给 Agent，Agent 再组织语言回复给用户。

理解了这个分层架构，你在设计系统时就能做出更清晰的决策：什么功能应该下沉为 MCP Tool，什么应该抽象为 Skill。

3. 从零搭建实战环境：以 Claude 为大脑的 Agent 为例

理论清楚了，我们进入实战。我会以一个相对通用的环境为例，演示如何搭建一个以 Claude 模型为推理核心，并能通过 MCP 使用工具和 Skills 的 LangChain Agent。

3.1 基础环境与依赖准备

首先，确保你的开发环境已经就绪。我建议使用 Python 3.10 或以上版本，并创建独立的虚拟环境。

# 创建并激活虚拟环境（以 conda 为例） conda create -n langchain-mcp-demo python=3.10 conda activate langchain-mcp-demo # 安装核心依赖 pip install langchain langchain-community langchain-core

关键点：langchain是主框架，langchain-community包含大量社区贡献的集成（包括很多 MCP 相关组件），langchain-core是核心接口。

接下来，安装 MCP 相关的核心库。目前 LangChain 对 MCP 的支持主要通过langchain-mcp-adapters等包实现，但生态在快速演进。一个更直接的方式是使用mcp客户端库。

# 安装 MCP 客户端库和 Claude SDK pip install mcp anthropic

同时，你需要一个可用的Claude API 密钥。前往 Anthropic 官网注册并获取。将其设置为环境变量：

# Linux/macOS export ANTHROPIC_API_KEY='your-api-key-here' # Windows (PowerShell) $env:ANTHROPIC_API_KEY='your-api-key-here'

3.2 启动你的第一个 MCP Server：一个计算器工具

MCP Server 可以用任何语言编写。为了快速演示，我们用 Python 写一个最简单的“计算器” Server。它提供一个add工具。

创建一个文件calculator_server.py：

# calculator_server.py import asyncio from mcp import Server, stdio import json # 创建 Server 实例 server = Server("calculator-server") # 定义工具 @server.tool() def add(a: float, b: float) -> float: """Add two numbers.""" return a + b # 运行 Server（使用 stdio 传输） async def main(): async with stdio.stdio_server() as (read, write): await server.run(read, write, server.create_initialization_options()) if __name__ == "__main__": asyncio.run(main())

这个 Server 通过标准输入输出（stdio）与 Client 通信，这是本地进程间通信的常见方式。

在另一个终端窗口，运行这个 Server，它会保持运行等待连接：

python calculator_server.py

3.3 构建 LangChain Agent 并连接 MCP

现在，构建我们的 Agent。创建一个agent_demo.py文件：

# agent_demo.py import asyncio import os from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_anthropic import ChatAnthropic from langchain_core.prompts import ChatPromptTemplate from mcp import ClientSession, stdio from langchain_mcp_adapters.tools import MCPTool async def main(): # 1. 初始化 Claude 模型 llm = ChatAnthropic( model="claude-3-5-sonnet-20241022", # 或其他 Claude 3 模型 temperature=0, api_key=os.environ.get("ANTHROPIC_API_KEY") ) # 2. 连接 MCP Server 并创建 LangChain Tool # 启动与 calculator_server.py 的通信 proc = await asyncio.create_subprocess_exec( "python", "calculator_server.py", stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, ) stdio_transport = stdio.StandardIO(proc.stdin, proc.stdout) async with ClientSession(stdio_transport) as session: # 初始化会话，获取工具列表 await session.initialize() # 将 MCP 工具转换为 LangChain 可识别的 Tool 对象 mcp_tools = await MCPTool.from_mcp_client_session(session) # 3. 定义 Agent 的提示词 prompt = ChatPromptTemplate.from_messages([ ("system", "You are a helpful assistant with access to tools. Use them when needed."), ("placeholder", "{chat_history}"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) # 4. 创建 Agent agent = create_tool_calling_agent( llm=llm, tools=mcp_tools, # 传入从 MCP 获取的工具 prompt=prompt, ) # 5. 创建执行器并运行 agent_executor = AgentExecutor(agent=agent, tools=mcp_tools, verbose=True) # 测试：让 Agent 使用计算器 result = await agent_executor.ainvoke({"input": "请计算 123.45 加上 678.9 等于多少？"}) print("\n--- Agent 回复 ---") print(result["output"]) # 可以继续更多对话... # result2 = await agent_executor.ainvoke({"input": "刚才两数之和再乘以 2 是多少？"}, result) if __name__ == "__main__": asyncio.run(main())

关键步骤解析：

1. 初始化 LLM： 使用ChatAnthropic封装 Claude 模型。temperature=0使输出更确定，适合工具调用。
2. 连接 MCP Server： 通过asyncio.create_subprocess_exec启动我们刚才写的计算器 Server 进程，并建立 stdio 通信管道。然后通过MCPTool.from_mcp_client_session这个适配器，将 MCP 协议下的工具自动转换成 LangChainTool对象列表。这是最关键的一步，实现了协议的桥接。
3. 构建 Agent： 使用create_tool_calling_agent（这是 LangChain 新版推荐的方式，比旧的initialize_agent更清晰）来创建 Agent。它将 LLM、工具列表和提示词模板组合在一起。
4. 执行与测试：AgentExecutor负责运行 Agent 的思考-行动循环。设置verbose=True可以看到 Agent 内部调用工具的思考过程。

运行这个脚本：

python agent_demo.py

如果一切正常，你将看到详细的日志，显示 Agent 识别出需要调用add工具，传入参数，得到结果，并最终给出回答。至此，一个最基本的、能通过 MCP 使用外部工具的 LangChain Agent 就跑通了。

4. 进阶应用：集成多 Server、定义 Skills 与生产化考量

基础流程跑通只是第一步。在实际项目中，你需要处理更复杂的情况。

4.1 集成多个 MCP Server 和复杂工具

一个实用的 Agent 往往需要连接多个数据源和服务。你可以同时连接多个 MCP Server。

假设我们还有一个提供“天气查询”的 MCP Server（假设已实现）。我们可以同时连接它和计算器 Server。关键在于管理多个 ClientSession 和工具列表。

# 片段：连接多个 MCP Server async def load_tools_from_servers(): all_tools = [] # 连接计算器 Server calc_proc = await asyncio.create_subprocess_exec(...) # 同上 calc_transport = stdio.StandardIO(calc_proc.stdin, calc_proc.stdout) async with ClientSession(calc_transport) as calc_session: await calc_session.initialize() calc_tools = await MCPTool.from_mcp_client_session(calc_session) all_tools.extend(calc_tools) # 注意：这里 session 不能立即关闭，需要在整个 Agent 生命周期内保持 # 实际项目中需要更精细的生命周期管理 # 连接天气 Server (假设通过 HTTP) # 有些 MCP Server 可能通过 HTTP 而非 stdio 暴露，需要使用对应的客户端连接方式 # async with ClientSession(http_transport) as weather_session: # ... return all_tools # 然后将 all_tools 传入 create_tool_calling_agent

避坑点：工具命名冲突。如果两个 Server 都提供了同名工具，需要在 LangChain 层面进行重命名或命名空间隔离，避免 Agent 混淆。

4.2 将常用工作流封装为 Skills

当某些任务模式固定时，将其封装为 Skill 能大幅提升效率和可靠性。在 LangChain 中，Skill 通常就是一个预设好提示词和工具调用逻辑的Chain。

例如，封装一个“获取天气并给出穿衣建议”的 Skill：

from langchain.chains import LLMChain from langchain.prompts import PromptTemplate # 假设我们已经有一个叫 `get_weather` 的 MCP Tool class WeatherAdviceSkill: def __init__(self, llm, tools): self.get_weather_tool = next(t for t in tools if t.name == "get_weather") self.llm = llm # 定义 Skill 专用的提示词 self.prompt = PromptTemplate.from_template( """你是一个生活助手。请根据以下天气信息，给出简洁的穿衣和出行建议。 天气信息：{weather_info} 建议：""" ) self.chain = LLMChain(llm=self.llm, prompt=self.prompt) async def run(self, location: str): # 1. 调用 MCP 工具获取原始数据 weather_raw = await self.get_weather_tool.ainvoke({"location": location}) # 2. 将结果交给 LLM 加工成建议 advice = await self.chain.ainvoke({"weather_info": weather_raw}) return advice["text"] # 在 Agent 中，可以这样使用 Skill： # 判断用户意图，如果是问穿衣建议，直接调用 skill.run(location) # 否则，走默认的 Agent 工具调用流程。

更高级的做法是利用LangGraph来编排包含多步判断、循环的复杂 Skills。LangGraph适合定义有状态、多分支的工作流，而简单的线性链用LLMChain或SequentialChain即可。

4.3 生产环境部署的注意事项

在开发环境玩得转，不代表能直接上生产。你需要考虑以下几点：

1. MCP Server 管理：

   • 生命周期： Agent 进程和 MCP Server 进程的生命周期需要妥善管理。通常采用 Supervisor、Docker Compose 或 Kubernetes 来统一管理。
   • 资源隔离： 每个 MCP Server 应有独立的资源限制，避免一个故障 Server 拖垮整个 Agent。
   • 健康检查与重连： 实现 MCP Client 对 Server 的健康检查机制，并在连接断开时尝试重连或故障转移。

2. 工具描述优化：

   • MCP Server 提供的工具描述（description）至关重要，它直接作为提示词的一部分影响 LLM 的选择。描述必须清晰、无歧义、说明输入输出格式。模糊的描述会导致 LLM 错误调用。
   • 示例：差的描述：“处理数据”。好的描述：“根据用户ID查询其最近30天的订单列表，返回一个JSON数组，每个订单包含 order_id, amount, status, create_time 字段。”

3. 错误处理与稳定性：

   • Agent 调用工具可能失败（网络超时、参数错误、服务异常）。需要在AgentExecutor层面或自定义Chain中增加重试、降级和友好的错误信息反馈逻辑。
   • 对工具返回的结果进行有效性校验，避免脏数据导致后续步骤或 LLM 解析出错。

4. 性能与成本：

   • 每次工具调用都涉及 LLM 思考（Claude API 调用），有成本和延迟。对于高频、固定的操作，考虑将其下沉为一个更复杂的 MCP Tool 或 Skill，减少与 LLM 的交互次数。
   • 使用verbose模式调试，但生产环境务必关闭，并接入结构化日志系统（如 JSON Logger），方便监控和追踪每次工具调用。

5. 安全性：

   • MCP Server 可能具有高权限（如数据库写操作、文件删除）。必须在 Server 端实现严格的权限校验和操作审计。
   • 对用户输入传递给工具的参数进行清洗和校验，防止注入攻击。
   • 谨慎暴露工具。不是所有 MCP Server 的工具都需要给每个 Agent 使用。

5. 常见问题排查与调试技巧

即使按照步骤操作，你也可能会遇到问题。以下是几个常见坑点和排查思路。

5.1 Agent 不调用工具，总是直接回答

现象： 你问“计算1+1”，Agent 直接说“1+1等于2”，而不是去调用add工具。排查顺序：

1. 检查工具描述： 这是最常见的原因。打开verbose=True的日志，看 LLM 收到的提示词里是否包含了你的工具描述。描述是否足够清晰？LLM 可能认为它自己就能算，不需要调用工具。尝试将工具描述改得更强制，例如：“你必须使用此工具进行任何数学计算，不可自行心算。”
2. 检查提示词模板： 你的ChatPromptTemplate中是否包含了{agent_scratchpad}这个 placeholder？这是 Agent 记录其思考过程（包括工具调用）所必需的。缺少它会导致 Agent 无法正常工作。
3. 检查 LLM 温度：temperature参数过高可能导致输出随机性太大，不遵循调用工具的指令。在工具调用场景，通常设为 0 或接近 0。
4. 检查工具定义： 通过print(mcp_tools)确认工具列表被正确加载，且每个工具的name和description属性正常。

5.2 连接 MCP Server 失败或超时

现象：ClientSession.initialize()报错或长时间无响应。排查顺序：

1. 确认 Server 进程： 首先确保你的 MCP Server 脚本（如calculator_server.py）正在独立运行，并且没有报错退出。
2. 检查传输方式： 确认 Client 和 Server 使用了相同的传输方式（stdio/HTTP）。示例中是 stdio，确保create_subprocess_exec的命令和路径正确。
3. 查看原始日志： 在 Server 和 Client 代码中增加基础日志，打印出建立连接时收发的原始数据，对照 MCP 协议格式检查。
4. 版本兼容性： 检查mcp客户端和服务器端库的版本是否兼容。协议可能仍在演进中。

5.3 工具调用结果解析错误

现象： Agent 调用了工具，但后续处理结果时出错，或者 LLM 无法理解工具返回的内容。排查顺序：

1. 检查工具返回格式： MCP 工具应返回结构化的数据（如字符串、数字、字典、列表）。如果返回了复杂的 Python 对象，需要先序列化为 JSON 等通用格式。确保返回的数据类型与工具声明的一致。
2. 观察agent_scratchpad： 在verbose日志中，仔细查看agent_scratchpad的内容。它会完整记录“Thought”（LLM 思考）、“Action”（调用哪个工具及参数）、“Observation”（工具返回结果）。观察 “Observation” 是否是你期望的数据。
3. 简化测试： 先绕过 Agent，直接写代码调用MCPTool.ainvoke()，看返回什么。确保工具本身工作正常。

5.4 如何处理需要复杂参数的工具？

有些工具需要复杂的输入对象。MCP 协议和 LangChain 都支持通过 JSON Schema 定义参数。

• 在 MCP Server 定义工具时，使用@server.tool()装饰器并配好参数类型提示，库通常会帮你生成 Schema。
• 在 LangChain 侧，MCPTool会自动获取这个 Schema。LLM 会根据 Schema 来生成调用参数。
• 关键： 确保你的 LLM 模型（如 Claude）具备较强的 JSON 模式理解和生成能力。Claude 3 系列在这方面表现很好。

6. 总结：从原理到生产的实践路径

将 LangChain Agent 与 MCP、Skills 结合，本质上是在构建一个可插拔、可编排的智能体系统。MCP 解决了“能力接入”的标准化问题，Skills 解决了“能力复用与组合”的效率问题。

对于个人开发者或小团队，我建议的实践路径是：

1. 从小处着手： 先像本文示例一样，用一个极简的 MCP Server（如计算器、时间查询）和 Claude 模型，把整个调用链路跑通。理解数据是如何在 Agent、MCP Client、MCP Server 之间流动的。
2. 封装核心工具： 将你业务中最关键、最稳定的数据源或 API 封装成 MCP Server。优先选择“只读”或低风险的操作开始。
3. 设计提示词与工具描述： 这是影响 Agent 表现最关键的“软”因素。花时间精心打磨工具的描述和系统提示词，让 LLM 能准确理解何时以及如何使用工具。
4. 构建初级 Skill： 针对你业务中频率高、步骤固定的任务，尝试将其封装为 Skill。初期可以用简单的LLMChain实现。
5. 引入运维与监控： 在考虑上生产前，务必加入日志、错误处理、超时控制、性能监控等非功能性代码。
6. 考虑复杂编排： 当单个 Agent 或 Chain 无法满足复杂业务流程时，再考虑引入LangGraph进行有状态、多角色的工作流编排。

最后，保持对生态的关注。LangChain 和 MCP 的集成方式、社区提供的现成 Server 和 Skills 都在快速发展。但无论工具如何变化，其核心思想——通过标准化协议解耦智能体的“思考”与“执行”，通过预定义模式提升复杂问题解决效率——将是构建强大、可维护 AI Agent 应用的坚实基础。