MCP+LangChain实战：从零搭建AI Agent工具调用架构

2026年了，如果你还在用“提示词+模型”的方式写 AI 应用，基本等于还在用记事本写代码。这一两年 AI 开发范式最大的变化，就是 MCP（Model Context Protocol）的快速普及。这个协议把 AI 应用从“模型+Prompt”变成了“模型+工具总线”，所有数据源、API、文件系统、数据库都能以统一方式接进大模型。

这次我们直接进入实战，不铺垫概念。文章核心围绕三件事：MCP Server 怎么搭、LangChain 怎么集成 MCP、Agent 怎么真正把工具用起来。全文按“环境准备 → Server 端实现 → LangChain 接入 → Agent 实战 → Debug 排查 → 工程化建议”展开，代码可以直接复制，路径和端口按你的环境调整。

如果你是做 AI 应用开发、Agent 开发，或者打算把 LangChain 项目升级到工具调用架构，这篇文章建议收藏。下面直接开始。

1. MCP 核心能力速览

先快速判断这东西适不适合你现在学。MCP 是 Anthropic 在 2024 年底开源的开放协议，目标是统一大模型应用和外部工具/数据源之间的通信方式。它解决的不是“模型聪明不聪明”的问题，而是“模型怎么稳定地调用工具”的问题。

从这张表可以得出一个结论：MCP 不是框架、不是模型、不是 SDK，它是“接口标准”。就像 HTTP 定义了 Web 如何通信，MCP 定义了 AI 应用如何发现和调用工具。学 MCP，核心是掌握三件事：Server 端暴露什么、Client 端怎么连、Agent 怎么选工具。

2. 适用场景与使用边界

MCP 的定位非常明确：解决 AI 应用接入外部系统时的碎片化问题。在它出现之前，每接一个数据源都要写一套私有函数调用，每换一个 Agent 框架又要重新适配一遍。MCP 把这些收敛成统一协议，工具即插即用。

适合的场景包括：

• 让 Agent 读取本地文件、数据库、网页内容。
• 让 Agent 调用内部 API，比如查询订单、创建工单、发送消息。
• 让 Agent 操作开发者工具，比如 GitHub、Figma、浏览器自动化。
• 让 Agent 在执行任务过程中动态选择多个工具组合调用。

不适合的场景也要说清楚。MCP 不负责模型能力提升，不负责工具内部逻辑的正确性，也不负责权限安全——这些都需要你自己在 Server 端和周边系统里控制。如果你只是做单轮问答、不需要外部数据，MCP 属于过度设计。

使用边界方面，只要涉及读取业务数据、写入系统、操作第三方账号，就必须要鉴权、限流、审计。尤其是调用线上 API 或操作真实业务数据时，建议先在测试环境验证身份体系和数据范围。

3. MCP 协议关键概念：Tools、Resources、Prompts

动手敲代码之前，先把协议层的三个核心原语理清楚。很多人在这一步就卡住了，因为网上资料常把这三者混在一起讲。

3.1 Tools（工具）

Tools 是 MCP 里最常用的原语，对应模型可执行的函数。每个 Tool 有名称、描述、输入参数 Schema。模型根据用户的自然语言请求，决定是否调用某个 Tool，并按照 Schema 生成参数。

例如一个get_weather工具，Schema 里声明city字符串参数。Agent 收到“北京明天天气如何”时，会调用get_weather并把city填成“北京”。

3.2 Resources（资源）

Resources 是静态或动态数据源，类似文件的虚拟化。比如把某个数据库查询结果、某个配置文档暴露成resource://orders/daily。模型不会直接“调用”资源，而是通过上下文读取。这适合给 Agent 注入背景信息、知识库片段、配置文件。

3.3 Prompts（提示词模板）

Prompts 是服务端预定义的提示词模板，客户端可以拉取并填入参数，快速生成结构化任务指令。比如定义一个review_code模板，接收language和code_path，就可以让 Agent 快速进入代码评审模式。

理论部分到这里就够了。接下来直接搭建环境，跑一个真实的 MCP Server。

4. LangChain + MCP 环境准备与前置条件

