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 调用失败原作者在常见问题表里把三个现象排在一列很值得展开它们不是互斥的三种故障而是同一条失败链上的三个「截图时刻」。现象典型表现优先排查点Inspector 连不上浏览器页面一直 loadingMCP Server 状态从未变成 connectedNPM 包 / 端口 / 模型通道MCP 无 ServerInspector 页面正常打开但 Server 列表为空看不到 pocket-notes命令路径 / Python 环境 / 启动参数Tool 调用失败Server 已连接点 Call Tool 后一直转圈或返回 500stdio 参数解析 / 模型通道 / 工具 Docstring如果你看到的是第一行先别急着改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 名用笔记域_动词格式让模型一眼看出用途只读操作不写盘写盘操作边界收窄错误返回可行动文案而不是抛未捕获异常。按这个规范做三个 Toolnotes_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(encodingutf-8)) def _save(notes): NOTES_FILE.parent.mkdir(parentsTrue, exist_okTrue) NOTES_FILE.write_text( json.dumps(notes, ensure_asciiFalse, indent2), encodingutf-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 fAdded 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 fNo notes matching {keyword}. return \n\n.join( f#{n[id]} {n[title]}\n{n[content]} for n in hits ) if __name__ __main__: mcp.run(transportstdio)这段代码里有几个细节是 mcp-builder 特别强调的title.strip()在写入前清掉纯空格输入notes_list只读不写notes_search对空关键词返回可行动文案。这些都不是炫技而是为了让模型在 Agent 环境里能根据 Docstring 正确推断参数不至于调用时传一个空字符串进去。2.3 本地空跑确认 stdio 正常Inspector 连不上之前先做一步「无模型」验证。直接运行python server.py如果脚本正确进程会挂在那里没有任何输出直到你按CtrlC退出。这代表 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-mcpserver.py这个相对路径就会失效。更稳定的做法是先写出绝对路径再进入任意目录都能启动npx modelcontextprotocol/inspector python /绝对路径/pocket-notes-mcp/server.pyWindows 用户要注意路径分隔符。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/inspectorNPM 需要从远程拉包在弱网环境下会持续几十秒甚至几分钟。浏览器窗口这时已经弹出来但 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_sourcetaotoken_aicg_blog_end只用于注册、创建 Key、查看模型广场和用量接口 Base URLhttps://taotoken.net/api末尾不要加/v1填进 Claude Code、Codex 或其他兼容工具模型 ID 不要靠记忆手敲以 TaoToken 模型广场当时列表为准。不同时间上架的模型名可能调整先到广场复制准确 ID再往配置文件里填能省掉一次 404 排障。4.3 写入 Claude Code 的 settings.jsonClaude 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. 带着新通道重跑 Inspector5.1 重启 Claude Code 和 Inspector许多人在改完settings.json之后直接点 Inspector 页面的刷新按钮发现还是连不上。原因是环境变量只在进程启动时加载Inspector 和 Claude Code 都是常驻进程不会热重载配置。正确做法是完全退出 Claude Code不是关闭窗口而是从菜单或命令行真正结束进程确认没有残留的 node 进程占用 Inspector 端口重新打开终端重新进入pocket-notes-mcp目录重新执行 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-notesInspector 测试通过后再回到 Claude Code 里注册这个 Server。个人调试推荐命令行添加作用域只对当前用户生效claude mcp add --transport stdio pocket-notes -- python /绝对路径/pocket-notes-mcp/server.pyWindows 用户把路径写成绝对路径的 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以及三个 toolnotes_add、notes_list、notes_search说明注册成功。项目级配置首次加载可能需要交互批准这是正常现象。6.2 对话验收与 JSON 落盘检查通道和注册都正常后在 Claude Code 对话中依次发三条指令用 pocket-notes 添加笔记标题「学习计划」内容「本周完成 MCP 教程」列出我所有笔记搜索包含 MCP 的笔记成功标志是Claude 实际调用了 MCP tool而不是自己编一段笔记内容。你能在回复中看到工具调用的痕迹比如「已调用 notes_add」的字样。接着打开本地 JSON 文件确认落盘macOS / Linux~/.pocket-notes/notes.jsonWindowsC:\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 没起来还是模型请求没出去」大概率能少走一段弯路。