1. 从“模型只会聊天”到“模型自己动手”MCP 协议到底解决了什么很多人第一次接触 MCP 协议是因为遇到一个很具体的尴尬模型能告诉你“北京今天大概 25 度”但你心里清楚它是猜的你让它读一下本地某个日志文件它只能礼貌地说“我无法访问你的文件系统”。大模型本身是个封闭的文本生成器它没有手也没有眼睛能做什么完全取决于外面那层应用给它接了什么。MCPModel Context Protocol要解决的就是这个“接什么、怎么接”的标准化问题。你可以把它理解成 AI 应用和外部工具之间的一份“插座协议”以前每个工具都要写一套胶水代码A 框架的天气插件搬到 B 框架就得重写现在只要工具按 MCP 规范注册成一个 server任何支持 MCP 的客户端都能即插即用。它底层走的是 JSON-RPC 2.0传输上目前主流是两种——Stdio 适合本地进程间通信Streamable HTTP 适合远程网络场景。早期那套 SSE 双端点方案因为架构复杂、和云原生无服务器环境配合别扭官方已经弃用了所以你现在看到的新教程基本都围绕这两种传输展开。这篇文章面向的是想快速跑通“大模型自主调用工具”最小闭环的开发者。我会用一个天气查询工具做例子把工具注册、调用触发、结果回传这条链路完整走一遍同时用 TaoToken 的统一 Key 把模型调用这一环接上避免你在多个平台的 Key 之间来回切换。读完你应该能拿到一份可以直接复制运行的 MCP 服务端配置以及一次成功调用和一次失败调用的对照排查过程。先说清楚 MCP 的工作流不然后面配置容易懵。当你问“北京天气怎么样”模型先分析意图决定要调用get_weather这个工具。但关键点是模型自己并不能真的去调工具。真正发生的是——AI 应用拦截了这个调用意图通过 MCP 客户端转发给对应的 MCP 服务器服务器执行真正的查询把结果返回给客户端客户端再把结果注入回对话上下文最后模型基于这份真实数据生成一句自然语言回答。整个过程对用户透明你感受到的只是一个流畅问答但背后已经完成了一次“模型决策 外部执行 结果回填”的闭环。这也是为什么 MCP 值得单独拿出来讲它把“模型想调工具”和“工具真的被执行”这两件事解耦了。模型只负责输出结构化的调用意图执行权牢牢握在你的应用手里安全边界清晰。接下来我们就从环境准备开始把这条链路搭起来。2. TaoToken 统一 Key 前置一个 Key 打通模型调用链路在动手写 MCP 代码之前得先把“模型从哪来”这件事定下来。MCP 负责的是工具调用链路但模型本身的推理请求还是要发到某个兼容 OpenAI 接口的服务上。如果你同时用几家模型Key、Base URL、模型名三套配置散落在不同文件里调试 MCP 的时候一旦报错你很难判断是工具链路的问题还是模型接入的问题。TaoToken 在这里的角色就是统一入口它提供兼容 OpenAI 规范的 API你拿一个 Key配一个 Base URL就能在 MCP 客户端里通过init_chat_model这类方式调用模型。这样 MCP 工具链路的变量就被隔离出来了——模型接入是稳定的出问题基本能定位到工具注册或传输配置上。你需要准备三样东西我把它叫做“三件套”后面所有配置都围绕它展开配置项说明示例值Base URL模型 API 的请求地址https://taotoken.net/apiAPI Key统一鉴权凭证在控制台创建形如sk-xxxxModel ID具体调用的模型标识按你开通的模型填写如qwen-plus获取方式很直接登录官网后进入控制台在 API Keys 页面创建一个新 Key。这里有个小细节创建后立刻复制保存页面刷新后完整 Key 不会再明文展示。模型 ID 则在你开通的模型列表里能看到填的时候要和平台上的标识完全一致大小写都别错。拿到三件套后建议先单独验证模型接口通不通再去接 MCP。这一步能帮你排除掉一大半“看起来像 MCP 报错、其实是 Key 或模型名写错”的问题。验证方式可以用最朴素的 curlcurl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: qwen-plus, messages: [{role: user, content: 只回复两个字通了}] }如果返回里能看到choices字段和正常内容说明模型接入这一环没问题可以放心进入 MCP 部分。如果这里就报 401那先别碰 MCP回去检查 Key 是否复制完整、有没有多余空格。我试过把 Key 末尾的换行符一起粘进环境变量结果排查了半小时这种坑很典型。把三件套写进.env文件后面代码直接读环境变量既安全又方便切换# .env QWEN_API_KEYsk-你的Key QWEN_BASE_URLhttps://taotoken.net/api QWEN_MODELqwen-plus注意变量名前缀我用的是QWEN这是为了和后面init_chat_model里的config_prefix对应上。你可以改成任意前缀只要前后一致就行。环境变量这一步做完模型侧的准备工作就结束了接下来进入真正的 MCP 服务端搭建。3. 可复制配置FastMCP 服务端 LangChain 客户端完整片段这一节是全文的核心我会把服务端和客户端两份代码都给全你复制后改一下环境变量就能跑。先装依赖pip install fastmcp langchain-mcp-adapters langchain langchain-community python-dotenvfastmcp用来快速构建 MCP 服务器langchain-mcp-adapters让 LangChain 能连接并使用 MCP 工具。两个包分工明确一个负责“把工具暴露出去”一个负责“把工具接进来”。先写服务端。我们创建一个 FastMCP 实例用mcp.tool()装饰器把get_weather注册成 MCP 工具。这个装饰器会自动读取函数的类型注解和 docstring生成工具 schema——也就是说你写的 docstring 会直接变成模型判断“该不该调这个工具”的依据所以描述要写清楚。FastMCP 天气服务 - mcp_weather_server.py from fastmcp import FastMCP mcp FastMCP(天气服务) mcp.tool() def get_weather(city: str) - str: 获取指定城市的天气信息 Args: city: 城市名称如 北京、上海、广州 weather_data { 北京: 晴天气温 25°C湿度 40%, 上海: 多云气温 28°C湿度 65%, 广州: 小雨气温 30°C湿度 80%, 深圳: 阴天气温 29°C湿度 75%, } if city in weather_data: return f{city}天气{weather_data[city]} return f{city}天气晴气温 22°C湿度 50% if __name__ __main__: mcp.run(transportstreamable-http, host127.0.0.1, port8000) # 本地进程间通信可切换为 # mcp.run(transportstdio)这里选streamable-http是因为它方便你单独启动、单独调试用浏览器或 curl 都能探活。如果你的场景是本地进程间通信把最后一行换成stdio模式即可客户端配置也要相应改成 command 形式。再写客户端。这是整个实现的重点也是 MCP 工具真正被 Agent 用起来的地方LangChain MCP 客户端 - mcp_client.py import os import asyncio from dotenv import load_dotenv from langchain.agents import create_agent from langchain.chat_models import init_chat_model from langchain_core.tools import BaseTool from langchain_community.tools import WriteFileTool, ReadFileTool, ListDirectoryTool from langchain_mcp_adapters.client import MultiServerMCPClient load_dotenv() prefix QWEN model init_chat_model( model_provideropenai, configurable_fields[model, api_key, base_url], config_prefixprefix ).with_config({ configurable: { f{prefix}_model: os.getenv(f{prefix}_MODEL), f{prefix}_api_key: os.getenv(f{prefix}_API_KEY), f{prefix}_base_url: os.getenv(f{prefix}_BASE_URL), } }) class CalculateTool(BaseTool): name: str calculate description: str 计算数学表达式的值 def _run(self, expression: str) - str: try: return f计算结果: {eval(expression)} except Exception as e: return f计算错误: {str(e)} async def _arun(self, expression: str) - str: return self._run(expression) async def main(): client MultiServerMCPClient( { weather: { url: http://127.0.0.1:8000/mcp, transport: streamable_http, } # stdio 模式 # {weather: {command: python, args: [mcp_weather_server.py]}} } ) mcp_tools await client.get_tools() calculate CalculateTool() write_file WriteFileTool() read_file ReadFileTool() list_dir ListDirectoryTool() agent create_agent( modelmodel, tools[calculate, write_file, read_file, list_dir] mcp_tools, system_prompt你是一个助手会用工具计算、读写文件、列出目录、查询天气。, debugTrue, ) queries [ 北京天气怎么样, 计算 2024*12500然后把结果保存到 result.txt, 读取 result.txt 的内容, ] for q in queries: print(f\n问{q}) result await agent.ainvoke( {messages: [{role: user, content: q}]} ) print(f答{result[messages][-1].content}) if __name__ __main__: asyncio.run(main())关键的一步是await client.get_tools()。这个方法会自动发现服务器上所有可用的 MCP 工具并把它们转换成 LangChain 能识别的工具格式。这一步省掉了手动定义工具 schema 的麻烦——你不用再手写 JSON Schema 描述参数FastMCP 那边装饰器已经帮你生成了。随后把这些 MCP 工具和自定义工具一起传给create_agentAgent 就具备了调用 MCP 工具的能力。配置里有个容易忽略的点MultiServerMCPClient的 key这里是weather只是客户端内部的服务器别名和 FastMCP 实例名“天气服务”不需要一致。真正决定连接的是url和transport。HTTP 模式下 URL 要带上/mcp路径这是 Streamable HTTP 的端点约定漏了会直接 404。4. 验证请求一次成功调用与一次失败调用的对照代码写完先启动服务端再跑客户端。服务端启动后你会看到类似Uvicorn running on http://127.0.0.1:8000的日志说明 MCP 服务已经在监听。这时候可以先用 curl 探一下端点是否活着curl -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,id:1,method:tools/list,params:{}}如果返回里能看到get_weather这个工具名和它的参数描述说明工具注册成功、端点可达。这一步很值得做因为它把“服务端问题”和“客户端问题”提前分开了。接着跑客户端。成功的情况下你会看到debugTrue打印出 Agent 的推理过程模型先判断“北京天气”需要调用工具输出一个 tool callMCP 客户端转发给服务端服务端返回天气字符串客户端把结果注入对话模型再生成最终回答。终端输出大致是这样问北京天气怎么样 答北京今天是晴天气温 25°C湿度 40%适合外出。注意这个回答里的数据来自get_weather的返回值不是模型编的。你可以把服务端里的“北京”改成“晴天转暴雨”再跑一次如果回答跟着变就证明工具调用链路真的通了——这是比看日志更硬的验证方式。现在看失败对照。最常见的失败是 401通常发生在模型调用这一环报错长这样openai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}这说明 TaoToken 的 Key 有问题要么没加载进环境变量要么复制时带了空格。检查.env是否被load_dotenv()正确读取可以在代码里临时打印os.getenv(QWEN_API_KEY)[:8]确认前缀。第二种失败是连接类报错比如httpx.ConnectError: [Errno 111] Connection refused或者日志里出现local proxy failed这类字样。这基本是 MCP 服务端没起来或者客户端 URL 写错了。确认服务端进程还在、端口是 8000、URL 带了/mcp。如果你把服务端跑在容器里127.0.0.1在客户端容器内指向的是它自己得换成服务名或宿主机地址。第三种是解析类报错典型的是reading choices相关比如TypeError: Cannot read properties of undefined (reading choices)这通常意味着模型返回体不是预期的 OpenAI 格式可能是 Base URL 配错了、请求打到了非兼容端点或者模型 ID 填了个不存在的名字导致返回了错误结构。回去核对三件套尤其是 Base URL 结尾不要多加/v1之类的路径除非平台明确要求。还有一种容易被误判的情况工具没被调用模型直接编了个天气回答。这不是报错但结果不对。原因通常是工具描述不够清晰模型没意识到该调它。把get_weather的 docstring 写得更明确比如加上“当用户询问某城市天气时必须调用此工具”命中率会明显提升。5. 本篇常见错排查从报错信息反推配置问题把上面几类错误系统化整理一下方便你对照排查。MCP 链路的报错有个特点它横跨模型接入、工具注册、传输连接三层同一句报错可能来自不同层所以定位时要按“先模型、再服务端、后客户端”的顺序排除。第一层是模型接入。401 和reading choices都属于这一层。前者是鉴权失败后者多半是响应结构不对。排查动作单独用 curl 打一次/api/chat/completions确认三件套正确。如果 curl 通了但代码不通那就是环境变量没加载检查.env路径和变量名大小写。init_chat_model的config_prefix是QWEN那环境变量就必须是QWEN_API_KEY、QWEN_BASE_URL、QWEN_MODEL少一个都会出问题。第二层是 MCP 服务端。Connection refused、404、local proxy failed属于这一层。排查动作确认服务端进程在跑curl探活/mcp端点能返回tools/list。如果探活失败看服务端启动日志有没有报端口占用如果探活成功但客户端连不上检查客户端 URL 是否和mcp.run里的 host、port 一致。stdio 模式下没有 URL要检查command和args能否在客户端环境里执行路径最好用绝对路径。第三层是工具调用本身。表现是模型没调工具、或者调了但参数不对。排查动作打开debugTrue看 Agent 输出的 tool call 里参数是什么。如果参数是空的或类型不对回去检查 FastMCP 函数的类型注解——city: str这种注解是 schema 的来源写成city不带类型生成的 schema 可能不完整。另外工具名不要用中文或特殊字符get_weather这种下划线命名最稳。还有一个隐蔽的坑同时注册了多个工具模型选错了。比如你既有get_weather又有calculate问天气时模型却去调计算。这通常是工具描述边界不清。解决办法是在 docstring 里写清楚适用场景必要时在 system prompt 里补一句“查询天气只能用 get_weather”。工具不是越多越好最小可用 Demo 阶段建议先跑通一个再逐步加。如果你在 Claude Code 或 Cline 这类支持 MCP 的客户端里配置三件套同样要写全Base URL 填https://taotoken.net/apiKey 填你的统一 KeyModel ID 填对应模型标识。有些客户端用settings.json或auth.json存配置格式不同但字段含义一致别只填了 Key 忘了 Base URL那样请求会打到默认端点直接失败。6. 把链路收进一个 Key后续可以怎么扩展跑通这个最小 Demo 之后你会发现 MCP 真正的价值不在“查天气”这种玩具场景而在于它把工具接入变成了可复用资产。同一个get_weather服务端换个客户端照样能用你新写一个查数据库的 MCP server也不用改 Agent 的核心逻辑只要在MultiServerMCPClient里加一个条目就行。工具和模型解耦这是它比传统插件方案更省心的地方。模型侧用 TaoToken 统一 Key 的好处在扩展阶段会更明显。当你从单模型切到多模型对比、或者给不同 Agent 配不同模型时Base URL 和鉴权方式不变只改 Model ID 就能切换MCP 工具链路完全不用动。这种“模型可换、工具不动”的结构调试起来变量少很多。如果你想继续往下走几个方向比较自然一是把streamable-http服务端部署到内网某台机器客户端通过内网地址连接验证远程传输二是给 MCP 服务端加鉴权避免工具被随意调用三是把多个工具拆成多个 MCP server用MultiServerMCPClient的多条目配置统一管理。每一步都建议先用 curl 或 debug 日志确认单点通了再往下叠不然报错会混在一起很难拆。最后留一个实用习惯每次改完配置先跑tools/list探活再跑客户端。这个顺序能帮你把大部分问题挡在模型调用之前。工具调用链路一旦跑顺后面接什么工具、换什么模型都只是填空而已。