关于操作系统，Windows、macOS、Linux 都可以跑通 Stdio 模式的 MCP Server。如果你在 Linux 服务器上做 AI 开发，建议优先考虑稳定性优先的 Server 版本，Python 环境管理会更干净。桌面版不是不能做开发，只是服务器版在依赖隔离和后台进程管理上更省心。

4.1 安装 Python 与虚拟环境管理

推荐 Python 3.10 以上版本。Ubuntu 环境下面给出示例命令，Windows/macOS 请使用对应安装方式。

# Ubuntu / Debian 系列 sudo apt update sudo apt install -y python3 python3-venv python3-pip

创建独立项目目录和虚拟环境：

mkdir -p mcp-langchain-demo cd mcp-langchain-demo python3 -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate

4.2 安装 MCP SDK、LangChain 与适配层

核心依赖是：MCP Python SDK、LangChain、langchain-mcp-adapters。适配层的作用是把 MCP Server 暴露的工具“翻译”成 LangChain 能识别的工具。

pip install --upgrade pip pip install mcp langchain langchain-openai langchain-mcp-adapters

需要说明的是，langchain-mcp-adapters是官方维护的适配包，当前主流用法是通过McpServerClient连接 MCP Server，再把 tools 转成 LangChain 工具列表。更早的 0.1.x 版本有load_mcp_tools之类的函数式写法，如果你在别的教程里看到，注意版本差异。

pip show langchain-mcp-adapters

4.3 模型服务准备

LangChain Agent 需要一个大模型来决策是否调用工具。这里用 OpenAI 兼容接口为例，无论你用的是官方 API、第三方中转还是本地部署的模型服务，只要暴露 OpenAI 兼容接口，都可以通过ChatOpenAI接入。

# 需要设置环境变量 # 如果使用本地或其它兼容服务，改成对应地址即可 export OPENAI_API_KEY="your-api-key" export OPENAI_API_BASE="https://api.example.com/v1"

如果使用本地模型服务，比如 vLLM 或 LM Studio，则把OPENAI_API_BASE指向本地端口，具体配置以你部署的服务为准。

5. 从零搭建一个 MCP Server：文件查询与天气查询实战

这一节我们写一个真正的 MCP Server。它会暴露两个工具：

1. read_local_file：读取本地文本文件内容。
2. get_weather：根据城市名返回模拟天气数据。

选择这两个工具的原因很直接：read_local_file能验证 Agent 与本地文件系统的交互能力，get_weather能验证模型对工具参数 Schema 的遵循程度。

5.1 创建 Server 文件

创建一个weather_server.py：

from mcp.server.fastmcp import FastMCP from typing import Optional mcp = FastMCP("demo-server") @mcp.tool() async def get_weather(city: str) -> str: """根据城市名查询实时天气。""" # 这里仅作演示，返回模拟数据 weather_data = { "北京": "晴，气温 18℃，北风 3 级", "上海": "多云，气温 22℃，东风 2 级", "广州": "小雨，气温 26℃，南风 2 级", } return weather_data.get(city, f"抱歉，没有 {city} 的天气数据") @mcp.tool() async def read_local_file(file_path: str) -> str: """读取本地文本文件内容，返回纯文本。""" if not file_path.endswith(".txt"): return "仅支持读取 .txt 文本文件" try: with open(file_path, "r", encoding="utf-8") as f: content = f.read() return content[:2000] or "(文件为空)" except FileNotFoundError: return f"文件不存在: {file_path}" except Exception as e: return f"读取失败: {str(e)}" if __name__ == "__main__": mcp.run(transport="stdio")

关键点：

• 装饰器@mcp.tool()把普通函数变成 MCP 工具。
• 函数类型注解和文档字符串会被自动提取成工具描述和参数 Schema。所以描述要写清楚“什么时候该调用、参数代表什么”。
• transport="stdio"表示通过标准输入输出通信，这是 LangChain 本地集成最稳定的方式。

5.2 手动运行测试 Server

先启动 Server，确保没报错：

python weather_server.py

如果能看到进程挂起、没有任何错误输出，说明 Stdio 模式初始化成功。注意此时该进程是在等待客户端连接，所以终端会一直停留。

5.3 用 MCP Inspector 调试

