MCP与LangChain实战：构建Agent工具调用标准化链路

最近在折腾 AI 应用开发，尤其是 Agent 项目时，我发现自己反复卡在同一个环节：模型能力再强，接不到业务数据、调不动内部工具，就等于建好了发动机却没有传动轴。早期我都是给每个数据源单独写一套调用代码，后来接触了 MCP（Model Context Protocol），整个接入方式被彻底统一了。

这篇文章会把 MCP 的核心概念讲清楚，并基于当前主流的 LangChain 生态，从零搭建一个可以运行的实战项目：写一个 MCP Server，再通过 LangChain Agent 让它自动被大模型调用。文章覆盖环境准备、协议原理、完整代码、常见报错和工程化建议，新手可以照着做，有经验的开发者可以直接跳到实战部分复用。

1. 背景与核心概念

1.1 MCP 到底是什么

MCP 的全称是 Model Context Protocol，翻译过来是“模型上下文协议”。它是由 Anthropic 在 2024 年 11 月开源的一项开放协议，目的是解决大模型与外部数据、工具之间“连接方式混乱”的问题。

有一个很形象的比喻：如果说大模型是一台电脑，那么 MCP 就是这台电脑的 USB-C 接口。在没有 USB-C 之前，键盘用圆口、鼠标用方口、显示器用 HDMI、网线用 RJ45，每个设备要单独配线；而 MCP 做的事情，就是把所有外设统一成一个标准接口。AI 应用只需要实现一次 MCP 客户端，就能连接任意支持 MCP 的服务端。

从专业角度定义，MCP 是一套基于 JSON-RPC 2.0 的通信协议，它定义了 AI 模型获取上下文、调用工具、访问外部资源的标准方式。目前 MCP 已经覆盖了数据库、文件系统、HTTP API、开发工具、设计工具等大量场景。比如 Figma、蓝湖这类设计工具陆续提供了 MCP Server，开发者可以通过自然语言直接操作设计稿的数据；还有很多社区维护的 MCP Server，可以访问搜索接口、读取网页、操作 Git 仓库等。

1.2 MCP 解决了什么问题

在做 AI Agent 开发之前，我们一般用 function calling（函数调用）来让模型调用工具。这个方案本身没问题，但它有一个明显的短板：模型每接一个新工具，就要重新写一遍参数定义、鉴权、协议转换逻辑。

举个具体例子：

• 接入天气 API 时，要把 OpenAPI 文档转换成模型能识别的工具描述；
• 接入内部业务系统时，要封装鉴权和数据映射；
• 接入数据库时，要单独定义 SQL 查询模板。

这些工作一旦超过三个系统，维护成本会急剧上升。更麻烦的是，每个团队、每个框架的工具定义格式都可能不同。你用 LangChain 写了一套 Agent，换到别的框架又要重写。

MCP 的核心价值，就是把这些“连接逻辑”从 AI 应用里剥离出来，放到独立的 Server 端。AI 应用只需要通过一套标准协议去发现工具、调用工具、接收结果。这样带来的好处有四个：

1. 标准化：工具的定义、调用、返回格式统一。
2. 复用性：同一个 MCP Server 可以被 LangChain、Claude Desktop、自研框架等任意客户端复用。
3. 解耦：工具逻辑更新时，改 Server 即可，客户端无需变动。
4. 生态化：社区上有大量现成的 MCP Server，开箱即用。

1.3 MCP 与 Agent、LangChain 的关系

很多初学者分不清这几个概念，我这里用一个分层方式说明：

• LLM（大模型）：负责理解和生成语言，是大脑。
• Agent（智能体）：利用大模型的推理能力，自主决定“下一步调用哪个工具、执行什么动作”，是决策者。
• MCP：提供标准化的工具/数据连接通道，是神经系统。
• LangChain：一个 AI 应用开发框架，负责组装模型、提示词、工具、记忆、编排等组件。

简单说，Agent 是目标，LangChain 是脚手架，MCP 是连接外部世界的通道。三者在实际项目中经常配合使用：LangChain 负责构建 Agent 的执行框架，Agent 通过 MCP Client 连接各种 MCP Server，最终实现“大模型 + 真实业务能力”的闭环。

2. 环境准备与版本说明

2.1 开发环境

本文的实战示例使用 Python，需要准备以下环境：

