mcp-builder 的 Inspector 连不上？TaoToken 这样改 Claude Code 通道再查

1. 先分清「Inspector 连不上」是哪一层在报错

1.1 Inspector 的两层结构

mcp-builder 是 Anthropic 在 anthropics/skills 仓库里的 MCP 工程规范，它把自定义 Server 的流程分成「规划 Tool 命名 → 用 FastMCP 实现 → 用 Inspector 调试 → 用 Eval 验收」四步。很多人在第三步卡住：npx @modelcontextprotocol/inspector python server.py之后，浏览器弹出来了，但工具列表是空的，状态栏一直在转圈，报错信息只有一句「failed to connect」。

要排掉这个错，先得理解 Inspector 内部其实跑着两个进程：外层是 Node 启动的本地 Web 服务，负责给浏览器页面提供调试界面；内层是python server.py拉起的 MCP Server，通过 stdio 协议传输 JSON-RPC 消息。浏览器页面上展示的 Tool 列表，并不是直接从server.py读出来的，而是 Inspector 先让 Server 启动并握手，再向模型发起一次「对话补全」请求，由模型根据 Server 暴露的工具描述生成初步调用结果，最后把 UI 渲染出来。

所以「Inspector 连不上」至少对应三个可能出错的位置：NPM 包本身没有正确下载、stdio 层 Python 环境异常、模型 API 通道请求超时。第三个位置最容易被忽略，因为大家默认调试 MCP 就只是「本地工具」，不该和云端模型有关。但 Inspector 的实际行为确实会发起模型请求，当这条通道卡住时，表现就是 MCP 一直连不上。

1.2 三种症状：连不上、无 Server、Tool 调用失败

原作者在常见问题表里把三个现象排在一列，很值得展开：它们不是互斥的三种故障，而是同一条失败链上的三个「截图时刻」。

如果你看到的是第一行，先别急着改server.py。mcp-builder 的规范里有一条很明确：先让 Server 能被独立测通，再去接 Agent。本地python server.py能挂住不报错，只代表 stdio 层没问题，不代表 Inspector 能拿到模型回复。真正要确认的是「Claude Code 当前使用的 API 通道是否还活着」。这也是可能的排查路径：打开 TaoToken 拿一把 Key，把 Base URL 切到兼容通道上，重新验证一遍。

2. 先用最小 Pocket Notes 还原现场

2.1 工具命名与读写边界

为了不干扰排查，Server 越简单越好。Pocket Notes 是一个本地纯文本笔记工具：添加、列表、搜索，数据存在用户目录 JSON 文件，不需要任何外部依赖。mcp-builder 对这类工具的建议是：Tool 名用笔记域_动词格式，让模型一眼看出用途；只读操作不写盘，写盘操作边界收窄；错误返回可行动文案，而不是抛未捕获异常。

按这个规范做三个 Tool：

• notes_add(title, content)：写，追加一条笔记，返回笔记 ID 和标题
• notes_list()：读，返回全部笔记的 ID 与标题
• notes_search(keyword)：读，在标题和正文里搜关键词

这三个 Tool 对应 Inspector 排障时的三层验证：写入是否成功、读取是否正确、过滤条件是否生效。如果notes_add都调不通，那就不是模型通道问题，而是 Server 根本没能启动。

2.2 直接建一个可运行的 server.py

先建目录并安装 MCP 依赖，后面所有步骤都基于这个环境：

mkdir pocket-notes-mcp && cd pocket-notes-mcp pip install mcp

创建server.py，完整可运行，不做抽象：