MCP 官方提供网页调试工具mcp-inspector，可以单独验证 Server 的注册工具和调用结果。

npx @modelcontextprotocol/inspector python weather_server.py

启动后根据控制台提示打开地址（一般是http://localhost:6274），在页面里能看到：

• Tools 列表里有两个工具。
• 点击get_weather，输入city为“北京”，能直接看到返回结果。
• 点击read_local_file，输入一个本机存在的.txt路径，能读取到文件内容。

这一步相当重要。先确认 Server 本身没问题，再去接 LangChain，否则后面出错时很难定位是协议问题还是框架适配问题。

6. LangChain Agent 集成 MCP：完整代码与启动流程

Server 已经能跑了，现在把它接进 LangChain Agent。

6.1 创建 LangChain 集成脚本

创建agent_demo.py：

import asyncio import os from pathlib import Path from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_mcp_adapters.client import McpServerClient async def run_agent(): # 固定 MCP Server 路径，按你的实际目录调整 server_script = str(Path(__file__).parent / "weather_server.py") # 连接本地 MCP Server async with McpServerClient( command="python", args=[server_script], encoding="utf-8", ) as client: # 获取工具列表，转成 LangChain 工具格式 tools = await client.get_tools() print(f"成功加载工具数量: {len(tools)}") for t in tools: print(f" - {t.name}: {t.description}") llm = ChatOpenAI( model="gpt-4o-mini", temperature=0, openai_api_key=os.getenv("OPENAI_API_KEY"), openai_api_base=os.getenv("OPENAI_API_BASE"), ) prompt = ChatPromptTemplate.from_messages( [ ("system", "你是一个可以调用本地工具的助手。需要工具时就调用工具。"), ("human", "{input}"), MessagesPlaceholder(variable_name="agent_scratchpad"), ] ) agent = create_openai_tools_agent(llm, tools, prompt) executor = AgentExecutor(agent=agent, tools=tools, verbose=True) # 测试 1：天气查询 result = await executor.ainvoke( {"input": "查询一下北京的天气情况"} ) print("== 天气查询结果 ==") print(result["output"]) # 测试 2：读取本地文件 test_file = Path(__file__).parent / "demo.txt" test_file.write_text("hello from mcp langchain agent", encoding="utf-8") result = await executor.ainvoke( {"input": f"读取本地文件 {test_file} 的内容"} ) print("== 文件读取结果 ==") print(result["output"]) if __name__ == "__main__": asyncio.run(run_agent())

6.2 启动并观察日志

运行脚本：

python agent_demo.py

正常流程会分几步：

1. McpServerClient拉起本地weather_server.py子进程。
2. 客户端自动完成 MCP 握手，获取工具列表。
3. LangChain 把工具包装成 Agent 可调用的BaseTool。
4. 用户提问后，LLM 决定调用哪个工具，Agent Executor 执行并把结果返回给 LLM。
5. LLM 根据工具结果生成最终回复。

verbose=True的 Agent 会打印详细的中间步骤，这是新手最重要的调试窗口。可以看到 LLM 的工具调用请求参数、工具返回结果、最终答案内容。

6.3 两个测试用例的预期结果

测试 1 中，输入“查询一下北京的天气情况”，理想情况是 LLM 先调get_weather(city="北京")，再基于返回结果给出“北京天气晴，气温 18℃”之类的回答。

测试 2 中，输入“读取本地文件 /path/to/demo.txt 的内容”，Agent 会调read_local_file(file_path=...)，并把文件内容回复给用户。

如果工具名、参数描述写得足够清晰，LLM 基本能准确选对工具。如果描述太模糊，模型可能会出现“没有调用工具直接编造答案”“选错工具”“参数格式错误”三种典型问题，这一点在后面的排查章节展开。

7. MCP Server 的更多连接方式：远程 MCP 与多工具组合

Stdio 模式适合本地开发，但真实业务里，MCP Server 多半部署在远端，通过 HTTP 暴露。这一节给出远程 MCP 的对接思路和代码模板。

7.1 通过 URL 连接远程 MCP Server

langchain-mcp-adapters也支持直接通过urllib连接远程 MCP Server。前提是远端已经启动了 Streamable HTTP 模式的 MCP 服务，并暴露了可访问的 URL。