• 操作系统：Windows 10/11、macOS 或 Linux 均可，本文以 Ubuntu 24.04 为例。
• Python：建议 3.10 及以上版本。
• IDE：VS Code 或其他主流编辑器。
• 大模型 API：任意支持 OpenAI 兼容接口的模型服务，本文示例使用 OpenAI 接口风格的配置。

不同版本的 LangChain 和 MCP SDK 接口可能有差异，项目中所用的版本需要根据你的实际环境调整。我在代码中会标注关键 API 的作用，遇到接口报错时优先检查版本。

2.2 安装依赖

建议先创建独立的虚拟环境，避免依赖冲突：

python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate

然后安装核心依赖：

pip install "mcp[cli]" langchain langchain-mcp-adapters langchain-openai

这里简单解释每个包的作用：

• mcp[cli]：MCP 官方 Python SDK，包含 FastMCP、ClientSession 等核心组件，[cli]会附带调试命令mcp。
• langchain：LangChain 主框架。
• langchain-mcp-adapters：LangChain 官方提供的 MCP 适配层，用于把 MCP 工具转换成 LangChain 可用的工具格式。
• langchain-openai：LangChain 中的 OpenAI 兼容模型接入包。

2.3 项目结构

我们实战项目的目录结构如下：

mcp-langchain-demo/ ├── server.py # MCP Server，提供天气查询工具 ├── client_test.py # 独立 MCP Client，用于验证 Server ├── agent.py # LangChain Agent 集成 MCP 的入口 └── requirements.txt # 依赖清单

3. MCP 协议核心原理拆解

虽然日常开发中我们更多在跟 SDK 打交道，但理解协议本身能帮助你更快排查问题，尤其是跨语言、跨框架联调的时候。

3.1 MCP 的三大核心抽象

MCP 协议定义了三种核心能力，理解这三者就能把握 MCP 的设计意图。

第一是 Tools（工具）。工具是让模型执行动作的接口，比如查询天气、发送邮件、执行 SQL。每个工具都有名称、描述和参数定义。关键点在于：工具是由模型根据用户意图动态选择调用的，所以名称要见名知意，描述要清晰，参数类型要明确。

第二是 Resources（资源）。资源是提供给模型阅读的数据，比如文件内容、数据库记录、API 响应。与工具不同，资源通常不需要“执行”，而是直接作为上下文输入。比如你要让模型分析一份 PDF，就可以把这个 PDF 注册成一个 Resource，模型读取后进行分析。

第三是 Prompts（提示词模板）。它提供了可复用的提示模板，类似于把某个领域的专家指令打包。客户端可以通过prompts/get获取模板，再填充参数生成完整的提示词。

一句话总结：工具负责“动手”，资源负责“喂数据”，提示词负责“教方法”。

3.2 两种主流传输方式

MCP 支持多种传输方式，实际开发中主要接触两种。

stdio（标准输入输出）方式是最简单也最常见的。MCP Server 作为客户端的一个子进程启动，双方通过标准输入 stdin 和标准输出 stdout 进行 JSON-RPC 消息交换。优点是无需网络端口，部署简单，适合本地工具；缺点是 Server 生命周期跟随客户端，不适合跨机器部署。

Streamable HTTP 方式则把 MCP Server 部署成独立的 HTTP 服务，客户端通过 HTTP 请求与其通信。它支持远程调用、身份认证和状态管理，更适合生产环境的多服务部署。

选择建议是：本地实验、开发调试用 stdio 最简单；正式部署、多个客户端共享同一个 Server 时，优先考虑 Streamable HTTP。

3.3 JSON-RPC 消息格式

MCP 基于 JSON-RPC 2.0 通信，所有请求和响应都是 JSON 对象。比如客户端调用get_weather工具时，发送的消息大致如下：

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_weather", "arguments": { "city": "北京" } } }

其中method是协议方法名，params是参数。核心方法包括：

• initialize：客户端与服务端握手，协商协议版本和能力。
• tools/list：获取服务端提供的工具列表。
• tools/call：调用指定工具。
• resources/list：获取资源列表。
• prompts/get：获取提示词模板。

日常使用 SDK 时，这些消息会被封装，但理解结构有助于排查问题。当你看到“method not found”或“connection closed”这类错误时，大概率就是协议握手或传输方式不匹配。

4. 实战：MCP Server + LangChain Agent 完整集成

