mcp.get_tools() 返回空列表、终端里一个刺眼的 404很多人第一反应是 MCP 服务器挂了或者工具描述压根没注入。实际接 MCP 的时候最容易先栽的地方不在工具层而在模型 API 地址上Base URL 手滑多写了一截 /v1请求被打到 /api/v1/... 上通道自然接不住。这篇按排障的路子走一遍先把模型通道量通再回头看工具注册。Key 统一从 TaoToken 拿落地页是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 填进工具的 Base URL 则固定写 https://taotoken.net/api 末尾不带 /v1。1. 从 mcp.get_tools() 返回空列表说起1.1 三个现场404、流式中断、工具描述为空先看三个具体的现场判断一下你踩的是哪一个。现场 AClaude Code 里刚配完环境变量敲一句话回车终端立刻回API error: 404报错路径里隐约能看到/api/v1/v1/messages这种叠了两层的写法。这种情况下 Key 没问题、网络也通纯粹是地址写错了。现场 BCodex 里配置了自定义 provider普通对话能出字一旦让模型去调 MCP 暴露出来的工具会话就提前结束日志里是流式中断或者400 invalid request。这种更容易误判成「工具描述格式不对」。现场 CContinue、Cline 这类图形客户端里模型很客气地回一句「我目前没有可用的工具」你去查mcp.get_tools()返回的是一个空数组。工具列表空的可能有两个原因——MCP 服务器没起来或者模型连接根本没通工具描述没进上下文。三个现场看着分散其实都指向两条链路模型通道能不能通工具清单有没有真的注册进去。这两条链路是串行的前一条断了后一条怎么查都是白费劲。1.2 /v1 到底做了什么路径被拼成了 /api/v1/v1大多数 SDK 在发请求时会自己往 base_url 后面补版本路径。OpenAI 风格的客户端补/v1/chat/completionsAnthropic 风格的客户端补/v1/messages。也就是说Base URL 填到哪一层最终路径由客户端决定。于是问题来了你在 Base URL 里已经写了https://taotoken.net/api/v1客户端再补一次/v1/messages拼出来就是https://taotoken.net/api/v1/v1/messages。这就像快递单上把门牌号写了两遍分拣中心看着这行字不知道包裹到底该送哪一栋。TaoToken 的兼容通道本身已经把版本路径安排好了Base URL 只需要填到https://taotoken.net/api这一层末尾不要/v1也不要留尾随斜杠。还有一个容易忽略的点UTM 参数属于给人点的落地页别带到接口地址上。某些客户端会把 query string 一起拼进请求路径结果就是你看不出错在哪但请求确实打歪了。1.3 排障顺序先量模型通道再量工具注册拿到报错别急着翻 MCP 服务器的源码。按下面这个顺序走通常三分钟能定位第一确认 Base URL 落在https://taotoken.net/api不多不少。第二确认 Key 是从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建的、没有多余空格或换行。第三发一条不涉及任何工具的纯聊天请求看通道是否 200。第四通道通了再去查 MCP 服务器的进程和initialize握手。顺序反过来的话你会一直在 MCP 那一侧打转而真正的毛病是模型请求压根没发出去。2. 模型一侧原生支持 MCP 的几个系列Base URL 各写在哪2.1 Claude 系列settings.json 的 env 段Claude 对本地文件系统、IDE 工具链的调用是深度集成的桌面端也允许挂自定义 MCP 服务器。落到命令行版本的 Claude Code配置集中在~/.claude/settings.json的env段里。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: 以模型广场当时列表为准的模型 ID } }三个变量各管一件事ANTHROPIC_BASE_URL决定请求打到哪ANTHROPIC_AUTH_TOKEN是通道凭据ANTHROPIC_MODEL是具体模型。三个里最容易写错的还是第一个多一个/v1就 404。也可以不改文件直接在 shell 里导出同名环境变量效果一致。但要注意如果你两边都写了实际生效的是哪一份取决于启动方式排障时先只保留一处避免自己跟自己打架。2.2 GPT/Codex 一侧config.toml 的 model_providerCodex 走的是 TOML 配置文件名是~/.codex/config.toml。它不认ANTHROPIC_*那套变量别把上面那段直接搬过来。model 以模型广场当时列表为准的模型 ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEYmodel_provider指向下面定义的 provider 块base_url同样只到/api这一层。env_key里写的是环境变量的名字不是 Key 本身——真正的值放在 shell 里export TAOTOKEN_API_KEYYOUR_API_KEY这样分开写的好处是配置文件可以进版本库Key 不会跟着泄露。Key 从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建建议在控制台里给不同机器建不同的 Key出问题好回收。2.3 开源模型与 Hugging Face 生态先量 OpenAI 兼容变量社区插件接入向量数据库、检索增强这套玩法时通常走 OpenAI 兼容协议。对应的环境变量是OPENAI_BASE_URL和OPENAI_API_KEYexport OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEYYOUR_API_KEY这里同样只到/api。有些插件的默认值是https://api.openai.com/v1你要是照着这个格式改成https://taotoken.net/api/v1就会踩到 1.2 节说的路径叠加问题。改地址的时候顺手把尾部那一截删掉比事后翻日志省事。2.4 模型 ID 从模型广场对一遍再填模型 ID 是最容易被随手编的地方。gpt-5、带奇怪日期后缀的名字网上抄来的十有八九是错的。正确做法是打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 看模型广场当时的列表复制里面真实存在的 ID 再填。列表会变所以别把某一篇文章里的字符串当成永久答案。3. 中间件与 Agent 框架mcp-agent、Goose、Continue 的落点3.1 mcp-agent 的多代理编排与连接生命周期mcp-agent 这类轻量框架管的是 MCP 连接的生命周期也支持多代理协作比如 Swarm 风格的分工模式。它的职责是「连上哪些 MCP 服务器、把哪些工具暴露给代理」而不是替你决定模型请求打到哪。所以配置上要分两处看框架一侧填 MCP 服务器的启动命令或地址模型一侧仍然是https://taotoken.net/api加上一把 Key。很多人把这两处搞混——在 MCP 服务器配置里填了模型通道地址结果服务器启动就报错。一个直观的检查办法先只注册一个最简单的 MCP 服务器比如只提供文件查找能力的那个跑通之后再往上加。一次加五个出错了你不知道该怀疑谁。3.2 Goose 的端点和命令式工作流Goose 走的是标准化 API 与端点设计擅长把调试、代码编写、跨平台数据同步这类动作串成工作流。它的配置里同样有一个模型端点字段填https://taotoken.net/api。有个细节值得留意Goose 的某些工作流会连续发多次请求如果 Base URL 写错你不会只看到一条报错而是一串失败日志。这时候从第一条错误的时间戳往回看能更快锁定是配置问题还是某一次调用的问题。3.3 动态注册mcp.get_tools() 不硬编码把工具名硬编码进 prompt 是很省事但工具一多就崩。会话开始的时候调一次mcp.get_tools()把当下可用的工具列表拿到手再拼进上下文这才是稳的做法。1. 建立模型通道Base URL https://taotoken.net/apiKey YOUR_API_KEY 2. 启动 MCP 服务器等待 initialize 完成 3. 调用 mcp.get_tools() 取回工具清单 4. 把工具描述注入本轮对话上下文 5. 模型决定调用哪个工具由框架执行并把结果回填第 1 步失败后面全是空转。这也是为什么 1.3 节强调先量模型通道——mcp.get_tools()返回空数组有可能是第 1 步就断了工具根本轮不到被注册。另外提醒一句工具能让模型生成 SQL、解释 SQL、对照表结构但真正的执行动作要由你在本地 SQL*Plus、只读副本或者测试库里跑再把结果贴回对话。别指望把生产库直接挂上去让模型去查那是两码事。4. 第一次接上Key、Base URL 和两份可复制配置4.1 拿 Key 与确认模型 ID打开 TaoToken 注册登录进控制台创建 API Key复制出来先放一边。同一页面上把模型广场的 ID 也确认一遍两个信息凑齐再动手改配置。Key 的占位符统一写YOUR_API_KEY贴进任何配置文件之前先确认前后没有多余空格和换行——这类隐形字符造成的 401查起来最烦。4.2 Claude Code 的两种写法写法一直接改~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: 以模型广场当时列表为准的模型 ID } }写法二在 shell 配置里导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODEL以模型广场当时列表为准的模型 ID注意地址里不要出现?utm_source之类的参数接口地址和给人点的页面地址是两回事。环境变量对照可以翻 Claude Code 接入文档。4.3 Codex config.tomlmodel 以模型广场当时列表为准的模型 ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY写完先跑一次最简单的对话确认通道通了再去挂 MCP 服务器。这一步的顺序别颠倒。4.4 Continue / Cline / CC Switch 这类 GUI 客户端图形客户端的供应商表单基本只有三个字段自定义供应商名称、Base URL、API Key外加一个模型 ID 下拉或输入框。Base URL 填https://taotoken.net/apiKey 填YOUR_API_KEY模型 ID 从模型广场复制。填完点保存多数客户端会立刻发一条测试请求如果这一步就报错基本可以确定是地址多了/v1。5. 验证分清「多了 /v1」还是「工具描述没注入」5.1 先发一条纯聊天请求配置改完第一件事不是去调工具而是发一条不涉及任何工具的普通对话。能正常出字说明模型通道没问题这一步就 404别往下查了回去看 Base URL。如果手边没有现成的客户端可以在 TaoToken 模型对话 里用同一把 Key 发一条测试消息快速确认 Key 和模型 ID 是对得上的。5.2 再看握手initialize、tools/list 与 Mcp-Session-Id通道通了之后验证 MCP 侧的握手顺序服务器启动后先initialize再tools/list会话期间带上Mcp-Session-Id做隔离。如果tools/list返回空说明服务器本身没暴露工具跟 Base URL 无关。如果tools/list正常但模型还是说没工具那就是工具描述没被拼进上下文——回去检查 3.3 节那五步里的第 4 步。5.3 三个报错对照表现象日志里能看到什么大概率原因动作立刻 404路径里出现/api/v1/v1/Base URL 多写了一截改成https://taotoken.net/api200 但工具列表为空tools/list返回[]MCP 服务器没暴露工具或没启动检查服务器进程与工具注册代码模型不可用model not found之类模型 ID 对不上回 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场核对这张表覆盖了本篇配置最可能遇到的三种情况。第一行是最高频的也是最容易被误判成「MCP 坏了」的。6. 排障清单安全配置与别踩的操作6.1 会话令牌、断线重连、权限控制Mcp-Session-Id这类会话令牌的作用是把不同会话隔开防止上下文串味。多代理场景下尤其重要——两个代理共用一个会话工具返回值可能互相污染。断线重连机制也值得配一下网络抖动之后能自动恢复握手不用你手动重启整个服务。权限控制是另一层。沙箱隔离加上最小权限能让工具只碰它该碰的东西。给一个只读工具配了写权限出事的时候你连是哪次调用改的数据都查不出来。6.2 两件不能做的事第一件别把生产的数据库、机器直接挂成 MCP 工具让模型去执行。模型的活是生成和解释执行由你在本地做。第二件别把接口地址和落地页地址混用——接口永远是https://taotoken.net/api需要注册、看用量、看模型列表的时候才打开带 UTM 的那个页面。顺手再看一眼 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的用量面板确认配置期间那几次失败请求有没有被记上心里有数。7. 跑通之后把这次调用对一下账配置保存、纯聊天请求通了、mcp.get_tools()能拿到清单这条链路就算立住了。接下来去 控制台 API Keys 给每台机器建一把独立的 Key方便日后按机器排查。如果打算长期用来写代码先看 Coding Plan 的套餐是否匹配你的调用量Claude Code 的环境变量细节则对照 接入文档 逐项核一遍。下次再遇到工具列表为空先别翻 MCP 服务器的代码。花三十秒看一眼 Base URL 有没有多出/v1能省掉大半个下午。