from langchain_mcp_adapters.client import McpServerClient client = McpServerClient(url="http://your-server:8000/mcp") tools = await client.get_tools()

这种模式适合前后端分离、多 Agent 共享同一批工具的场景。需要注意的是：

• 远程模式必须确认接口鉴权和网络白名单。
• 工具数量多时，工具描述和 Schema 会占不少上下文 Token，建议服务端精简描述。
• 远程 MCP 的延迟比本地 stdio 高一个量级，对延迟敏感的场景要评估。

7.2 多 MCP Server 组合

Agent 不需要只连一个 Server。你可以同时连接“数据库 MCP Server”和“文件系统 MCP Server”，把两边的工具一起注册进 Agent。

server1 = McpServerClient(command="python", args=["db_server.py"]) server2 = McpServerClient(command="python", args=["file_server.py"]) async with server1 as s1, server2 as s2: tools = await s1.get_tools() + await s2.get_tools()

这种组合方式非常实用，比如一个 Agent 既需要读取数据库里的用户信息，又需要把结果写入日志文件，两个 Server 各司其职。

8. 接口 API 化与批量任务设计

MCP 本身是 Agent 与工具之间的协议，不是给外部系统直接调用的 HTTP API。但真实业务里，你需要把“MCP Server 的查询能力”封装成可供其他系统调用的 API。常见做法是用 FastAPI 包一层。

8.1 用 FastAPI 封装 MCP 工具查询

from fastapi import FastAPI from pydantic import BaseModel import asyncio app = FastAPI() class QueryRequest(BaseModel): user_input: str @app.post("/agent/run") async def run_agent(req: QueryRequest): from agent_demo import run_agent_once result = await run_agent_once(req.user_input) return { "output": result["output"], "intermediate_steps": str(result["intermediate_steps"]), }

注意：这里依赖run_agent_once是你自己写的、能接收字符串并返回结果的函数。实际项目建议把 Agent 初始化逻辑独立出来，避免每次请求都重新拉起 MCP Server 子进程。

8.2 批量任务队列设计

批量任务场景下，不要直接并发拉太多 MCP 连接，要设置信号量和重试机制。下面是一个简单的批量处理模板：

import asyncio from asyncio import Semaphore async def batch_process(user_inputs: list[str], max_concurrency: int = 3): sem = Semaphore(max_concurrency) async def process_one(text: str): async with sem: # 这里替换成你自己的 Agent 调用函数 return await run_agent_once(text) results = await asyncio.gather(*[process_one(t) for t in user_inputs]) return results

批量任务的核心注意事项：

• 控制并发数，防止上游 LLM API 限流。
• 记录每个任务的输入、输出、耗时和错误信息，方便失败重放。
• 如果 Agent 内部有状态，需要确认多任务之间是否有状态污染。

9. 资源占用与性能观察

MCP 是协议层，本身不跑模型，所以显存占用可以忽略不计。真正占资源的是 LLM 推理服务和 MCP Server 所在进程的开销。以下观察点值得关注。

9.1 如何观察性能

• 启动时间：McpServerClient拉起本地 Python 子进程需要一个握手周期，Linux 下通常比 Windows 快一些，具体以本机测试为准。
• 工具调用延迟：LLM 决策 + 工具执行 + LLM 总结，三段耗时。工具执行如果涉及网络请求，会显著增加总时长。
• Token 消耗：Agent 的中间步骤会消耗大量 Token，尤其是工具描述过长、多轮调用时。建议用verbose=True观察每一轮的 Token 变化。

9.2 降低开销的技巧

• 精简工具描述，不要写冗长的历史背景。
• 参数 Schema 只保留必要字段，减少生成参数时的错误。
• 如果 Agent 只需要 1 个工具，不要注册 10 个工具，避免干扰决策。
• 批量任务使用异步并发，但并发数不要超过 LLM 接口的 RPM 限制。

9.3 进程残留问题

Stdio 模式下，如果 Python 脚本异常退出，子进程可能残留。排查时用系统进程命令检查：

ps aux | grep weather_server.py # Linux / macOS tasklist | findstr weather_server.py # Windows