import json from pathlib import Path from mcp.server.fastmcp import FastMCP mcp = FastMCP("pocket-notes") NOTES_FILE = Path.home() / ".pocket-notes" / "notes.json" def _load(): if not NOTES_FILE.exists(): return [] return json.loads(NOTES_FILE.read_text(encoding="utf-8")) def _save(notes): NOTES_FILE.parent.mkdir(parents=True, exist_ok=True) NOTES_FILE.write_text( json.dumps(notes, ensure_ascii=False, indent=2), encoding="utf-8", ) @mcp.tool() def notes_add(title: str, content: str) -> str: """Add a note. title: note title; content: note body.""" title = title.strip() if not title: return "Error: title cannot be empty. Provide a title and retry." notes = _load() note_id = len(notes) + 1 notes.append({"id": note_id, "title": title, "content": content.strip()}) _save(notes) return f"Added note #{note_id}: {title}" @mcp.tool() def notes_list() -> str: """List all notes (id and title only).""" notes = _load() if not notes: return "No notes yet. Use notes_add first." return "\n".join(f"#{n['id']} {n['title']}" for n in notes) @mcp.tool() def notes_search(keyword: str) -> str: """Search notes by keyword in title or content.""" kw = keyword.strip().lower() if not kw: return "Error: keyword cannot be empty." hits = [ n for n in _load() if kw in n["title"].lower() or kw in n["content"].lower() ] if not hits: return f"No notes matching '{keyword}'." return "\n\n".join( f"#{n['id']} {n['title']}\n{n['content']}" for n in hits ) if __name__ == "__main__": mcp.run(transport="stdio")

这段代码里有几个细节是 mcp-builder 特别强调的：title.strip()在写入前清掉纯空格输入；notes_list只读不写；notes_search对空关键词返回可行动文案。这些都不是炫技，而是为了让模型在 Agent 环境里能根据 Docstring 正确推断参数，不至于调用时传一个空字符串进去。

2.3 本地空跑确认 stdio 正常

Inspector 连不上之前，先做一步「无模型」验证。直接运行：

python server.py

如果脚本正确，进程会挂在那里，没有任何输出，直到你按Ctrl+C退出。这代表 FastMCP 正常启动了 stdio 服务，正在等待 stdin 的 JSON-RPC 消息。

这一步很关键：它排除了 Python 语法错误、依赖缺失、文件路径写错等最基础的问题。如果这里就报错，后面 Inspector 里看到的所有异常都和它无关。只有在python server.py能稳定挂起的条件下，才有必要继续往模型通道方向排查。

3. 按报告顺序排除路径与 Python 环境

3.1 绝对路径到底写对没有

很多「Inspector 连不上」最后定位到的是命令参数问题。npx @modelcontextprotocol/inspector python server.py这个写法里，python server.py会被 Inspector 原样当作启动命令传给子进程。如果当前工作目录不是pocket-notes-mcp，server.py这个相对路径就会失效。

更稳定的做法是先写出绝对路径，再进入任意目录都能启动：

npx @modelcontextprotocol/inspector python /绝对路径/pocket-notes-mcp/server.py

Windows 用户要注意路径分隔符。E:\pocket-notes-mcp\server.py在 cmd 里没问题，但 Inspector 底层走的是 shell 解析，反斜杠在部分环境里会被当作转义符。稳妥起见，Windows 上用正斜杠或双反斜杠：E:/pocket-notes-mcp/server.py。

3.2 python 与 pip 是不是同一个环境

这是第二常见的坑。pip install mcp装进了某个 Python 环境，但npx启动python server.py时，PATH 里排在前面的可能是另一个 Python。比如系统里同时有 Homebrew Python、Anaconda、系统自带的/usr/bin/python3，它们各自的site-packages互不相通，server.py里import mcp在其中一个环境能过，在另一个就直接 ModuleNotFoundError。

排查方式很简单：

python -c "import mcp; print(mcp.__file__)"

如果这个命令能输出路径，再确认which python指向的是不是你执行pip install mcp时用的那个解释器。如果你用了虚拟环境，还需要先source venv/bin/activate再启动npx，因为 Inspector 的子进程继承的是当前 shell 的环境变量，不会自动加载 venv。

如果确认了绝对路径和 Python 环境都没问题，但 Inspector 还是停在「connecting」状态，那就要看一眼另一个方向：模型 API 通道是不是已经超时了。

3.3 npx 首次下载导致的「假连不上」

还有一类情况非常容易误导人：第一次运行npx @modelcontextprotocol/inspector，NPM 需要从远程拉包，在弱网环境下会持续几十秒甚至几分钟。浏览器窗口这时已经弹出来，但 Inspector 的本地服务其实还没就绪，页面上所有按钮都点了没反应，看起来像「Server 连不上」。

