LangChain与MCP实战：从FastMCP到Agent工具调用拦截器

先问一个问题：你看到的 AI Agent 大多数还停留在“能聊天、能写诗”的阶段，而真正有价值的是让大模型去执行任务。可是大模型本身不会操作你的 API、不会查你的数据库、不会调用你项目里的工具，它只会“说话”。为了让模型安全、统一、低成本地使用真实工具，2026 年前后的 Agent 工程化路径基本收敛到了 LangChain + MCP + Agent 这套组合上。

这篇文章面向有 Python 基础、想搞懂 Agent 工具调用全流程的开发者，也适合后端同学快速了解 Java 侧怎么接入 MCP。我会先解释 MCP 和 FastMCP 到底是什么，再带你把一个 FastMCP Server 写出来，然后交给 LangChain Agent 调用，最后补上工具拦截器、Java 集成和常见报错排查。整个流程走完，你不仅能跑通 Demo，还能理解为什么生产环境需要设计拦截层。

1. MCP 不是又一个 AI 框架，而是模型与工具之间的“标准化插座”

1.1 MCP 解决什么问题

在没有 MCP 之前，大模型要调用一个工具，通常需要开发者写大量胶水代码。每个模型有各自的 Function Calling 格式，每个工具又有自己的鉴权方式、参数结构、返回格式，结果就是模型、工具、应用三者之间互相绑定，换一个模型就要重写一遍工具层。

MCP（Model Context Protocol）的出现，相当于在模型和工具之间定义了一套统一协议。它可以理解成一个“标准化插座”：工具只需实现一套 MCP 服务端协议，任何支持 MCP 的客户端（LangChain、Claude、各类 Agent 框架）都可以直接对接。开发者不必再为每个模型单独适配工具。

1.2 LangChain、LangGraph、Agent 三者关系

很多新手容易把 LangChain 理解成一个“大而全的 AI 应用框架”，但从 2024 年到 2026 年的演进来看，官方已经逐渐把复杂工作流能力交给了 LangGraph，LangChain 则更多负责模型接入、工具管理、链式调用、检索增强等基础编排。

• LangChain：面向大模型应用的开发工具集，提供模型的统一抽象、 Prompt 模板、输出解析、工具调用等。
• LangGraph：在 LangChain 之上构建有状态、可编排的 Agent 工作流，适合复杂多步任务、人机协同、循环控制等场景。
• Agent：基于大模型决策，自动选择并调用工具完成任务。

做简单问答可以只用 LangChain，但要做真正的 Agent，需要在“模型判断、工具选择、结果观察”之间循环，这正是 LangGraph 的强项。不过在实际中，单 Agent 快速实现也可以只用 LangChain 自带的 AgentExecutor。

1.3 FastMCP 在生态中的位置

FastMCP 是 MCP Server 的一种轻量级快速开发方式，它降低了一步步手写 JSON-RPC 和 schema 定义的成本。调用者甚至不需要完整理解 MCP 底层消息格式，就可以把普通 Python 函数暴露成 MCP 工具。FastMCP 底层实际上是包装了 MCP Python SDK，因此不同写法之间经常容易混淆，我会在后面单独讲兼容问题。

2. 环境准备与版本说明

2.1 准备 Python 环境

建议使用 Python 3.10 及以上版本，虚拟环境隔离依赖。Windows、macOS、Linux 都可以，命令行操作略有差异。Linux 服务器部署时可使用python3 -m venv创建虚拟环境，本文以 Python 3.10+ 为例。

python3 -m venv venv source venv/bin/activate

Windows 下激活命令是：

venv\Scripts\activate

2.2 安装基础依赖

需要说明的是，2026 年这些库迭代速度很快，版本不能写死。实际安装时建议锁定一份能跑通的版本组合，尤其是 FastMCP 相关的底层 SDK。

pip install -U langchain langchain-openai langchain-mcp-adapters fastmcp mcp

这里按模块拆解一下：

• langchain：LangChain 核心库。
• langchain-openai：用于接入兼容 OpenAI 协议的大模型，也包括主流国内模型的 OpenAI 兼容接口。
• langchain-mcp-adapters：LangChain 官方提供的 MCP 适配器，能把 MCP 工具转换成 LangChain Tool。
• fastmcp：用于快速构建 MCP Server。
• mcp：MCP Python SDK，某些旧版 FastMCP 会依赖它。