如果发现残留，直接终止对应 PID，否则端口无关的 stdio 子进程会累积占用内存。

10. 常见问题与排查方法

这一节整理我实践中比较高频的坑。每个问题都按现象、原因、排查、解决四步列出。

11. Agent 工具选择的工程化经验

很多人第一次跑通 MCP Agent 后，会陷入一个困惑：既然 LLM 能选工具，是不是工具越多越好？

不是。工具数量增加会带来三个问题：

第一，工具描述占据上下文窗口。一个工具的描述如果写 200 Token，50 个工具就是 10000 Token，模型用于推理的空间被压缩，工具选择准确率反而下降。

第二，模型在“相似工具”之间容易选错。比如get_weather和get_temperature描述相似，模型可能错误调用。除非有必要，否则把功能相近的工具合并成一个工具，内部用参数区分。

第三，调试变难。工具多，中间步骤就多，定位问题更耗时间。建议第一版只注册核心工具，跑通后再逐步扩充。

另外，创建 Agent 时一定要限制最大迭代次数，防止模型在工具调用中死循环。AgentExecutor有max_iterations参数，建议起步设为 3 到 5。

12. 最佳实践与合规提醒

到这里，整个 MCP + LangChain + Agent 的链路已经跑通。最后给几条工程化建议。

12.1 代码与配置管理

• 所有工具函数写独立文件，不要堆在 Agent 启动脚本里。
• MCP Server 的启动命令、模型 API Key、Base URL 全部用环境变量或配置文件管理，不要硬编码。
• 工具函数内部不要打印敏感数据，日志级别要可控。

12.2 架构与部署建议

• 本地开发用 stdio 模式，部署到服务器后优先考虑远程 MCP 模式，便于多个 Agent 共享。
• 如果多个 Agent 需要调用同一批工具，建议把 MCP Server 独立部署成服务，不要每个 Agent 都拉一个子进程。
• 对耗时较长的工具调用，比如爬网页、跑数据分析，建议改成异步任务，Agent 先返回“正在处理”，结果通过异步回调或轮询获取。

12.3 安全与合规

• 工具调用如果涉及读取数据库或文件系统，必须做路径白名单和权限校验，防止 Agent 被诱导访问未授权文件。
• MCP Server 暴露到公网时，必须加鉴权，建议使用 API Key 或 OAuth 方式，禁止裸奔。
• 如果 Agent 操作的是真实业务系统，比如发送邮件、修改订单、删除文件，建议先实现“预执行确认”逻辑，也就是让 Agent 先生成操作预览，由人工确认后再执行。
• 涉及第三方平台的自动化操作，比如 GitHub、Figma、浏览器控制，必须保证有授权，并且只在允许的范围内执行，不突破权限边界。

13. 总结与下一步

MCP 不是新语言，也不是新框架，它是 AI 应用开发里“工具链统一”的答案。这篇文章的核心链路是：本地 Stdio 模式启动 MCP Server，通过langchain-mcp-adapters把工具接进 LangChain Agent，让 LLM 自主选择工具并返回结果。整个过程不依赖高配显卡，不依赖特定模型服务，只要模型支持 OpenAI 兼容的工具调用接口就能跑。环境方面，Windows、macOS、Linux 都能开发，部署到服务器时建议用稳定优先的 Linux 发行版。

最先要验证的功能，建议按这个顺序来：先单独跑weather_server.py，再用 MCP Inspector 确认工具注册，最后才接 LangChain。最容易踩的坑有三个：工具描述写得太含糊导致模型选错或乱编、McpServerClient的args路径写错导致子进程启动失败、以及批量任务并发过高被 LLM 接口限流。这三个坑，分别对应 Schema 设计、环境调试、并发控制三个层面的能力，也是 MCP 工程化最核心的经验。

下一步可以扩展的方向很多：把 MCP Server 部署成远程 HTTP 服务、接入 LangGraph 做有状态 Agent、结合 RAG 给 Agent 注入私域知识，或者用 MCP 对接更多内部系统。最推荐的做法是：先以一个真实工具为目标，把它完整跑通并部署，再复用这套流程去接第二个、第三个工具。工具一多，你就能明显感受到统一协议的价值。