判断方法是在终端里观察输出。如果还在滚动 NPM 的下载进度条，说明 Inspector 本体还没起来。此时不用修改任何配置，等它完成即可。如果不确定，可以先单独执行一次npx @modelcontextprotocol/inspector --help，让它把包装好，再带参数启动，可以避免「下载中」和「真故障」混淆。

4. 通道层：让模型请求先通过 TaoToken 走通

4.1 为什么 MCP 调试还要检查 API 通道

Inspector 虽然是个本地调试工具，但在渲染 Tool 列表、触发 Call Tool 时，部分版本的调试体验依赖一次真实的模型补全请求。如果你发现本地验证一切正常、命令路径无误、Python 环境干净，却仍然「连不上」，那么最后一块拼图往往就是 Claude Code 默认走的那条 API 通道已经不可用：可能是配额耗尽，可能是网络出口波动，也可能是默认 Base URL 当前响应太慢。

这时候的思路是：先不碰server.py，也不碰 stdio 配置，只把 Claude Code 的模型请求切换到一个稳定的兼容通道上。TaoToken 提供统一 API 接入，支持把 Base URL 指向https://taotoken.net/api，让请求先能通，再回到 Inspector 里逐个测 Tool。它的角色只是通道验证，不会改写你的 MCP Server。

4.2 创建 Key 并拿到 Base URL

打开 TaoToken 注册并登录，在控制台创建 API Key。创建时选好你自己的模型即可，拿到形如sk-xxx的 Key 字符串。需要记住两个地址，不要混用：

• 官网落地页：https://taotoken.net/?utm_source=taotoken_aicg_blog_end，只用于注册、创建 Key、查看模型广场和用量
• 接口 Base URL：https://taotoken.net/api，末尾不要加/v1，填进 Claude Code、Codex 或其他兼容工具

模型 ID 不要靠记忆手敲，以 TaoToken 模型广场当时列表为准。不同时间上架的模型名可能调整，先到广场复制准确 ID，再往配置文件里填，能省掉一次 404 排障。

4.3 写入 Claude Code 的 settings.json

Claude Code 读取环境变量的方式有两种：一种是在 shell 里export，另一种是写进~/.claude/settings.json的env字段。后者更持久，也方便换 Key 时统一修改。配置文件格式如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "你在模型广场复制的模型 ID" } }

其中YOUR_API_KEY是你刚在 TaoToken 控制台创建的 Key，不要写在博客或共享配置里。ANTHROPIC_BASE_URL必须指向https://taotoken.net/api，不能在这里带 UTM 参数，也不要在末尾补/v1。ANTHROPIC_MODEL以模型广场列表为准。

保存后退出 Claude Code 完全重启，再在对话里输出/status，如果能显示模型信息，说明环境变量已经生效。这一步通过后，Claude Code 的模型请求就切到了 TaoToken 通道上。可以先在对话里随便问一句「你当前用的模型 ID 是什么」，确认模型能正常回复，再去重启 Inspector。

5. 带着新通道重跑 Inspector

5.1 重启 Claude Code 和 Inspector

许多人在改完settings.json之后直接点 Inspector 页面的刷新按钮，发现还是连不上。原因是环境变量只在进程启动时加载，Inspector 和 Claude Code 都是常驻进程，不会热重载配置。正确做法是：

1. 完全退出 Claude Code，不是关闭窗口，而是从菜单或命令行真正结束进程
2. 确认没有残留的 node 进程占用 Inspector 端口
3. 重新打开终端，重新进入pocket-notes-mcp目录
4. 重新执行 Inspector 命令

npx @modelcontextprotocol/inspector python /绝对路径/pocket-notes-mcp/server.py

浏览器页面重新打开后，MCP Server 状态应该比之前更快进入 connected。这一步只能验证 stdio 和通道是否通畅，真正的功能验证还要靠依次调用三个 Tool。

5.2 按固定顺序测三个 Tool

遵循 mcp-builder 的验证习惯，在 Inspector 里按「先写、再读、再搜索」的顺序来测，每个结果都有明确的成功标志：