如果你的项目里只需要调用已存在的 MCP Server，可以不装fastmcp，只装mcp和适配器。

2.3 建议的工程目录

为了让 Demo 清晰，建议按下面结构组织代码：

langchain-mcp-agent/ ├── .env ├── requirements.txt ├── server.py # FastMCP Server ├── agent_client.py # LangChain Agent 调用端 └── interceptor_demo.py # 工具拦截器示例

代码尽量按文件拆分，不要全堆到一个脚本里。

3. FastMCP 核心原理解析

3.1 MCP 的工作流程

先看一个简化的调用链路：

大模型（Agent） ↓ 决定调用工具 LangChain 工具层 ↓ 通过 MCP Client MCP 协议（stdio 或 HTTP/SSE） ↓ MCP Server（工具执行） ↓ 返回结构化结果

也就是说，MCP 客户端和 MCP Server 之间通过统一协议通信。stdio 模式适合本地进程，远程场景会用 HTTP 或 SSE 传输。

对开发者来说，日常最关心两件事：一是写 Server 时怎么把函数暴露成工具，二是在 Agent 端怎么发现并调用这些工具。

3.2 一个最简单的 FastMCP Server

创建一个server.py，内容如下：

from fastmcp import FastMCP # 创建 MCP Server 实例 mcp = FastMCP("demo-server") # 通过装饰器把普通函数暴露为 MCP 工具 @mcp.tool() def add(a: int, b: int) -> int: """计算两个整数之和""" return a + b @mcp.tool() def get_weather(city: str) -> str: """模拟查询城市天气，返回简单文本结果""" # 真实项目中这里可以调用外部 API return f"{city} 的天气：多云，24℃" if __name__ == "__main__": # 以 stdio 方式运行，供 MCP 客户端连接 mcp.run(transport="stdio")

这段代码包含两个工具：

• add：整数加法，用于演示参数传递。
• get_weather：模拟第三方服务，演示返回外部数据。

@mcp.tool()装饰器会根据函数签名、类型注解和 docstring，自动生成 MCP 协议要求的工具描述，这就是 FastMCP 简化开发的核心能力。Docstring 会被大模型当作工具说明，务必写清楚。

3.3 FastMCP 常见写法差异

不同版本的 FastMCP 暴露出的导入方式不完全一致。常见的写法有：

# 新版写法 from fastmcp import FastMCP # 也常见于基于 mcp SDK 的写法 from mcp.server.fastmcp import FastMCP

如果你遇到这样的报错：

ImportError: cannot import name 'fastmcp' from 'fastmcp' (unknown location)

原因通常是本地存在一个名为fastmcp.py的文件或fastmcp/目录，屏蔽了真正安装的包。另一种情况是包损坏或版本不兼容。排查时先看报错里fastmcp指向的路径，如果指向的是你的项目目录，说明命名冲突，需要把本地文件改名。

3.4 MCP Server 的四种核心能力

FastMCP 底层把 MCP Server 能力划分为：

• Tool：可被模型直接调用的函数。
• Resource：暴露数据资源，通常走文件式或资源式读取。
• Prompt：预置提示词模板。
• Sampling：让服务端反向请求模型补全。

工具类开发最常用 Tool。如果你的场景是让 Agent 获取私有数据，而不是执行操作，可以考虑 Resource，它更强调“上下文读取”。

4. LangChain Agent 集成 MCP 实战

4.1 在 Python 端通过适配器连接 MCP Server

要实现 Agent 调用 FastMCP 暴露的工具，需要启动一个 MCP Client。下面给出一个完整可运行示例。

创建.env文件，写入大模型相关配置：

OPENAI_API_KEY=your-api-key OPENAI_API_BASE=https://api.openai.com/v1 MODEL_NAME=gpt-4o-mini

如果使用的是国内兼容 OpenAI 协议的大模型，把OPENAI_API_BASE替换成对应服务商地址即可。

创建agent_client.py：