接下来我们完成一个从零到一的可运行项目。业务场景设定为：Agent 可以查询多个城市的天气，并回答用户关于天气的追问。

4.1 创建项目与依赖清单

先创建项目目录，并准备requirements.txt：

mcp[cli]>=1.2.0 langchain>=0.3.0 langchain-mcp-adapters>=0.1.0 langchain-openai>=0.2.0

然后在终端安装：

pip install -r requirements.txt

如果安装时提示版本冲突，优先把langchain和langchain-mcp-adapters升级到最新稳定版，因为 MCP 适配器的 API 变化较快。

4.2 编写 MCP Server

在server.py中，我们使用 FastMCP 快速定义一个带两个工具的天气服务。

# 文件路径：server.py from mcp.server.fastmcp import FastMCP # 创建 MCP Server 实例，名称会作为服务标识 mcp = FastMCP("WeatherServer") # 模拟天气数据源，实际项目可替换为数据库或外部 API WEATHER_DATA = { "北京": "晴，最高温 26℃，最低温 14℃，东南风 2 级", "上海": "多云，最高温 28℃，最低温 19℃，东风 3 级", "广州": "雷阵雨，最高温 30℃，最低温 24℃，南风 2 级", } @mcp.tool() def get_weather(city: str) -> str: """查询指定城市的实时天气情况。 Args: city: 城市名称，例如：北京、上海、广州 Returns: 该城市的天气描述字符串 """ if city in WEATHER_DATA: return WEATHER_DATA[city] return f"暂未收录 {city} 的天气数据，请确认城市名称后重试。" @mcp.tool() def get_supported_cities() -> list[str]: """获取所有支持天气查询的城市列表。""" return list(WEATHER_DATA.keys()) if __name__ == "__main__": # 默认以 stdio 方式运行 mcp.run()

这里有两个需要注意的细节。

第一，@mcp.tool()装饰器会把被装饰的函数注册成 MCP 工具。函数的文档字符串（docstring）非常重要，因为 LangChain Agent 会把工具描述拼接进系统提示词，让模型知道“什么时候该调用这个工具”。描述写得模糊，模型就会在错误场景调用或者干脆不调用。

第二，参数类型标注必须是具体的类型，比如str、int、float、list等。MCP 会根据类型标注自动生成 JSON Schema，如果用了dict或者Any，工具参数校验会变得不可控。

4.3 用独立 Client 验证 Server

先不急着集成 LangChain，我们要用最底层的 ClientSession 验证 Server 是否正常工作。创建client_test.py：

# 文件路径：client_test.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): # 配置子进程启动参数：python server.py server_params = StdioServerParameters( command="python", args=["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() print("=== 可用工具列表 ===") for tool in tools.tools: print(f"- {tool.name}: {tool.description}") # 调用 get_weather 工具 result = await session.call_tool("get_weather", {"city": "北京"}) print("\n=== 调用 get_weather 结果 ===") print(result.content) if __name__ == "__main__": asyncio.run(main())

运行验证：

python client_test.py

预期输出类似：

=== 可用工具列表 === - get_weather: 查询指定城市的实时天气情况。 - get_supported_cities: 获取所有支持天气查询的城市列表。 === 调用 get_weather 结果 === [TextContent(type='text', text='晴，最高温 26℃，最低温 14℃，东南风 2 级')]

看到工具列表和返回内容，说明 Server 和 Client 之间的通信链路已经打通。

4.4 集成到 LangChain Agent

接下来是关键环节：让 LangChain Agent 自动决定调用 MCP 工具。创建agent.py：

# 文件路径：agent.py import asyncio from langchain.agents import create_agent from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI async def main(): # 注册一个 stdio 类型的 MCP Server async with MultiServerMCPClient( { "weather-server": { "command": "python", "args": ["server.py"], "transport": "stdio", } } ) as client: # 将 MCP 工具转换为 LangChain 工具 tools = client.get_tools() # 初始化大模型 model = ChatOpenAI(model="gpt-4o", temperature=0) # 创建 Agent agent = create_agent(model, tools) # 向 Agent 提问 response = await agent.ainvoke( { "messages": [ { "role": "user", "content": "北京和上海今天天气怎么样？哪个城市更热？", } ] } ) # 输出 Agent 最终回复 print(response["messages"][-1].content) if __name__ == "__main__": asyncio.run(main())

这段代码做了几件事：