第一步，测写入。在 Inspector 的 Tools 面板里找到notes_add，填入title=购物清单，content=牛奶、鸡蛋。点击 Call Tool，预期返回一段文字：Added note #1: 购物清单。如果这里报错，说明 Server 的写入链路有问题，与模型通道无关。

第二步，测列表。选择notes_list，点击 Call Tool。预期返回#1 购物清单。如果能看到这条输出，说明 JSON 文件读写正常，_load与_save之间没有横跳路径问题。

第三步，测搜索。选择notes_search，填入keyword=牛奶。预期返回完整条目，包含标题和正文。这一步验证的是过滤逻辑，不是通道。

三件事全部通过，说明 Server 逻辑正确，Inspector 的连接受控于通道状态也被排除。此时回到 Claude Code 接入环节，就能区分「MCP 配置问题」和「模型通道问题」了。

6. 回到 Claude Code：/mcp 验证与对话验收

6.1 重新接入 pocket-notes

Inspector 测试通过后，再回到 Claude Code 里注册这个 Server。个人调试推荐命令行添加，作用域只对当前用户生效：

claude mcp add --transport stdio pocket-notes -- python /绝对路径/pocket-notes-mcp/server.py

Windows 用户把路径写成绝对路径的 Windows 风格：

claude mcp add --transport stdio pocket-notes -- python E:/pocket-notes-mcp/server.py

如果你希望团队共享，则把配置写进项目的.mcp.json：

{ "mcpServers": { "pocket-notes": { "type": "stdio", "command": "python", "args": ["E:/tools/pocket-notes-mcp/server.py"] } } }

完全重启 Claude Code 后，输入/mcp，如果看到pocket-notes以及三个 tool（notes_add、notes_list、notes_search），说明注册成功。项目级配置首次加载可能需要交互批准，这是正常现象。

6.2 对话验收与 JSON 落盘检查

通道和注册都正常后，在 Claude Code 对话中依次发三条指令：

1. 用 pocket-notes 添加笔记：标题「学习计划」，内容「本周完成 MCP 教程」
2. 列出我所有笔记
3. 搜索包含 MCP 的笔记

成功标志是：Claude 实际调用了 MCP tool，而不是自己编一段笔记内容。你能在回复中看到工具调用的痕迹，比如「已调用 notes_add」的字样。接着打开本地 JSON 文件确认落盘：

• macOS / Linux：~/.pocket-notes/notes.json
• Windows：C:\Users\你的用户名\.pocket-notes\notes.json

文件内容里应该出现刚添加的笔记 ID、标题和正文。如果对话里 Claude 说「已添加」，但 JSON 文件里没有，那就要回头查server.py里的NOTES_FILE路径是不是被绝对路径覆盖了，或者 Claude Code 启动时的工作目录和预期不一致。

7. 跑通后，去控制台对一次调用记录

7.1 用模型对话确认同一把 Key

整套流程跑通以后，建议做最后一个闭环验证：用同一把YOUR_API_KEY，打开 TaoToken 模型对话 发一条测试消息。这条消息走的是独立的模型对话入口，和 Claude Code 共用同一套 Key 体系。如果这边能正常回复，但 Claude Code 里提示鉴权失败，那问题一定出在settings.json的环境变量上；如果两边都失败，检查 Key 是否复制完整，是否带上了多余空格。

7.2 看 Coding Plan 与 API Keys 管理

小说完整个链路，接下来最重要的是看本次调用是否真实记账。回到 控制台 API Keys 页面，检查刚才 Claude Code 对话过程中是否产生了对应的调用记录。如果长期写代码，对用量有稳定需求，可以在 Coding Plan 里看套餐是否够用，避免写代码写到一半额度见底。Claude Code 的环境变量对照和更多接入姿势，参考 Claude Code 接入文档。

这样一个排障闭环就完整了：从Inspector 连不上的表象出发，先分离层级，再用最小 Server 还原现场，排除路径与 Python 环境，切通道验证模型请求，最后回到 Inspector 和 Claude Code 做功能验收。以后再遇到 MCP 相关的问题，先问一句「到底是 Server 没起来，还是模型请求没出去」，大概率能少走一段弯路。