import asyncio import os from dotenv import load_dotenv from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI from langchain_mcp_adapters.client import MultiServerMCPClient load_dotenv() async def main(): # 启动一个 MCP Server 客户端 async with MultiServerMCPClient( { "demo": { "command": "python", "args": ["server.py"], "transport": "stdio", } } ) as client: # 获取 MCP 暴露的工具，转换为 LangChain Tool tools = client.get_tools() model = ChatOpenAI( model=os.getenv("MODEL_NAME", "gpt-4o-mini"), api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_API_BASE"), temperature=0 ) prompt = ChatPromptTemplate.from_messages( [ ("system", "你是一个智能助手，可以调用外部工具完成任务。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ] ) agent = create_openai_tools_agent(model, tools, prompt) executor = AgentExecutor(agent=agent, tools=tools, verbose=True) result = executor.invoke( {"input": "请帮我计算 123456 和 789012 两个数的和，" "然后查询城市【杭州】的天气。"} ) print(result["output"]) if __name__ == "__main__": asyncio.run(main())

这段代码的思路是：

1. MultiServerMCPClient以 stdio 方式拉起server.py。
2. client.get_tools()拿到所有 MCP 工具。
3. 将 MCP 工具作为 LangChain Agent 的可用工具集合。
4. 大模型根据用户问题自动决定是否调用工具。
5. AgentExecutor 负责执行 Agent 循环。

运行命令：

python agent_client.py

预期会看到模型内部多次调用add和get_weather的日志，最终输出类似这样：

这两个数的和是 912468，杭州的天气为多云，24℃。

4.2 create_openai_tools_agent 与 create_react_agent 怎么选

很多人在网上看到两种 Agent 写法，会疑惑有什么区别。

• create_openai_tools_agent：面向支持 Function/Tool Calling 的模型，要求模型能够返回结构化工具调用指令，适合 GPT、Claude、通义、智谱等新模型。
• create_react_agent：使用 ReAct 提示词风格，让模型以文本方式输出思考和动作，兼容性更广，但稳定性相对不如 Tool Calling。

新项目优先选择create_openai_tools_agent，或者升级到 LangGraph 的create_react_agent风格。如果你只需要快速验证 MCP 工具是否连通，上面基于 AgentExecutor 的写法已经足够。

4.3 复杂流程时切换到 LangGraph

当任务状态多、需要分支判断、需要人工确认或循环重试时，直接使用 AgentExecutor 会显得线程混乱。LangGraph 提供更明确的状态机写法，同样可以把 MCP 工具接入。

以下是一个简要示例，只展示 LangGraph 端到端的 Agent 用法：

from langchain_openai import ChatOpenAI from langchain_mcp_adapters.client import MultiServerMCPClient from langgraph.prebuilt import create_react_agent async def run_graph(): async with MultiServerMCPClient( { "demo": { "command": "python", "args": ["server.py"], "transport": "stdio", } } ) as client: tools = client.get_tools() model = ChatOpenAI(model="gpt-4o-mini", temperature=0) agent = create_react_agent(model, tools) result = await agent.ainvoke({"messages": [("human", "帮我计算 1 + 2")]}) return result import asyncio print(asyncio.run(run_graph()))

对比 LangChain 旧版 AgentExecutor，LangGraph 更强调messages状态流转，底层会维护消息历史，在复杂的多轮对话、条件分支场景中更有优势。

5. 工具拦截器：为什么 Agent 需要一层“安检”

5.1 拦截器解决的问题

MCP 工具一旦被 Agent 使用，模型就可能根据用户输入调用你的真实服务。如果完全不设防，会带来三个直接风险：

• 敏感参数越权：模型本来只应该查询某用户自己的数据，却被诱导传入其他用户 ID。
• 高风险操作不可控：删除、覆盖、转账、发消息等操作如果没有二次确认，后果严重。
• 审计缺失：模型调用了哪些工具、参数是什么、结果如何，全部没有日志。

工具拦截器的本质是在用户输入进入模型之前、以及模型返回工具调用之后，增加两层约束。常见做法是把“调用意图校验”和“参数校验”抽成装饰器或代理层。

5.2 Python 侧实现一个简单工具拦截器

我们可以在 FastMCP Server 外层包一层参数校验逻辑，也可以在 LangChain 工具层封装。这里给出一个通用的装饰器方案：

import functools import logging logger = logging.getLogger("tool-interceptor") ALLOWED_CITIES = {"杭州", "上海", "北京"} def tool_interceptor(func): """工具拦截器：统一校验和审计""" @functools.wraps(func) def wrapper(*args, **kwargs): # 模拟从上下文获取当前用户 user_id = kwargs.pop("_user_id", "anonymous") # 1. 参数校验 city = kwargs.get("city", "") if city and city not in ALLOWED_CITIES: logger.warning("user=%s 尝试访问未授权城市: %s", user_id, city) raise ValueError(f"城市 {city} 不在授权列表内") # 2. 操作审计 logger.info("user=%s call func=%s args=%s", user_id, func.__name__, kwargs) # 3. 执行原函数 return func(*args, **kwargs) return wrapper @mcp.tool() @tool_interceptor def get_weather(city: str) -> str: """查询指定城市天气（仅限授权城市）""" return f"{city} 的天气：多云，24℃"