1. MultiServerMCPClient是适配层的入口，可以同时注册多个 MCP Server。键名是自定义标识，command、args指定了 Server 的启动方式，transport指定传输类型。
2. client.get_tools()会启动 Server 并读取tools/list，返回一个 LangChain 工具列表。
3. create_agent是 LangChain 新版推荐的 Agent 创建方式，传入模型和工具，框架会自动编排“思考-调用工具-观察结果-再思考”的循环。
4. agent.ainvoke执行对话，内部会自动处理中间的工具调用过程。

如果你的 LangChain 版本较老，使用的可能是initialize_agent或create_tool_calling_agent，建议升级到 0.3 以上并使用create_agent。

4.5 运行与验证

运行 Agent：

python agent.py

模型会经历类似下面的内部过程：

1. 读取用户问题，判断需要查询两个城市的天气。
2. 调用get_weather({"city": "北京"})，得到结果。
3. 调用get_weather({"city": "上海"})，得到结果。
4. 根据两个结果生成回答。

最终输出大致为：

北京今天晴，最高温26℃，最低温14℃；上海多云，最高温28℃，最低温19℃。上海比北京更热。

到这里，你已经完成了一个完整的 MCP + LangChain Agent 集成链路。如果调试时模型没有自动调用工具，可以开启 LangChain 的运行日志，观察中间步骤是否触发了 tools 调用。

5. 进阶：Agent Skill 与 MCP 有什么区别

在最近的 AI 开发讨论中，除了 MCP，Agent Skill 也是一个高频词汇。很多读者问我，它们是不是同一个东西，这里统一说明。

5.1 两者的定位不同

MCP 解决的是“能力连接”问题。它把工具、数据资源从 AI 应用中解耦出来，通过标准化协议让模型调用外部系统。你可以理解为：MCP 是插头和插座的标准，把充电器、显示器、硬盘都接到了电脑上。

Agent Skill 则更侧重“任务过程知识”。一个 Skill 通常是一组指令、代码模板和使用说明的集合，告诉模型“完成某类任务时需要遵循什么步骤、使用什么策略”。它更像是给模型一本操作手册。

举一个区分例子：

• 查询天气并返回结构化 JSON，适合用 MCP Tool 实现，因为这是确定性的对外接口调用。
• 撰写一份季度复盘报告，包含数据提取、分析框架、文风要求，这适合用 Skill 封装，因为过程知识比单纯调用一个接口复杂得多。

5.2 如何选择

在实际项目中，两者的边界并不是互斥的。一个 Skill 内部完全可以通过 MCP 调用外部工具。更合理的做法是：

• 需要对接外部系统、提供可复用能力时，优先做成 MCP Server。
• 需要沉淀特定领域的工作流程、提示策略时，优先做成 Agent Skill。
• 两者结合使用，MCP 提供工具基础，Skill 提供流程引导。

对初学者来说，建议先掌握 MCP，因为它是 AI 应用开发的基础设施。Skill 是更高层的工作流抽象，理解 MCP 之后再学习会顺畅很多。

6. 常见问题与排查思路

在实践 MCP + LangChain 的过程中，下面几个问题出现频率最高。

6.1 子进程启动失败

错误表现为连接直接断开，或提示无法启动python。排查步骤：

python server.py

手动启动如果报错，说明代码有问题；如果正常启动，说明MultiServerMCPClient中的command或args配置与当前环境不符。在 Windows 上，有时需要把command改为python的完整路径，或者使用py命令。

6.2 工具描述不完整导致调用不准确

模型决定是否调用工具，主要依据是工具的名称和描述。建议描述中明确说明“这个工具做什么”“什么场景下使用”“参数含义是什么”。例如：

@mcp.tool() def send_email(to: str, subject: str, body: str) -> str: """向指定收件人发送邮件。仅用于用户明确要求发送邮件时使用。 Args: to: 收件人邮箱地址 subject: 邮件主题 body: 邮件正文内容 """

对比一下，如果描述写成“发送邮件”三个字，模型在邮件相关场景可能不会调用它，因为信息不足以建立关联。

6.3 生产环境的连接不稳定

本地 stdio 方式在服务器上长期运行时，可能会因为进程退出或文件描述符泄露导致连接不稳定。解决方案是把 MCP Server 改造成 Streamable HTTP 模式，作为独立服务运行，客户端通过 URL 连接。改动主要集中在启动代码：

