1. 为什么 LLM 工具调用要盯住 MCP Streamable HTTP 模式如果你正在做 LLM 工具调用大概率绕不开 MCPModel Context Protocol。它解决的是一个很实际的问题模型本身只会生成文本但你想让它查数据库、读文件、调内部接口就得有一套标准协议把「模型想干什么」翻译成「服务端能执行什么」。MCP 就是干这个的。早期 MCP 走的是 HTTPSSE 模式客户端先发一个 GET 建立 SSE 长连接服务端再通过这条连接推消息。这套机制能用但在真实工程里问题不少长连接容易被中间层掐断、断线重连要自己处理 Last-Event-ID、多实例部署时会话粘性问题很烦。Streamable HTTP 模式就是对这些痛点的标准化升级它把消息统一收敛到单个/mcp路由上POST 发 JSON-RPC 请求GET 可选监听 SSE 流会话状态通过Mcp-Session-Id头来追踪断点续传也支持。这篇文章要解决的核心场景是LLM 通过 MCP 协议 Streamable HTTP 模式完成工具调用并且用 TaoToken 作为统一的 Key/API 通道接入。适合谁看三类人一是正在给 Agent 接工具、被 SSE 长连接折腾过的后端同学二是想用统一 API 通道管理多个模型 Key、不想每个项目都散落一堆密钥的开发者三是刚接触 MCP、想找一个能跑通的完整示例照着做的小白。我会给出可复制的 MCP 服务端配置、Streamable HTTP 端点与鉴权参数然后演示一次工具调用请求的完整验证动作最后把返回结果逐字段核对一遍。全程用 TaoToken 的 API 通道https://taotoken.net/api作为模型侧入口服务端工具用 Python 的 FastMCP 写客户端用官方mcp库的streamablehttp_client。你跟着敲一遍能拿到一个真实可用的工具调用链路。先说清楚一个概念区分避免后面混淆MCP 服务端负责「暴露工具」模型侧负责「决定调哪个工具」。TaoToken 在这里的角色是模型侧的 API 通道它不替代 MCP 服务端而是让你在客户端调用模型时用一套统一的 Key 和 Base URL 去访问模型能力。工具调用的决策由模型产生执行由 MCP 服务端完成两者通过 MCP 协议通信。理解了这个分工后面的配置就不会乱。2. TaoToken 前置准备Key、Base URL 与模型 ID 三件套在写代码之前先把模型侧的三件套准备好。任何接入类问题90% 的报错都出在这三个值上Base URL、API Key、Model ID。我见过太多人把 Base URL 写成官网首页、把 Key 复制多了空格、把 Model ID 写成展示名然后对着 401 或 404 发呆。第一步拿到 API Key。访问 TaoToken 控制台的 API Keys 页面https://taotoken.net/console/api-keys新建一个 Key。建议按项目命名比如mcp-tool-demo方便后面轮换和排查。Key 只在创建时完整显示一次复制后先存到本地环境变量别直接硬编码进代码提交到仓库。第二步确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这里不带任何查询参数就是干净的 API 根路径。很多 OpenAI 兼容的 SDK 会自动在 Base URL 后面拼/v1/chat/completions之类的路径所以你要填的是根不是完整端点。第三步选 Model ID。在模型对话页面https://taotoken.net/models能看到当前可用的模型列表挑一个支持工具调用function calling / tool use的模型。不是所有模型都支持工具调用选错了会在返回里看不到tool_calls字段或者直接报参数不支持。建议先用一个明确标注支持工具调用的模型做验证。把这三个值写进环境变量后面代码直接读export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODEL_ID你选的支持工具调用的模型ID如果你用的是 Claude Code 这类工具配置会落在settings.json里如果用 Codex会落在auth.json。不管哪种核心都是这三个值。下面给一个通用的 JSON 配置片段路径按你实际工具的约定放{ base_url: https://taotoken.net/api, api_key: sk-你的实际Key, model: 你选的支持工具调用的模型ID }注意Base URL 结尾不要加/v1也不要加/chat/completions。SDK 会自己拼。加了反而会变成/api/v1/v1/...这种重复路径直接 404。如果你需要长期跑编码类 Agent 任务可以考虑 Coding Planhttps://taotoken.net/coding-plan它在额度管理上更适合高频调用场景。但本文的验证流程用普通 API Key 就够了先把链路跑通再考虑套餐。这里再强调一个容易踩的坑不要把 MCP 服务端的地址和 TaoToken 的 Base URL 搞混。MCP 服务端是你自己起的工具服务地址类似http://localhost:8050/mcpTaoToken 的 Base URL 是模型 API 的入口。两者是完全不同的东西一个负责执行工具一个负责生成决策。配置时分开管理别写进同一个变量。3. 可复制配置FastMCP 服务端 Streamable HTTP 客户端这一节是全文的技术核心给出两份可直接运行的代码服务端注册工具并以 Streamable HTTP 模式启动客户端通过streamablehttp_client连接并调用工具。代码我实测过Python 3.10 环境直接跑。先装依赖pip install mcp[cli] httpx服务端代码server.pyfrom mcp.server.fastmcp import FastMCP # 创建 MCP 服务端无状态 HTTP 模式适合横向扩展 mcp FastMCP(MyServer, host127.0.0.1, port8050, stateless_httpTrue) mcp.tool() def say_hello(name: str) - str: 向指定名字打招呼 return fHello, {name}! Nice to meet you! mcp.tool() def add(a: int, b: int) - int: 计算两个整数之和 return a b if __name__ __main__: # 使用 Streamable HTTP 传输模式启动 mcp.run(transportstreamable-http)这里有几个关键点。stateless_httpTrue表示服务端不维护会话状态每次请求独立处理不返回Mcp-Session-Id也不要求客户端持有。这种模式适合无状态部署、多实例横向扩展。如果你需要会话上下文追踪把它设为False服务端会为每个客户端维护 Session日志里能看到Created new transport with session ID: xxx和Terminating session: xxx两条记录。transportstreamable-http是启动 Streamable HTTP 模式的关键参数服务端会监听/mcp路径统一处理 POST 和 GET 请求。客户端代码client.pyimport asyncio from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client async def main(): # 连接 MCP 服务端的 Streamable HTTP 端点 async with streamablehttp_client(http://localhost:8050/mcp) as ( read_stream, write_stream, get_session_id, ): async with ClientSession(read_stream, write_stream) as session: await session.initialize() # 列出服务端暴露的所有工具 tools_result await session.list_tools() print(Available tools:) for tool in tools_result.tools: print(f- {tool.name}: {tool.description}) # 调用 add 工具 result await session.call_tool(add, arguments{a: 1, b: 2}) print(f1 2 {result.content[0].text}) if __name__ __main__: asyncio.run(main())客户端的streamablehttp_client返回三个值读流、写流、获取 session id 的函数。ClientSession把读写流包起来initialize()完成握手list_tools()拉取工具清单call_tool()发起实际调用。返回的result.content[0].text就是工具执行结果注意它不是裸数字而是被包在 JSON-RPC 响应对象里的内容块。如果你要把模型侧也接进来让 LLM 决定调哪个工具可以在客户端里加一段调用 TaoToken API 的逻辑把list_tools()的结果转成模型的 tools 参数模型返回tool_calls后再路由到call_tool()。这部分逻辑因框架而异核心是保持 Base URL、Key、Model ID 三件套一致。提示服务端和客户端建议分两个终端跑先启动server.py看到监听日志后再跑client.py。如果客户端报连接拒绝先确认服务端是否真的起来了。4. 验证请求从 list_tools 到 call_tool 的完整结果核对配置写完最关键的一步是验证。很多人代码跑起来了但没核对返回结果线上出问题才发现工具根本没被调用。这一节把验证动作拆成三步每步都有明确的预期结果。第一步启动服务端。在终端执行python server.py正常会看到类似Uvicorn running on http://127.0.0.1:8050的日志。因为用了stateless_httpTrue日志里不会出现 session ID 相关的记录。如果你把stateless_http去掉默认False日志会多出Created new transport with session ID: 82a3519c341d4088a9c4c0856b991480和Terminating session: 82a3519c341d4088a9c4c0856b991480两条这说明服务端在为每个客户端维护会话。两种模式都能用区别在于是否需要状态追踪。第二步运行客户端。执行python client.py预期输出Available tools: - say_hello: 向指定名字打招呼 - add: 计算两个整数之和 1 2 3核对三个点工具清单里是否包含你注册的所有工具、描述是否和 docstring 一致、call_tool的返回是否是3。如果工具清单为空说明服务端注册没生效如果返回不是3检查arguments的键名是否和函数参数名一致。第三步用 curl 直接打一次 Streamable HTTP 端点验证协议层。这一步能帮你区分「是 MCP 逻辑问题」还是「是网络/协议问题」curl -X POST http://127.0.0.1:8050/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }预期返回一个 JSON-RPC 响应result.tools数组里包含say_hello和add。注意Accept头必须同时包含application/json和text/event-stream这是 Streamable HTTP 模式的协议要求缺了会返回 406。再打一次工具调用curl -X POST http://127.0.0.1:8050/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: add, arguments: {a: 1, b: 2} } }预期返回里result.content[0].text是3。到这里MCP 服务端的工具调用链路就验证完了。接下来把模型侧接进来用 TaoToken 的 API 发一次带 tools 参数的请求看模型是否返回tool_calls。如果模型返回了工具调用意图说明整条链路模型决策 → MCP 执行是通的。注意核对返回时不要只看 HTTP 状态码 200 就认为成功。JSON-RPC 的错误是包在响应体里的error字段非空才是真失败。养成看result和error两个字段的习惯。5. 本篇常见错排查401、local proxy failed 与 reading choices这一节把我在实际接入中遇到的报错按现象归类给出定位思路。这些报错覆盖了模型侧和 MCP 侧两类问题对照着看能省不少时间。401 Unauthorized。这是模型侧最常见的错几乎都是 Key 的问题。三种可能Key 复制时带了首尾空格、Key 已过期或被删除、Key 没有对应模型的权限。排查方法把 Key 打印出来看长度和首尾字符重新在控制台生成一个再试。如果换了新 Key 还是 401检查 Base URL 是否写成了https://taotoken.net/api/带了尾斜杠某些 SDK 对尾斜杠敏感。local proxy failed / connection refused。这是 MCP 客户端连不上服务端的典型报错。先确认服务端进程是否在跑curl http://127.0.0.1:8050/mcp能不能通。如果服务端在跑但客户端连不上检查端口是否被占用、host 是否写成了0.0.0.0而客户端连的是127.0.0.1。还有一种情况是客户端用了localhost但系统解析到了 IPv6 的::1而服务端只监听了 IPv4改成127.0.0.1即可。Error reading choices / 返回体里没有 choices 字段。这是模型侧响应解析失败。原因通常是 Base URL 拼错了路径请求打到了非 API 端点返回的是 HTML 而不是 JSON。检查 Base URL 是否为https://taotoken.net/api不要带/v1或/chat/completions。另外确认 Model ID 拼写正确写错模型名有时会返回一个结构不同的错误体解析器读choices就报错。OAuth / 鉴权头格式错误。如果你用的是 Claude Code 或类似工具鉴权头格式有特定要求。常见错误是把Authorization: Bearer sk-xxx写成了Authorization: sk-xxx少了Bearer前缀。检查配置文件里的 header 拼写注意大小写和空格。工具清单为空但没报错。这是 MCP 侧的问题通常是mcp.tool()装饰器没生效或者函数定义在mcp.run()之后。确保所有工具函数在mcp.run()之前定义并注册。还有一种可能是客户端连到了错误的端点比如连了/sse而不是/mcp。Mcp-Session-Id 相关报错。如果你用了有状态模式stateless_httpFalse客户端需要在后续请求里带上服务端返回的Mcp-Session-Id头。漏带会报会话不存在。如果不想处理这个直接用stateless_httpTrue每次请求独立不需要维护会话 ID。排查顺序建议先 curl 打 MCP 端点确认服务端正常再用 TaoToken 的模型对话页面https://taotoken.net/models单独测一次模型调用确认 Key 正常最后把两者串起来。分段验证比一上来就端到端调试高效得多。6. 把链路固定下来从验证到日常使用的接入建议链路跑通之后下一步是把它变成日常能用的东西。这里给几个实操建议都是踩过坑之后总结的。第一把三件套放进环境变量或密钥管理服务不要硬编码。代码里统一用os.environ.get(TAOTOKEN_API_KEY)读取本地开发用.env线上用平台的密钥管理。这样轮换 Key 时只改一处。第二MCP 服务端的工具描述docstring要写清楚。模型是靠描述来决定调哪个工具的描述模糊会导致误调用。比如add的描述写成「计算两个整数之和」比写成「加法」好得多模型能准确判断参数类型和用途。第三无状态模式优先。除非你确实需要跨请求的会话上下文否则用stateless_httpTrue。它省去了会话管理的复杂度部署时也不用考虑会话粘性多实例随便扩。第四给工具调用加日志。在call_tool前后打点记录工具名、参数、返回、耗时。出问题时这些日志是唯一的线索。MCP 的 JSON-RPC 错误信息有时比较简略自己的日志能补上上下文。第五定期核对模型返回的tool_calls结构。不同模型对工具调用的返回格式略有差异升级模型或换模型后要重新验证一遍解析逻辑。别假设格式永远不变。如果你要把这套链路用到生产建议先在测试环境用固定的几个工具跑一段时间观察调用成功率和延迟再逐步放开工具范围。工具调用本质上是让模型获得了执行能力权限边界要提前划清楚哪些工具能调、参数范围是什么都在服务端做校验不要只依赖模型的判断。需要查 API 细节的时候接入文档在https://taotoken.net/doc里面有完整的端点和参数说明。模型对话页面https://taotoken.net/models可以用来快速验证某个模型是否支持工具调用。API Keys 管理在https://taotoken.net/console/api-keys。这三个页面基本覆盖了日常接入需要的所有信息。最后说一个心态上的建议MCP 工具调用的调试本质上是把「模型决策」和「工具执行」两段分开验证。模型侧用 TaoToken 的对话页面单独测工具侧用 curl 单独测两段都通了再串起来。这样任何一段出问题都能快速定位不会在一堆日志里迷失方向。 
长河君 · 2026/10/7 7:43:27 · 阅读 1.2k LLM 工具调用实战：基于 MCP 协议 Streamable HTTP 模式的 TaoToken 接入指南
1. 为什么 LLM 工具调用要盯住 MCP Streamable HTTP 模式如果你正在做 LLM 工具调用大概率绕不开 MCPModel Context Protocol。它解决的是一个很实际的问题模型本身只会生成文本但你想让它查数据库、读文件、调内部接口就得有一套标准协议把「模型想干什么」翻译成「服务端能执行什么」。MCP 就是干这个的。早期 MCP 走的是 HTTPSSE 模式客户端先发一个 GET 建立 SSE 长连接服务端再通过这条连接推消息。这套机制能用但在真实工程里问题不少长连接容易被中间层掐断、断线重连要自己处理 Last-Event-ID、多实例部署时会话粘性问题很烦。Streamable HTTP 模式就是对这些痛点的标准化升级它把消息统一收敛到单个/mcp路由上POST 发 JSON-RPC 请求GET 可选监听 SSE 流会话状态通过Mcp-Session-Id头来追踪断点续传也支持。这篇文章要解决的核心场景是LLM 通过 MCP 协议 Streamable HTTP 模式完成工具调用并且用 TaoToken 作为统一的 Key/API 通道接入。适合谁看三类人一是正在给 Agent 接工具、被 SSE 长连接折腾过的后端同学二是想用统一 API 通道管理多个模型 Key、不想每个项目都散落一堆密钥的开发者三是刚接触 MCP、想找一个能跑通的完整示例照着做的小白。我会给出可复制的 MCP 服务端配置、Streamable HTTP 端点与鉴权参数然后演示一次工具调用请求的完整验证动作最后把返回结果逐字段核对一遍。全程用 TaoToken 的 API 通道https://taotoken.net/api作为模型侧入口服务端工具用 Python 的 FastMCP 写客户端用官方mcp库的streamablehttp_client。你跟着敲一遍能拿到一个真实可用的工具调用链路。先说清楚一个概念区分避免后面混淆MCP 服务端负责「暴露工具」模型侧负责「决定调哪个工具」。TaoToken 在这里的角色是模型侧的 API 通道它不替代 MCP 服务端而是让你在客户端调用模型时用一套统一的 Key 和 Base URL 去访问模型能力。工具调用的决策由模型产生执行由 MCP 服务端完成两者通过 MCP 协议通信。理解了这个分工后面的配置就不会乱。2. TaoToken 前置准备Key、Base URL 与模型 ID 三件套在写代码之前先把模型侧的三件套准备好。任何接入类问题90% 的报错都出在这三个值上Base URL、API Key、Model ID。我见过太多人把 Base URL 写成官网首页、把 Key 复制多了空格、把 Model ID 写成展示名然后对着 401 或 404 发呆。第一步拿到 API Key。访问 TaoToken 控制台的 API Keys 页面https://taotoken.net/console/api-keys新建一个 Key。建议按项目命名比如mcp-tool-demo方便后面轮换和排查。Key 只在创建时完整显示一次复制后先存到本地环境变量别直接硬编码进代码提交到仓库。第二步确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这里不带任何查询参数就是干净的 API 根路径。很多 OpenAI 兼容的 SDK 会自动在 Base URL 后面拼/v1/chat/completions之类的路径所以你要填的是根不是完整端点。第三步选 Model ID。在模型对话页面https://taotoken.net/models能看到当前可用的模型列表挑一个支持工具调用function calling / tool use的模型。不是所有模型都支持工具调用选错了会在返回里看不到tool_calls字段或者直接报参数不支持。建议先用一个明确标注支持工具调用的模型做验证。把这三个值写进环境变量后面代码直接读export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODEL_ID你选的支持工具调用的模型ID如果你用的是 Claude Code 这类工具配置会落在settings.json里如果用 Codex会落在auth.json。不管哪种核心都是这三个值。下面给一个通用的 JSON 配置片段路径按你实际工具的约定放{ base_url: https://taotoken.net/api, api_key: sk-你的实际Key, model: 你选的支持工具调用的模型ID }注意Base URL 结尾不要加/v1也不要加/chat/completions。SDK 会自己拼。加了反而会变成/api/v1/v1/...这种重复路径直接 404。如果你需要长期跑编码类 Agent 任务可以考虑 Coding Planhttps://taotoken.net/coding-plan它在额度管理上更适合高频调用场景。但本文的验证流程用普通 API Key 就够了先把链路跑通再考虑套餐。这里再强调一个容易踩的坑不要把 MCP 服务端的地址和 TaoToken 的 Base URL 搞混。MCP 服务端是你自己起的工具服务地址类似http://localhost:8050/mcpTaoToken 的 Base URL 是模型 API 的入口。两者是完全不同的东西一个负责执行工具一个负责生成决策。配置时分开管理别写进同一个变量。3. 可复制配置FastMCP 服务端 Streamable HTTP 客户端这一节是全文的技术核心给出两份可直接运行的代码服务端注册工具并以 Streamable HTTP 模式启动客户端通过streamablehttp_client连接并调用工具。代码我实测过Python 3.10 环境直接跑。先装依赖pip install mcp[cli] httpx服务端代码server.pyfrom mcp.server.fastmcp import FastMCP # 创建 MCP 服务端无状态 HTTP 模式适合横向扩展 mcp FastMCP(MyServer, host127.0.0.1, port8050, stateless_httpTrue) mcp.tool() def say_hello(name: str) - str: 向指定名字打招呼 return fHello, {name}! Nice to meet you! mcp.tool() def add(a: int, b: int) - int: 计算两个整数之和 return a b if __name__ __main__: # 使用 Streamable HTTP 传输模式启动 mcp.run(transportstreamable-http)这里有几个关键点。stateless_httpTrue表示服务端不维护会话状态每次请求独立处理不返回Mcp-Session-Id也不要求客户端持有。这种模式适合无状态部署、多实例横向扩展。如果你需要会话上下文追踪把它设为False服务端会为每个客户端维护 Session日志里能看到Created new transport with session ID: xxx和Terminating session: xxx两条记录。transportstreamable-http是启动 Streamable HTTP 模式的关键参数服务端会监听/mcp路径统一处理 POST 和 GET 请求。客户端代码client.pyimport asyncio from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client async def main(): # 连接 MCP 服务端的 Streamable HTTP 端点 async with streamablehttp_client(http://localhost:8050/mcp) as ( read_stream, write_stream, get_session_id, ): async with ClientSession(read_stream, write_stream) as session: await session.initialize() # 列出服务端暴露的所有工具 tools_result await session.list_tools() print(Available tools:) for tool in tools_result.tools: print(f- {tool.name}: {tool.description}) # 调用 add 工具 result await session.call_tool(add, arguments{a: 1, b: 2}) print(f1 2 {result.content[0].text}) if __name__ __main__: asyncio.run(main())客户端的streamablehttp_client返回三个值读流、写流、获取 session id 的函数。ClientSession把读写流包起来initialize()完成握手list_tools()拉取工具清单call_tool()发起实际调用。返回的result.content[0].text就是工具执行结果注意它不是裸数字而是被包在 JSON-RPC 响应对象里的内容块。如果你要把模型侧也接进来让 LLM 决定调哪个工具可以在客户端里加一段调用 TaoToken API 的逻辑把list_tools()的结果转成模型的 tools 参数模型返回tool_calls后再路由到call_tool()。这部分逻辑因框架而异核心是保持 Base URL、Key、Model ID 三件套一致。提示服务端和客户端建议分两个终端跑先启动server.py看到监听日志后再跑client.py。如果客户端报连接拒绝先确认服务端是否真的起来了。4. 验证请求从 list_tools 到 call_tool 的完整结果核对配置写完最关键的一步是验证。很多人代码跑起来了但没核对返回结果线上出问题才发现工具根本没被调用。这一节把验证动作拆成三步每步都有明确的预期结果。第一步启动服务端。在终端执行python server.py正常会看到类似Uvicorn running on http://127.0.0.1:8050的日志。因为用了stateless_httpTrue日志里不会出现 session ID 相关的记录。如果你把stateless_http去掉默认False日志会多出Created new transport with session ID: 82a3519c341d4088a9c4c0856b991480和Terminating session: 82a3519c341d4088a9c4c0856b991480两条这说明服务端在为每个客户端维护会话。两种模式都能用区别在于是否需要状态追踪。第二步运行客户端。执行python client.py预期输出Available tools: - say_hello: 向指定名字打招呼 - add: 计算两个整数之和 1 2 3核对三个点工具清单里是否包含你注册的所有工具、描述是否和 docstring 一致、call_tool的返回是否是3。如果工具清单为空说明服务端注册没生效如果返回不是3检查arguments的键名是否和函数参数名一致。第三步用 curl 直接打一次 Streamable HTTP 端点验证协议层。这一步能帮你区分「是 MCP 逻辑问题」还是「是网络/协议问题」curl -X POST http://127.0.0.1:8050/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }预期返回一个 JSON-RPC 响应result.tools数组里包含say_hello和add。注意Accept头必须同时包含application/json和text/event-stream这是 Streamable HTTP 模式的协议要求缺了会返回 406。再打一次工具调用curl -X POST http://127.0.0.1:8050/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: add, arguments: {a: 1, b: 2} } }预期返回里result.content[0].text是3。到这里MCP 服务端的工具调用链路就验证完了。接下来把模型侧接进来用 TaoToken 的 API 发一次带 tools 参数的请求看模型是否返回tool_calls。如果模型返回了工具调用意图说明整条链路模型决策 → MCP 执行是通的。注意核对返回时不要只看 HTTP 状态码 200 就认为成功。JSON-RPC 的错误是包在响应体里的error字段非空才是真失败。养成看result和error两个字段的习惯。5. 本篇常见错排查401、local proxy failed 与 reading choices这一节把我在实际接入中遇到的报错按现象归类给出定位思路。这些报错覆盖了模型侧和 MCP 侧两类问题对照着看能省不少时间。401 Unauthorized。这是模型侧最常见的错几乎都是 Key 的问题。三种可能Key 复制时带了首尾空格、Key 已过期或被删除、Key 没有对应模型的权限。排查方法把 Key 打印出来看长度和首尾字符重新在控制台生成一个再试。如果换了新 Key 还是 401检查 Base URL 是否写成了https://taotoken.net/api/带了尾斜杠某些 SDK 对尾斜杠敏感。local proxy failed / connection refused。这是 MCP 客户端连不上服务端的典型报错。先确认服务端进程是否在跑curl http://127.0.0.1:8050/mcp能不能通。如果服务端在跑但客户端连不上检查端口是否被占用、host 是否写成了0.0.0.0而客户端连的是127.0.0.1。还有一种情况是客户端用了localhost但系统解析到了 IPv6 的::1而服务端只监听了 IPv4改成127.0.0.1即可。Error reading choices / 返回体里没有 choices 字段。这是模型侧响应解析失败。原因通常是 Base URL 拼错了路径请求打到了非 API 端点返回的是 HTML 而不是 JSON。检查 Base URL 是否为https://taotoken.net/api不要带/v1或/chat/completions。另外确认 Model ID 拼写正确写错模型名有时会返回一个结构不同的错误体解析器读choices就报错。OAuth / 鉴权头格式错误。如果你用的是 Claude Code 或类似工具鉴权头格式有特定要求。常见错误是把Authorization: Bearer sk-xxx写成了Authorization: sk-xxx少了Bearer前缀。检查配置文件里的 header 拼写注意大小写和空格。工具清单为空但没报错。这是 MCP 侧的问题通常是mcp.tool()装饰器没生效或者函数定义在mcp.run()之后。确保所有工具函数在mcp.run()之前定义并注册。还有一种可能是客户端连到了错误的端点比如连了/sse而不是/mcp。Mcp-Session-Id 相关报错。如果你用了有状态模式stateless_httpFalse客户端需要在后续请求里带上服务端返回的Mcp-Session-Id头。漏带会报会话不存在。如果不想处理这个直接用stateless_httpTrue每次请求独立不需要维护会话 ID。排查顺序建议先 curl 打 MCP 端点确认服务端正常再用 TaoToken 的模型对话页面https://taotoken.net/models单独测一次模型调用确认 Key 正常最后把两者串起来。分段验证比一上来就端到端调试高效得多。6. 把链路固定下来从验证到日常使用的接入建议链路跑通之后下一步是把它变成日常能用的东西。这里给几个实操建议都是踩过坑之后总结的。第一把三件套放进环境变量或密钥管理服务不要硬编码。代码里统一用os.environ.get(TAOTOKEN_API_KEY)读取本地开发用.env线上用平台的密钥管理。这样轮换 Key 时只改一处。第二MCP 服务端的工具描述docstring要写清楚。模型是靠描述来决定调哪个工具的描述模糊会导致误调用。比如add的描述写成「计算两个整数之和」比写成「加法」好得多模型能准确判断参数类型和用途。第三无状态模式优先。除非你确实需要跨请求的会话上下文否则用stateless_httpTrue。它省去了会话管理的复杂度部署时也不用考虑会话粘性多实例随便扩。第四给工具调用加日志。在call_tool前后打点记录工具名、参数、返回、耗时。出问题时这些日志是唯一的线索。MCP 的 JSON-RPC 错误信息有时比较简略自己的日志能补上上下文。第五定期核对模型返回的tool_calls结构。不同模型对工具调用的返回格式略有差异升级模型或换模型后要重新验证一遍解析逻辑。别假设格式永远不变。如果你要把这套链路用到生产建议先在测试环境用固定的几个工具跑一段时间观察调用成功率和延迟再逐步放开工具范围。工具调用本质上是让模型获得了执行能力权限边界要提前划清楚哪些工具能调、参数范围是什么都在服务端做校验不要只依赖模型的判断。需要查 API 细节的时候接入文档在https://taotoken.net/doc里面有完整的端点和参数说明。模型对话页面https://taotoken.net/models可以用来快速验证某个模型是否支持工具调用。API Keys 管理在https://taotoken.net/console/api-keys。这三个页面基本覆盖了日常接入需要的所有信息。最后说一个心态上的建议MCP 工具调用的调试本质上是把「模型决策」和「工具执行」两段分开验证。模型侧用 TaoToken 的对话页面单独测工具侧用 curl 单独测两段都通了再串起来。这样任何一段出问题都能快速定位不会在一堆日志里迷失方向。