LangChain MCP 1.4.0a2 集成 FastMCP 协议 · 干货攻略

• 链接: https://x.com/hwchase17/status/2093426582002208786
• 分类: x-tips
• 来源: X @hwchase17
• 作者: Jay
• 更新: 2026-09-03
• 仓库: langchain-ai/langchain-mcp-adapters

这是什么

2026 年 8 月底，LangChain 官方在 langchain==1.4.0a2 中正式加入了基于 FastMCP 协议的 MCP（Model Context Protocol）适配层，使 LangChain/LangGraph Agent 能够直接调用任何兼容 MCP 标准的外部工具服务器。该功能通过独立包 langchain-mcp-adapters 实现，核心组件是 MultiServerMCPClient——一个可以同时连接多个 MCP 服务器并统一加载其工具的客户端。

注意：原帖署名 @hwchase17（LangChain 创始人），实际发帖人为 @sydneyrunkle（LangChain 团队），她于 2026-08-28 在 X 上宣布了这一更新，版本号为 langchain==1.4.0a2（alpha 预览版）。

为什么值得关注

解决什么问题

在 LangChain 拥抱 MCP 之前，Agent 要接入外部工具需要为每个工具写单独的适配代码。MCP 是一种开放协议（Anthropic 主导），旨在标准化 LLM 与工具/数据源之间的交互方式。有了 langchain-mcp-adapters：

• 任何 MCP 工具 → 直接变成 LangChain 工具，无需定制开发
• 多服务器场景 → 一个 MultiServerMCPClient 管理所有连接，工具按需路由
• 多种传输协议 → stdio（本地子进程）、HTTP/SSE、Streamable HTTP、WebSocket 一套 API 全支持

关键适用场景

1. 企业内部有多个 MCP 工具服务器（数据库、API、文件操作），需要被 LangGraph Agent 统一调度
2. 想用 FastMCP 的简洁 API 定义工具，同时让 LangChain Agent 能调用它们
3. 需要跨多个 MCP 服务器做工具选择（tool selection），由 Agent 自主决定调用哪个

核验过程

官方来源

交叉验证

• 官方 README 明确指出：pip install langchain-mcp-adapters 后，通过 to_fastmcp() 可将 LangChain 工具导出为 FastMCP 工具（即双向互通）
• 官方文档确认：Streamable HTTP 传输自动回退到 SSE 以兼容旧版 MCP 服务器实现
• 官方参考文档确认：MultiServerMCPClient 的 tool_name_prefix 参数默认为 False，同名单工具不会自动去重，需手动开启前缀区分

⚠️ 冲突说明

• 原帖主张："multi-server tool selection 与 auth handoffs 实操摩擦点社区首次系统性披露"——这一说法未经官方文档确认。官方 README 和 LangChain 文档均未系统列出 auth handoffs 的已知问题，本攻略不将此类未经核验的说法作为结论写入，仅引用社区论坛（LangChain Forum）中已记录的 Windows stdio bug 作为已知摩擦点实例。

上手步骤

1. 安装依赖

pip install langchain-mcp-adapters langgraph "langchain[openai]"
# 或
uv add langchain-mcp-adapters langgraph

2. 用 FastMCP 创建工具服务器

# math_server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Multiply two numbers"""
    return a * b

if __name__ == "__main__":
    mcp.run(transport="stdio")

3. LangChain 多服务器客户端接入

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent

async def main():
    client = MultiServerMCPClient(
        {
            "math": {
                "command": "python",
                "args": ["/path/to/math_server.py"],
                "transport": "stdio",          # 本地子进程
            },
            "weather": {
                "url": "http://localhost:8000/mcp",
                "transport": "http",          # 远程 HTTP 服务
            }
        },
        tool_name_prefix=True,                  # 避免同名工具冲突
        handle_tool_errors=True,               # 错误返回给 Agent 自愈而非崩溃
    )

    tools = await client.get_tools()
    agent = create_agent("claude-sonnet-4-6", tools)
    response = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "what's (3 + 5) x 12?"}]}
    )
    print(response)

asyncio.run(main())

4. 远程 MCP 服务器（Streamable HTTP）

# 先启动示例服务器
# cd examples/servers/streamable-http-stateless/
# uv run mcp-simple-streamablehttp-stateless --port 3000

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
from langchain_mcp_adapters.tools import load_mcp_tools

async with streamablehttp_client("http://localhost:3000/mcp") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await load_mcp_tools(session)
        # 进一步接入 Agent ...

5. 工具拦截器（认证中间件示例）

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_mcp_adapters.interceptors import MCPToolCallRequest
from langchain_core.messages import ToolMessage

async def require_authentication(request: MCPToolCallRequest, handler):
    """给每个 MCP 工具调用附加认证信息"""
    runtime = request.runtime
    # 在请求头中注入 Bearer token
    runtime.headers["Authorization"] = f"Bearer {os.getenv('MCP_API_KEY')}"
    return await handler(request)

client = MultiServerMCPClient(
    {...},
    tool_interceptors=[require_authentication],
)

6. 将 LangChain 工具导出为 FastMCP 服务

from langchain_mcp_adapters.tools import to_fastmcp
from langchain_core.tools import tool

@tool
def get_weather(location: str) -> str:
    """Get weather for location"""
    return f"It's sunny in {location}"

# 将 LangChain 工具变成 FastMCP 服务，可被任何 MCP 客户端调用
fastmcp_server = to_fastmcp([get_weather])

坑与适用边界

1. Windows + stdio 传输 = 已知 bug

LangChain Forum 有记录（2026-09 初）：Windows 环境下 FastMCP stdio 传输无法正常启动 subprocess，日志完全不输出。macOS 和 Linux 正常。 临时方案：换用 transport="http"（需要 MCP 服务器单独部署）。

2. 同名工具需手动排重

tool_name_prefix 默认为 False，多个 MCP 服务器若有同名工具，LangChain 会直接报错或覆盖。开启前缀可解：

client = MultiServerMCPClient({...}, tool_name_prefix=True)
# 工具名变为 "math_add" / "weather_add"，避免冲突

3. MultiServerMCPClient 默认无状态

每次工具调用都会创建新的 ClientSession，执行完毕立即清理。如果需要保持会话状态，需要显式管理 session：

async with client.session("math") as session:
    tools = await load_mcp_tools(session)
    # 在同一个 session 内多次调用

4. handle_tool_errors 行为

默认为 True（新行为）：工具执行报错时返回 ToolMessage 带 status="error"，让 Agent 可以自愈。设为 False 为旧行为，直接抛 ToolException。

5. auth handoffs

原帖提及"auth handoffs 实操摩擦点"为社区观察，官方文档未系统记录。现有认证支持方式是通过 tool_interceptors 在请求层注入 header，或通过 httpx.Auth 对象传入 auth 参数。无开箱即用的跨服务器身份转发机制。

一句话结论

langchain-mcp-adapters 让 LangChain Agent 无缝接入任意 MCP 工具服务器，核心是 MultiServerMCPClient 的多传输协议支持；上手简单（pip install 即可），但多服务器同名工具冲突、Windows stdio bug、auth handoffs 机制缺失是已知坑，生产使用前需确认传输层和认证方案。