# server.py 的启动部分，按需切换到 HTTP 模式 if __name__ == "__main__": mcp.run(transport="http")

具体参数取决于你所安装的 MCP SDK 版本，修改前先查阅对应版本的文档。

7. 最佳实践与工程建议

7.1 工具设计规范

MCP 工具等同于对外暴露的 API，设计质量直接决定 Agent 的成功率。建议遵循几点：

• 名称采用小写动词 + 名词，例如get_weather、create_ticket。
• 每个工具必须有清晰的 docstring，注明用途、参数含义和返回值。
• 参数尽量使用简单类型，避免深层嵌套结构。
• 返回结果优先使用 JSON 字符串，便于模型解析。
• 一个工具只做一件事，不要写“万能工具”。

7.2 安全与权限边界

这是工程落地中最不能省略的部分。MCP Server 如果连了数据库或内部系统，本质上是把操作权限交给了模型。必须做到：

• 输入校验：对用户传入的参数做严格校验，防止通过工具拼接出恶意命令或 SQL 注入。
• 最小权限：Server 运行账号只授予业务必需权限，不要用管理员账号跑服务。
• 密钥隔离：不要把 API Key、数据库密码硬编码在 Server 代码中，使用环境变量或配置中心管理。
• 操作确认：涉及删除、修改、支付等高危操作时，增加二次确认机制，不要让 Agent 直接执行。

7.3 可观测性与日志

Agent 调用链路长，一旦出问题很难定位。建议在工具函数内外增加结构化日志，记录入参、出参和耗时：

import logging import time logger = logging.getLogger("mcp.tool") def log_tool_call(func_name: str): def decorator(func): def wrapper(*args, **kwargs): start = time.time() logger.info("调用工具 %s, args=%s, kwargs=%s", func_name, args, kwargs) try: result = func(*args, **kwargs) logger.info("工具 %s 返回成功, 耗时 %.2fs", func_name, time.time() - start) return result except Exception as e: logger.error("工具 %s 执行失败: %s", func_name, e, exc_info=True) raise return wrapper return decorator

接入分布式追踪系统后，可以完整看到“用户提问 → 模型决策 → 工具调用 → 返回结果”的链路。

7.4 生产环境注意事项

• 优先使用 Streamable HTTP 部署，而不是 stdio，避免子进程生命周期难以管理的问题。
• 为每个 MCP Server 配置独立的健康检查接口和超时控制。
• 工具调用失败时，返回结构化错误信息而不是抛出未捕获异常，方便模型判断下一步动作。
• 版本升级前，在测试环境跑一遍工具清单遍历和关键调用用例，MCP SDK 迭代速度较快。

8. 总结与学习路线

这篇文章从概念到实战，完整走通了 MCP + LangChain Agent 的集成路线。你现在应该已经掌握：

1. MCP 是什么，以及它如何解决 AI 应用连接外部系统的标准化问题。
2. MCP 的三大核心抽象（工具、资源、提示词）和两种主流传输方式。
3. 使用 FastMCP 编写一个可运行的 MCP Server。
4. 通过 LangChain Agent 自动调用 MCP 工具。
5. MCP 与 Agent Skill 的区别和选型思路。
6. 常见报错的排查方式和工程化建议。

下一步的学习路线，我建议按顺序推进：

• 熟悉 MCP 官方文档中关于 Authorization、Streamable HTTP 服务端部署、Vendoring 等进阶内容。
• 把实战项目升级为 HTTP 模式，体验远程连接与多客户端复用。
• 学习 LangGraph，理解状态机、记忆和复杂工作流编排，它与 LangChain 本体的区别在于：LangChain 适合快速组装链式调用，LangGraph 更适合需要分支、循环和状态持久化的复杂 Agent 场景。
• 尝试对接社区现成的 MCP Server，比如数据库、Git、办公文档类，理解不同 Server 的设计差异。
• 在真实业务里选一个小工具（例如工单查询、报表生成）改造成 MCP Server，推动一次实际的“AI 接入业务系统”。

动手写一个 MCP Server 并不难，难的是把它设计得严谨、安全、可维护。建议你从今天这个天气示例开始，先跑通链路，再逐步加入鉴权、日志和 HTTP 部署，一步步把标准协议转化为工程能力。如果本文对你有帮助，可以收藏备用，后续我会继续更新关于 MCP 远程部署和 LangGraph Agent 编排的实战内容。