这里有一个关键点：装饰器顺序。@mcp.tool()在最外层，用来把函数注册为 MCP 工具；@tool_interceptor在内层，用来包装真正的业务函数。这样 MCP 层对外暴露的是被拦截后的函数，而不是原始逻辑。

5.3 Java 和 Harness 场景下的“拦截”对应到哪一层

搜索中经常出现Harness，在 Agent 工程化里它不是某个具体 MCP 框架，而更偏向“处理链路中的执行环境、权限上下文、策略控制”。例如 Java 侧接入时，你可以在 MCP Client 与业务服务之间添加一个 Filter 层，类似 Spring MVC 拦截器，统一做身份解析、参数校验、调用审计。

如果团队已经有 Policy Engine 或网关，可以让 MCP 工具调用走统一鉴权网关，而不是在各工具内部重复写鉴权。拦截器不应该只做日志，它更是“安全边界”。

6. Java 侧集成 MCP 的思路

6.1 Java 生态里的 MCP 客户端

MCP 官方提供了 Java SDK，基于 Java 17 以上版本开发。常见路线是启动一个 MCP Server 地址，然后通过客户端注册 ToolSpecification，把远程工具适配成 Spring AI 的 Tool。

需要说明的是，Java SDK 版本迭代比较快，下面的代码只演示思路，不保证在你的版本上零修改运行。

// 使用 MCP Java SDK 建立连接并获取工具列表的核心思路 McpTransport transport = new StdioMcpTransport.Builder() .command("python") .args(List.of("server.py")) .build(); McpClient client = McpClient.using(transport) .sync(); InitializeRequest initRequest = new InitializeRequest(); client.initialize(initRequest); ListToolsResult tools = client.listTools(null); for (Tool tool : tools.tools()) { System.out.println("Tool name: " + tool.name()); System.out.println("Tool schema: " + tool.inputSchema()); }

如果你的服务端通过 HTTP 暴露 MCP，Java Client 需要换成 Http 或 SSE 传输方式，原理类似。

6.2 Java Agent 与工具调用闭环

实际 Java Agent 项目，通常顺序是：

1. Spring AI / LangChain4j 负责大模型对话和输出解析。
2. MCP Java SDK 负责发现工具，并把工具转换成函数调用格式。
3. 业务服务通过 Spring Bean 暴露给工具层。
4. 拦截器或 AOP 切面负责鉴权、限流、审计。

相比 Python，Java 对类型规范和异常处理更严格，MCP 的 JSON-Schema 到 Java 类型的映射容易出问题，尤其嵌套复杂对象时。建议保持 MCP 工具参数为简单类型，例如String、int、简单 List，避免对象嵌套导致序列化问题。

7. LangChain 与 LangGraph 如何配合使用

对于真正要上生产的项目，2026 年更合理的分工是：

• MCP Server 负责把存量系统能力变成标准工具，由业务团队独立维护。
• LangGraph 负责 Agent 状态机、任务编排、循环控制和人工审核节点。
• LangChain 作为基础库，提供模型接入、Prompt、输出解析能力。

一个比较常见的 Agent 设计是：先由 Graph 判断用户意图，然后按需调用 MCP 工具，如果工具结果置信度不够，再走人工确认分支。这样做的好处是，MCP 工具复用性高，LangGraph 编排灵活，两者通过 Tool 接口天然打通。

如果你只是做 AI 助手 Demo，直接 LangChain 足矣。如果你要做“能自动执行多步骤任务”的 Agent，建议优先学习 LangGraph，它的可控性会更好。

8. 常见问题与排查

下面整理 MCP + LangChain Agent 抛锚的高频场景。

8.1 为什么不能在 MCP Server 里随便 print

这点特别容易踩坑：当你使用 stdio transport 时，MCP Server 是通过标准输入输出与客户端通信的。如果你在 Server 代码里加一句：

print("debug log")

这段字符串会直接污染协议通道，轻则解析失败，重则 Client 一直等待。调试时请使用logging模块，并且让日志输出到 stderr：

