1. 为什么大模型需要 MCP 协议才能自己调用工具你可能已经习惯了这样的场景问大模型“北京天气怎么样”它要么说“我无法获取实时数据”要么凭训练语料编一个温度给你。问题不在于模型不够聪明而在于它和外部工具之间缺一根标准化的“数据线”。MCP 协议Model Context Protocol要解决的正是这件事——它把工具调用抽象成一套统一的客户端-服务器约定让模型能像插 U 盘一样接入天气查询、文件读写、数据库检索这些能力。MCP 协议是什么一句话概括它是大模型与外部工具之间的通用接口规范底层跑的是 JSON-RPC 2.0。能做什么让模型在对话过程中自主决定“我现在该调哪个工具、传什么参数”而不是靠你在 prompt 里硬编码调用逻辑。适合谁适合正在做本地 AI 工具接入、想让 Agent 真正干活的开发者尤其是用 LangChain、Claude Code、Cline 这类框架的人。我试过把工具调用逻辑全塞进 prompt 里结果模型经常把参数格式写错或者该调工具的时候直接编答案。MCP 的价值在于把“工具描述”和“调用协议”从 prompt 里剥离出来交给标准化的服务端注册。模型只需要知道有哪些工具可用剩下的路由、参数校验、结果注入由 MCP 客户端和服务器完成。从架构上看MCP 采用经典的客户端-服务器模式。目前主流传输方式有两种Stdio 适合本地进程间通信Streamable HTTP 适合远程网络场景。早期还支持过 SSE但因为双端点架构复杂、和云原生无服务器环境兼容性差官方已经弃用。所以你现在选型时本地工具用 Stdio跨机器或容器化部署用 Streamable HTTP别再去碰 SSE 了。实际工作流程是这样的你问“北京天气怎么样”大模型分析意图后决定调用 get_weather 工具。但模型本身不能直接调工具实际是 AI 应用拦截这个请求通过 MCP 客户端转发给对应的服务器端。服务器执行真正的查询把结果返回给客户端客户端再注入回对话。最后模型基于真实数据生成自然语言回答。整个过程对用户透明你感受到的只是一个流畅的问答。理解了原理接下来动手跑通一次完整调用。我会给出可复制的 settings.json 和 config.toml 配置骨架说明 TaoToken 统一 Key/API 通道的接入方式并附上工具调用链路的验证动作与排错清单。目标很明确让你在本地环境里从零跑通一次“模型自主调用 MCP 工具”的完整链路。2. TaoToken 前置准备统一 Key 与 API 通道接入在写 MCP 服务器和客户端之前先把模型通道准备好。MCP 负责工具调用但模型本身还是要通过一个 API 来访问。这里我用 TaoToken 作为统一入口原因是它把多家模型的 Key 和 Base URL 收敛成一套配置省得你在 MCP 客户端、Claude Code、Cline 之间来回切换环境变量。TaoToken 是什么它是一个模型 API 聚合通道提供统一的 Key 和 Base URL让你用同一套凭证访问不同模型。能做什么在 MCP 场景里它主要解决两件事一是模型调用的鉴权和路由二是让 MCP 客户端配置保持干净不用为每个模型单独维护一套环境变量。适合谁适合需要频繁切换模型做工具调用测试的开发者。先拿 Key。访问 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建一个新 Key。建议按项目命名比如 mcp-weather-test方便后续排查。创建后复制保存页面只显示一次。拿到 Key 后记下两个核心参数参数值说明Base URLhttps://taotoken.net/api所有模型请求的统一入口API Key你刚创建的 Key放在环境变量或配置文件里如果你用的是 Claude Code 或 Cline 这类工具它们各自有配置文件。Claude Code 的配置在~/.claude/settings.jsonCline 在 VS Code 的 settings.json 里。MCP 客户端这边我推荐用环境变量管理 Key避免硬编码进代码。在项目根目录创建.env文件TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELqwen-plus这里模型名按你实际用的填。TaoToken 支持多家模型具体 Model ID 可以在模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite测试确认。我一般先用对话页面发一条消息确认 Key 和模型名对得上再去写 MCP 代码。如果你打算长期跑编码类 Agent可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它针对高频工具调用场景做了额度优化。不过对于本篇的验证流程按量付费的 Key 就够了。配置骨架方面MCP 客户端读取模型配置的方式取决于你用的框架。LangChain 这边我用init_chat_model配合configurable_fields把 model、api_key、base_url 三个字段暴露成可配置项。这样切换模型时只改环境变量不动代码。一个容易踩的坑Base URL 末尾不要加/v1或/chat/completionsTaoToken 的入口就是https://taotoken.net/api框架会自动拼接路径。我见过有人写成https://taotoken.net/api/v1结果 404。如果你不确定先用 curl 测一下curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:qwen-plus,messages:[{role:user,content:hi}]}返回正常 JSON 就说明通道通了。这一步别跳过后面 MCP 报错时你能快速判断是模型通道问题还是工具调用问题。3. 可复制配置settings.json 与 config.toml 骨架这一节给你两套配置骨架一套给 Claude Code / Cline 这类用 JSON 的工具一套给 Codex 或需要 TOML 的场景。核心是三件套Base URL、Key、Model ID缺一不可。先看 Claude Code 的~/.claude/settings.json。如果你用 Claude Code 接入 MCP配置长这样{ mcpServers: { weather: { command: python, args: [/Users/yourname/projects/mcp-weather/mcp_weather_stdio.py], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } }, model: { provider: openai, base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: qwen-plus } }注意mcpServers里的command和args是 Stdio 模式的启动方式。Claude Code 会以子进程方式拉起这个 Python 脚本通过标准输入输出通信。env里把 TaoToken 的 Key 和 Base URL 传进去服务器端如果需要调模型就能直接用。如果你用 Cline配置在 VS Code 的 settings.json 里结构类似但字段名不同{ cline.mcpServers: { weather: { command: python, args: [/Users/yourname/projects/mcp-weather/mcp_weather_stdio.py], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } }, cline.apiProvider: openai, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiApiKey: sk-你的Key, cline.openAiModelId: qwen-plus }Cline 的 MCP 配置字段是cline.mcpServers模型配置是cline.openAiBaseUrl这一组。三件套同样齐全Base URL、Key、Model ID。再看 Codex 的~/.codex/auth.json和config.toml。Codex 用 TOML 管理模型配置auth.json 存凭证{ OPENAI_API_KEY: sk-你的Key }对应的~/.codex/config.tomlmodel qwen-plus model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key OPENAI_API_KEY [mcp_servers.weather] command python args [/Users/yourname/projects/mcp-weather/mcp_weather_stdio.py] [mcp_servers.weather.env] TAOTOKEN_API_KEY sk-你的Key TAOTOKEN_BASE_URL https://taotoken.net/apiCodex 的model_providers段定义自定义 providerbase_url指向 TaoTokenenv_key指定从哪个环境变量读 Key。mcp_servers段注册 MCP 服务器Stdio 模式同样用 command args。如果你用 Streamable HTTP 模式配置改成 URL 形式{ mcpServers: { weather: { url: http://127.0.0.1:8000/mcp, transport: streamable_http, env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }Streamable HTTP 模式下MCP 服务器是独立进程你先手动启动它客户端通过 HTTP 连接。Stdio 模式则是客户端拉起服务器进程生命周期绑定。配置写完后检查三件事Base URL 是不是https://taotoken.net/api不带多余路径、Key 有没有复制错、Model ID 是不是 TaoToken 支持的。这三件套任何一项错了后面都会报鉴权或模型不存在。4. 验证请求从 MCP 服务器到工具调用链路配置就绪后开始验证。我分三步走先单独跑通 MCP 服务器再用客户端发现工具最后让模型自主调用。第一步写 MCP 服务器。用 FastMCP 框架代码很短FastMCP 天气服务 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]} else: return f{city}天气晴气温 22°C湿度 50% if __name__ __main__: mcp.run(transportstdio)mcp.tool()装饰器把get_weather注册成 MCP 工具函数签名和 docstring 会自动生成工具 schema。transportstdio表示用标准输入输出通信适合本地进程间调用。如果你想用 HTTP 模式改成mcp.run(transportstreamable-http, host127.0.0.1, port8000)。先单独测服务器能不能启动python mcp_weather_stdio.py如果没报错进程会挂起等待输入说明服务器正常。按 CtrlC 退出。第二步写客户端发现工具。用langchain-mcp-adapters的MultiServerMCPClientLangChain MCP 客户端 - 连接 FastMCP 天气服务 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_mcp_adapters.client import MultiServerMCPClient load_dotenv() prefix TAOTOKEN 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: {command: python, args: [mcp_weather_stdio.py]}} ) mcp_tools await client.get_tools() print(f发现 MCP 工具: {[t.name for t in mcp_tools]}) calculate CalculateTool() agent create_agent( modelmodel, tools[calculate] mcp_tools, system_prompt你是一个助手会用工具计算和查询天气。, debugTrue ) queries [ 北京天气怎么样, 计算 2024*12500, ] 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省去大量胶水代码。第三步运行客户端python mcp_client.py预期输出先打印发现 MCP 工具: [get_weather]然后对“北京天气怎么样”这个问题Agent 会自动调用get_weather工具返回“北京天气晴天气温 25°C湿度 40%”。debugTrue会打印工具调用的中间过程你能看到模型决定调哪个工具、传了什么参数。如果一切正常你已经跑通了一次完整的 MCP 工具调用链路模型分析意图 → 决定调用 get_weather → MCP 客户端转发请求 → 服务器执行 → 结果注入对话 → 模型生成回答。5. 常见报错排查401、local proxy failed、reading choices这一节对照真实报错给你排查清单。MCP 链路涉及模型通道、MCP 服务器、客户端三层报错信息往往指向不同层需要逐层定位。401 Unauthorized。这是最常见的鉴权错误出现在模型调用层。原因通常是 Key 不对、Base URL 不对、或者环境变量没加载。排查步骤先确认.env文件里的TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL拼写正确再用 curl 直接测模型通道见第 2 节的 curl 命令如果 curl 通了但代码报 401检查load_dotenv()有没有在init_chat_model之前调用。我踩过的坑是把 Key 写进了config.toml但环境变量没导出Codex 读的是env_key指定的变量结果读到空值。local proxy failed。这个报错通常出现在 MCP 客户端连接服务器时。Stdio 模式下客户端会拉起服务器子进程如果command或args路径不对就会报 local proxy failed。排查确认args里的 Python 脚本路径是绝对路径或者相对于客户端工作目录的正确路径确认python命令在 PATH 里或者用python3确认脚本本身能独立运行先手动python mcp_weather_stdio.py测一下。Streamable HTTP 模式下这个报错说明客户端连不上http://127.0.0.1:8000/mcp检查服务器有没有启动、端口有没有被占用。reading choices 相关报错。这类错误出现在模型返回结果解析阶段通常是模型返回的 JSON 格式不符合预期。原因可能是 Model ID 写错了TaoToken 路由到了不支持的模型或者模型本身不支持工具调用function calling。排查确认 Model ID 在 TaoToken 支持列表里换一个明确支持工具调用的模型测试比如 qwen-plus 或 gpt-4o-mini检查init_chat_model的model_provider是不是openaiTaoToken 兼容 OpenAI 格式。OAuth 相关报错。如果你用 Claude Code 接入可能会遇到 OAuth token 过期或配置冲突。Claude Code 有自己的鉴权体系和 TaoToken 的 Key 是两套。排查确认~/.claude/settings.json里model段的api_key填的是 TaoToken Key而不是 Claude 官方 Key如果同时配了官方和 TaoToken检查有没有字段冲突。必要时清空 Claude Code 的缓存重新登录。工具被发现但模型不调用。这不是报错但很常见。现象是get_tools()返回了工具列表但模型回答时直接编答案不调工具。原因通常是 system prompt 没强调用工具或者模型能力不够。排查在 system prompt 里明确写“查询天气必须调用 get_weather 工具”换一个工具调用能力更强的模型检查工具描述docstring是否清晰模型靠描述判断该不该调。MCP 服务器启动后立即退出。Stdio 模式下服务器进程应该挂起等待输入。如果立即退出说明mcp.run()之前的代码抛异常了。排查在mcp.run()前加 print 确认执行到哪一步检查 FastMCP 版本pip install fastmcp装最新版确认transport参数拼写正确是stdio不是std。Streamable HTTP 模式连接超时。检查服务器host是不是127.0.0.1客户端 URL 是不是http://127.0.0.1:8000/mcp。注意路径末尾的/mcp不能少FastMCP 默认挂载在/mcp。如果服务器在容器里host 要改成0.0.0.0客户端用宿主机 IP。排查时记住分层原则模型通道问题看 401 和 reading choicesMCP 连接问题看 local proxy failed 和超时工具调用问题看模型行为。每层单独验证别混在一起调。6. 长期编码与 Agent 场景的接入建议跑通一次调用只是起点。如果你打算把 MCP 用在长期编码或 Agent 场景有几个实践建议。第一工具粒度别太细。我一开始把每个文件操作都注册成独立工具结果模型在“读文件→改内容→写回”这个链路里频繁切换工具token 消耗大且容易出错。后来改成组合工具比如edit_file(path, old, new)一次完成读改写调用次数降了一半。第二Stdio 和 Streamable HTTP 按场景选。本地开发用 Stdio进程生命周期绑定调试方便。部署到服务器或容器用 Streamable HTTP服务器独立运行多个客户端可以共享。别在本地用 HTTP 模式多一层网络开销没必要。第三模型通道用统一入口。TaoToken 的价值在长期场景里更明显你换模型时只改 Model IDBase URL 和 Key 不动。MCP 客户端的配置保持稳定减少环境变量漂移。如果你跑编码类 AgentCoding Plan 的额度模型比按量付费更适合高频调用。第四给工具调用加日志。debugTrue在开发阶段够用但生产环境建议把工具调用记录写到文件方便回溯。LangChain 的 callback 机制可以拦截工具调用事件记录工具名、参数、返回值和耗时。第五验证链路要可重复。我习惯写一个verify_mcp.py脚本每次改配置后跑一遍先 curl 测模型通道再get_tools()测工具发现最后发一条固定 query 测端到端调用。三步都过才算配置生效。这个脚本比手动点来点去可靠得多。如果你还没拿 Key去 API Keys 页面创建一个https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各框架的配置示例。模型对话页面可以用来快速验证 Model ID 和 Key 是否匹配https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite。最后说一个实际经验MCP 工具调用的稳定性一半取决于模型能力一半取决于工具描述。docstring 写得越清楚模型判断该不该调、传什么参数就越准。我见过同一个工具改了一版 docstring 后调用成功率从 60% 提到 90%。所以别在工具描述上偷懒那是模型唯一的判断依据。