LangChain + 模型上下文协议（MCP）：AI 智能体 Demo 的 TaoToken 统一接入实践

1. 为什么 LangChain 智能体 Demo 总卡在工具接入这一步如果你最近在折腾 LangChain 智能体 Demo大概率会遇到一个很具体的场景模型能聊天但一让它调用外部工具就出问题。要么是工具注册方式每个框架都不一样要么是模型请求的通道换来换去Key 管理散落在好几个文件里。我试过把算术工具、文件读取、搜索接口分别用不同方式塞进 Agent结果调试成本比写业务逻辑还高。模型上下文协议MCP出现的意义就在这里。它把「模型怎么发现工具、怎么调用工具、怎么拿回结果」这件事标准化了。你可以把它理解成 AI 世界的 USB-C 接口以前每个外设一个专用口现在统一成一个协议。MCP 由 Anthropic 推动开源核心目标是让大语言模型能够安全、可解释地连接外部数据源和工具服务。对于本地 Demo 调试来说这意味着你写一次 MCP Server就能被多个支持 MCP 的客户端复用。但光有 MCP 还不够。LangChain 负责编排智能体的推理循环MCP 负责工具侧的标准化中间还缺一个稳定的模型请求通道。很多人在 Demo 阶段直接用某个厂商的 Key一旦要换模型或者做多模型对比就得改代码、改环境变量、改 Base URL。TaoToken 在这里扮演的角色就是统一 Key 和 API 通道你拿一个 Key通过一个兼容 OpenAI 协议的入口就能请求不同模型同时把 MCP 工具链挂到 LangChain Agent 上。这篇内容面向的是本地 Demo 调试场景。我会给出可复制的 LangChain Agent 配置片段、MCP 服务注册步骤以及一次完整的工具调用验证动作。目标很明确让你跑通从模型请求到 MCP 工具执行的闭环而不是停留在「连上后就能用」的空泛描述。适合谁适合已经会写 Python、用过 LangChain 基础组件、想快速验证 MCP 工具链的开发者。如果你还没配过环境跟着步骤走也能跑起来。核心检索词先明确LangChain 集成 MCP、模型上下文协议工具调用、AI 智能体 Demo 统一接入。这三个词会贯穿全文后面每个配置和排障都围绕它们展开。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在写 LangChain Agent 之前先把模型请求通道固定下来。这一步不做后面调试工具调用时你会分不清是模型没返回 tool_calls还是 Key 或 Base URL 配错了。TaoToken 的接入方式兼容 OpenAI 协议所以 LangChain 里的 ChatOpenAI 可以直接用只需要改三个东西API Key、Base URL、Model ID。先拿 Key。打开 TaoToken 的 API Keys 管理页创建一个新 Key。地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys创建后复制出来形如sk-xxxx。注意不要提交到 Git本地 Demo 用环境变量管理。然后确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api这个地址不加 UTM 参数直接作为 OpenAI 兼容的 base_url 使用。LangChain 的 ChatOpenAI 默认会拼/chat/completions所以 base_url 填到/api这一层即可。Model ID 怎么选如果你只是跑通 Demo选一个支持 function calling / tool calling 的模型就行。比如gpt-4o、claude-3-5-sonnet这类。具体可用列表可以在模型对话页里看https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels这里有个坑要注意不是所有模型都支持工具调用。如果你选的模型在返回里没有tool_calls字段LangChain 的 ReAct Agent 就不会触发 MCP 工具。所以第一步验证时先用一个明确支持 tool calling 的模型。环境变量配置建议这样写export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Python 里读取。不要硬编码在代码里Demo 也一样。后面如果要做多模型对比只改环境变量不改代码。依赖安装部分除了 LangChain 和 MCP 适配器还需要 LangGraph 的预构建 Agent。一条命令pip install langchain-mcp-adapters langgraph langchain-openai mcp这里langchain-mcp-adapters是 LangChain 官方维护的 MCP 适配层负责把 MCP 工具转成 LangChain Tool。mcp是协议本身的 Python SDK。langgraph提供create_react_agent比手写 AgentExecutor 更简洁。如果你打算长期跑编码类 Agent或者需要更稳定的调用配额可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan但本地 Demo 阶段先用按量 Key 就够了。前置准备的核心就一句话一个 Key、一个 Base URL、一个支持 tool calling 的 Model ID。这三件套后面在 LangChain 配置里会反复出现。3. 可复制配置MCP Server 注册与 LangChain Agent 接入这一节是全文的核心操作区。我会先写一个最小可用的 MCP Server再写 LangChain 客户端最后给出完整的配置片段。你直接复制就能跑。3.1 写一个数学计算 MCP Server创建math_server.pyfrom mcp.server.fastmcp import FastMCP mcp FastMCP(Math) mcp.tool() def add(a: int, b: int) - int: 两数相加 return a b mcp.tool() def multiply(a: int, b: int) - int: 两数相乘 return a * b if __name__ __main__: mcp.run(transportstdio)这里用的是 FastMCP它把函数签名和 docstring 自动转成 MCP 工具描述。transportstdio表示通过标准输入输出通信适合本地 Demo。注意 docstring 要写清楚模型靠它判断什么时候调用这个工具。3.2 LangChain 客户端接入 MCP创建client.pyimport asyncio import os from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools from langgraph.prebuilt import create_react_agent from langchain_openai import ChatOpenAI model ChatOpenAI( modelgpt-4o, api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], temperature0, ) server_params StdioServerParameters( commandpython, args[math_server.py], ) async def run_agent(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await load_mcp_tools(session) agent create_react_agent(model, tools) result await agent.ainvoke( {messages: whats (3 5) x 12?} ) return result if __name__ __main__: print(asyncio.run(run_agent()))这段配置里有三个关键点。第一ChatOpenAI的base_url指向 TaoToken 的 API 入口api_key从环境变量读。第二StdioServerParameters里的args要填math_server.py的路径如果不在同目录用绝对路径。第三load_mcp_tools(session)会把 MCP Server 里注册的add和multiply转成 LangChain Tool然后create_react_agent自动完成工具绑定。3.3 用 settings 片段固定配置如果你用 VS Code 或者 Cursor 做本地调试可以把环境变量写进.vscode/settings.json或者项目根目录的.env。这里给一个.env示例TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在代码里用python-dotenv加载from dotenv import load_dotenv load_dotenv()如果你用的是 Claude Code 或者 Cline 这类工具配置里同样需要三件套Base URL、Key、Model ID。以 Cline 的 MCP 配置为例JSON 片段如下{ mcpServers: { math: { command: python, args: [/absolute/path/to/math_server.py] } } }注意这里的args必须是绝对路径相对路径在 MCP 客户端启动时容易找不到文件。这是我在本地调试时踩过的坑之一。3.4 运行顺序先启动 MCP Server 不需要单独跑因为stdio_client会自动拉起子进程。你只需要运行客户端python client.py如果一切正常你会看到 Agent 先调用add(3, 5)再调用multiply(8, 12)最后返回自然语言答案。下一节我会拆解这个返回结构并给出验证成功的判断标准。4. 验证请求一次完整的工具调用闭环与结果解读跑通client.py之后不要只看最后那句自然语言答案。真正要验证的是中间的工具调用链路是否完整。LangGraph 的ainvoke返回的是一个包含messages列表的字典里面记录了从用户提问到最终响应的每一步。一次成功的输出结构大致如下{ messages: [ HumanMessage(contentwhats (3 5) x 12?), AIMessage( content, tool_calls[ {name: add, args: {a: 3, b: 5}, id: call_1}, {name: multiply, args: {a: 8, b: 12}, id: call_2} ], finish_reasontool_calls ), ToolMessage(content8, nameadd, tool_call_idcall_1), ToolMessage(content96, namemultiply, tool_call_idcall_2), AIMessage( contentThe result of (3 5) x 12 is 96., finish_reasonstop ) ] }判断闭环成功的标准有三个。第一AIMessage里出现了tool_calls并且finish_reason是tool_calls说明模型正确识别了需要调用工具。第二ToolMessage的tool_call_id和前面的调用 ID 一一对应说明 MCP Server 执行结果正确回传。第三最后一条AIMessage的finish_reason是stop并且内容里包含了计算结果 96。如果只看到自然语言答案但中间没有tool_calls那说明模型没有走工具调用可能是 Model ID 不支持 tool calling或者 MCP 工具没有正确加载。你可以在load_mcp_tools之后打印一下tools列表tools await load_mcp_tools(session) print([t.name for t in tools])正常应该输出[add, multiply]。如果为空检查math_server.py里的mcp.tool()装饰器是否生效以及session.initialize()是否在load_mcp_tools之前调用。另一个验证点是 Token 消耗。在返回的AIMessage里通常能看到usage_metadata或response_metadata里面记录了输入和输出 token 数。Demo 阶段不用太在意成本但如果你要对比不同模型这个字段很有用。实测下来从模型请求到 MCP 工具执行整个链路在本地通常 2 到 5 秒完成。如果超过 10 秒还没返回大概率是 MCP Server 启动失败或者模型请求超时。下一节我会列出几个常见报错和排查方法。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。你在本地跑 LangChain MCP 时最可能遇到下面几类问题。每个我都给出触发场景和排查路径。5.1 401 Unauthorized报错长这样openai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}触发场景TAOTOKEN_API_KEY没设置或者设置成了别的平台的 Key。排查步骤先在终端确认环境变量是否生效echo $TAOTOKEN_API_KEY如果输出为空说明.env没加载或者 export 没执行。另一个可能是 Key 复制时带了空格或换行。重新在 API Keys 页面复制一次注意不要多选字符。5.2 local proxy failed / connection error报错长这样openai.APIConnectionError: Connection error.或者某些客户端会提示local proxy failed。触发场景base_url写错或者本地网络无法访问目标地址。排查步骤确认TAOTOKEN_BASE_URL是https://taotoken.net/api不要多加/v1或者结尾斜杠。然后用 curl 直接测curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o,messages:[{role:user,content:hi}]}如果 curl 能通说明是 LangChain 配置问题如果 curl 也不通检查网络和 Base URL。5.3 reading choices 报错报错长这样KeyError: choices或者TypeError: NoneType object is not subscriptable出现在解析响应时。触发场景模型返回结构不符合 OpenAI 格式或者请求被中间层拦截返回了错误 JSON。排查步骤先打印原始响应。在ChatOpenAI里加max_retries0然后捕获异常打印e.response.text。常见原因是 Model ID 写错比如把gpt-4o写成了gpt4o。确认模型 ID 从模型对话页复制。5.4 OAuth 相关报错报错长这样OAuth token exchange failed或者某些 MCP 客户端提示需要授权。触发场景你用的 MCP Server 需要远程认证但本地 Demo 用的是 stdio 传输不涉及 OAuth。如果你在 Claude Code 或 Cline 里配置远程 MCP Server才需要处理 OAuth。排查步骤本地 Demo 阶段优先用 stdio 传输的 MCP Server避免引入 OAuth 复杂度。如果必须用远程 MCP确认回调地址和 client_id 配置正确。5.5 MCP Server 启动失败报错长这样FileNotFoundError: [Errno 2] No such file or directory: math_server.py触发场景StdioServerParameters的args用了相对路径但工作目录不对。排查步骤改成绝对路径import os server_params StdioServerParameters( commandpython, args[os.path.abspath(math_server.py)], )另一个常见问题是commandpython在某些环境里应该用python3或者虚拟环境的完整路径。如果你用了 venv建议填 venv 里的 python 绝对路径。5.6 工具没有被调用这个不算报错但结果不对。Agent 直接回答了96但没有走add和multiply。触发场景模型不支持 tool calling或者create_react_agent没有正确绑定工具。排查步骤先确认tools列表非空再确认 Model ID 支持 function calling。如果用的是 TaoToken 统一通道可以在模型对话页先手动测一下该模型是否返回tool_calls。排障时如果拿不准直接看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc文档里有 Base URL、鉴权方式、兼容端点的说明。大部分 401 和连接问题都能在那里找到答案。6. 把 Demo 跑稳之后统一通道与 MCP 工具链的下一步Demo 跑通只是起点。真正要往生产或者长期调试走有几个方向可以继续。第一把 MCP Server 从 stdio 换成 SSE 或 streamable HTTP这样多个客户端可以共享同一套工具服务。第二把 LangChain Agent 的 prompt 和工具选择逻辑抽出来做成可配置的方便对比不同模型在同一个 MCP 工具链上的表现。第三用 TaoToken 的统一 Key 做多模型路由同一个 Agent 代码只改 Model ID 就能切换底层模型。如果你后面要跑更复杂的编码类 Agent或者需要更稳定的长会话配额可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan如果只是想快速验证某个模型是否支持 tool calling直接用模型对话页测https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat需要新建或管理 Key 的时候回到 API Keys 页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdocClaude Code 相关的 Anthropic 兼容配置可以参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_anthropic最后给一个实用技巧在本地 Demo 里加一个--debug参数把agent.ainvoke返回的messages完整打印出来。这样每次工具调用链路是否完整一眼就能看出来。比只看最终答案靠谱得多。