import sys print("debug", file=sys.stderr)

8.2 Agent 执行时间过长导致超时

热词中有一条比较典型的英文报错：

The agent execution provider did not respond in time. This may indicate the model...

它的含义是模型在执行链中没有在限定时间内返回响应。常见原因有三个：

• 模型服务网络延迟高。
• Agent 进入了多轮工具循环，总耗时长。
• 请求上下文中塞入了过多工具描述，导致首 token 生成变慢。

排查时可以开启 verbose 模式，观察具体在哪一步耗时过高，再调整timeout、模型max_tokens或减少不必要的工具数量。

8.3 工具注册不上

特别是搜索里提到 Figma MCP 在 Codex 中注册不上。这类问题的共同点往往是：

• MCP Client 使用 OAuth 或 Token，但 Server 侧鉴权失败。
• 服务端工具列表与客户端 schema 不匹配。
• 远程 MCP URL 不稳定，客户端握手时拉取不到工具列表。

解决方式是先用官方 MCP Inspector 或ListTools测试工具枚举是否正常，不要直接冲进 Agent 排错。

9. 工程落地建议

9.1 工具边界要小，权限要收敛

一个 MCP Server 不要塞进几十个工具，建议按“领域”划分。比如订单域一个 Server，库存域一个 Server。一来工具说明会更聚焦，模型选择准确率更高；二来权限隔离也更清晰。

工具必须遵循最小必要权限，比如查询工具只给只读数据库账号。拦截器中即使校验通过，底层数据源也应限制行级权限，不能只依赖模型自觉。

9.2 工具描述就是“模型的操作说明书”

模型是通过 docstring/description 来决定要不要调用工具的。比如：

# 描述不清晰 def add(a, b): ... # 描述清晰 def add(a: int, b: int) -> int: """计算两个整数之和，参数 a 和 b 必须是整数"""

第二种才适合给 Agent 使用。描述里需要明确：用途、参数含义、单位、边界条件、可能的异常。建议把调用失败的常见原因写进说明，减少模型误判。

9.3 统一异常格式，让 Agent 能“看懂错误”

工具报错时不要直接抛一堆堆栈，Agent 拿到之后很难处理。生产环境更推荐返回结构化错误：

{ "error_code": "CITY_NOT_ALLOWED", "message": "城市不在授权列表内", "suggestion": "请询问用户是否切换为允许的城市" }

这样模型可以根据suggestion生成补救回答，而不是对堆栈束手无策。

9.4 设计审计与监控

每个工具调用都打印到日志可不够，建议记录下来：

• 用户 ID、会话 ID。
• 模型本次选择的工具名称和参数。
• 返回摘要和耗时。
• 结果是否命中成功。

如果做 Agent 平台，审计日志还需要支持回放，方便定位模型是否被 Prompt 注入诱导执行了风险动作。

9.5 关于安全边界的额外提醒

大模型调用工具的核心风险在于“不可预测性”。因此要求：

• 默认拒绝高风险操作，也就是白名单机制而不是黑名单。
• 涉及真实验收、删除、发消息、付款，必须接入人工确认节点。
• 不要在 MCP Server 里硬编码生产环境密钥，使用环境变量或配置中心。
• 对用户输入和工具返回内容都要做长度限制，防止超长内容耗尽上下文或形成提示注入。

10. 下一步可以做什么

跑通上面的 Demo 之后，建议你继续做三件事：

第一，把 MCP Server 从 stdio 改成远程 HTTP 版，让它作为一个独立服务运行，同时用 FastMCP 的远程配置方式连接，体验真正的服务化。

第二，把一个旧项目里的工具方法（比如查询订单、计算价格、生成周报）手动封装成 MCP 工具，接入 LangGraph，观察 Agent 在真实任务里的表现。

第三，写一个工具拦截器的中间件，把参数白名单、用户上下文、审计日志一起接进去，然后再让外部使用者通过 MCP 调用一次你的工具。你会发现，没有拦截层的 Demo 和带拦截层的工程系统，安全体验完全不一样。

如果这篇文章对你有帮助，可以先收藏备用。后续我会继续更新远程 MCP、工具注册中心、LangGraph 任务编排、Java Spring AI + MCP 实战等内容。遇到环境安装或者代码报错，欢迎在评论区说明异常栈和版本，我尽量帮你一起排查。