在 Claude Code 里敲完claude mcp add回到对话框输入/mcp清单却空着、或者少了自己刚加的那一个——多数时候问题不在 MCP 服务器本身而在 scope 加错了层。先别急着删配置重装去 TaoTokenhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_end创建一把 Key把 Claude Code 的 Base URL 填成https://taotoken.net/api确认模型请求这条链路本身是通的通道没问题再回头对照.mcp.json与~/.claude.json的 JSON 结构playwright 这类 MCP 才会出现在/mcp列表里。下面按排障顺序走先分清现象再确认通道最后逐个 scope 对文件。1./mcp里找不到刚加的服务器先分清是哪种没生效1.1 三种现象对应三种不同的错同样是「没反应」落在配置层的位置完全不同先归类能省掉一半时间。列表里压根没有这个名字claude mcp add生效的文件和你当前打开的项目目录对不上。最常见的是用了默认的 local scope配置写在~/.claude.json的projects节点下而你换了目录启动 Claude Code自然看不到。列表里有但调用工具时报错scope 没问题问题在 MCP 服务器进程本身起不来——npx找不到、uvx没装、参数写错、端口被占。当前目录能看到换个目录就消失典型的 project scope 行为配置绑定在项目根目录的.mcp.json上从子目录启动就匹配不到。把这三类分开之后「add 完没反应」就不再是个玄学问题而是一张可以逐条打勾的清单。每次出问题先对号入座别一上来就改 JSON。1.2 为什么add返回成功/mcp里却没有claude mcp add的默认 scope 是local它不会写进你项目根目录的.mcp.json而是写进用户级的~/.claude.json并且嵌在projects里、按项目绝对路径分组。命令返回成功只说明「这个文件写进去了」不说明「你当前这个目录读得到」。很多人对文件的直觉是「写到一个全局文件就等于全局生效」但 local scope 恰恰相反文件是全局的作用范围却是按路径切的。理解这一点后面三个 scope 的对照就顺了。2. 排 MCP 之前先把 Claude Code 的请求接到 TaoToken 通道2.1 拿 Key并确认 Base URL 该填什么打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册账号进控制台创建 API Key复制出来的那串就是下文配置里出现的YOUR_API_KEY。顺手去 TaoToken 的模型广场看一眼当前可用的模型 ID记下来——模型名以模型广场当时列表为准不要照抄别人文章里的旧 ID也不要自己拼日期后缀。这里有件事必须分清楚给人点的网页地址和填进工具的接口地址不是同一个。用途地址说明注册、创建 Key、看模型广场、看用量https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end浏览器里打开填进 Claude Code 的 Base URLhttps://taotoken.net/api末尾不要加/v1把/v1拼到后面或者把带?utm_source的落地页地址填进工具是两类最常见的低级错误先在这里避开。2.2~/.claude/settings.json里把通道指过去Claude Code 既读环境变量也读~/.claude/settings.json的env字段。想让所有项目都走同一条通道改配置文件更省事{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID } }ANTHROPIC_MODEL填你在模型广场看到的那一串 IDANTHROPIC_AUTH_TOKEN填刚创建出来的 Key。改完重启 Claude Code让它重新读一遍配置。2.3 临时启动环境变量或taotokenCLI不想动全局配置也可以在终端里临时带一次export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELYOUR_MODEL_ID习惯用命令行拉起的装一下官方 CLInpm install -g taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m YOUR_MODEL_ID注意-u后面是接口地址https://taotoken.net/api不是落地页也不要加/v1。2.4 一条消息确认通道是通的通道验证不需要复杂操作在 Claude Code 里发一句「你好回复一个字」能正常返回就说明模型请求这条路通了。这一步的价值在于把问题二分——如果这里就不通后面的 MCP 排障全是白费力气如果这里通了那/mcp列表为空就只可能是 scope 或服务器进程的问题。3. 对着--scope回查.mcp.json和~/.claude.json各写哪一段3.1--scope project写进项目根目录的.mcp.jsonclaude mcp add playwright --scope project -- npx -y playwright/mcplatest这个命令会在当前工作目录的根生成或修改.mcp.json{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest] } } }.mcp.json跟着项目走别人 clone 下来也有。反过来说你必须在包含这个文件的那个目录启动 Claude Code它才认。从src/子目录启动匹配不到根目录的.mcp.json。3.2--scope user写进~/.claude.json顶层的mcpServersclaude mcp add playwright --scope user -- npx -y playwright/mcplatest落点是这样注意它在文件的顶层没有嵌套{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest] } } }这一层是所有项目都生效的和具体目录无关适合那些「我到处都想用」的 MCP。3.3--scope local~/.claude.json里按项目路径分组的那一块local 是claude mcp add不带--scope时的默认值也是最多人踩坑的地方——文件是用户级的~/.claude.json但内容挂在某个项目路径下{ mcpServers: {}, projects: { /Users/you/code/demo: { mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest] } } } } }这就是「文件里有、列表里没有」的根源你加的时候在/Users/you/code/demo后来在/Users/you/code/other里开 Claude Code当然看不见。回查时先搜顶层的mcpServers再往下翻projects两边都确认一遍。3.4 三个落点放一起对照scope文件JSON 位置生效范围project项目根目录.mcp.json顶层mcpServers该项目及其子目录user~/.claude.json顶层mcpServers所有项目local默认~/.claude.jsonprojects.绝对路径.mcpServers仅该路径提示回查时先回想「我加的时候用的哪个--scope」再打开对应文件搜mcpServers。三个地方都搜一遍哪一层缺了、哪一层重复了一眼就能看出来。4. scope 对了工具还是调不动命令、路径与执行边界4.1npx、uvx在图形化启动的 Claude Code 里找不到MCP 服务器是一个本地子进程靠command字段拉起来。如果你从 IDE 或桌面端启动 Claude Code它继承的PATH可能和终端里不一样npx、uvx、node这些命令就会「找不到」。处理办法是把命令写成绝对路径先在你的终端里跑一遍which npx把输出填进command字段比反复猜环境变量靠谱得多。4.2 MCP 只负责生成和解释真正的执行在你手上这一点值得单独强调。MCP 服务器提供的是能力描述Claude Code 借助它把请求转成一次工具调用但涉及数据库、生产机器、部署脚本这类动作不应该、也不适合让 AI 直接连上去执行。比较稳的做法是让 Claude Code 生成或解释 SQL 与命令你自己在本地终端或 SQL*Plus 里执行把报错或结果贴回对话下一轮再让它据此调整。这条链路里 AI 是「写和读」的角色执行权始终留在你手里。MCP 加得对不对跟这条边界并不冲突。4.3 现象与原因对照现象常见原因处理方向/mcp里没有该条目scope 与当前目录不匹配按第 3 节对文件列表有调用即失败npx路径在 GUI 环境缺失command改绝对路径提示服务器启动超时首次拉包慢或被网络策略拦先在终端手动跑一遍同一条命令换个项目就消失用了 project scope改--scope user或复制.mcp.json注意MCP 服务器首次启动往往要先下载依赖包第一次调用慢是正常的别把「慢」当成「没配上」。在终端里手动执行一次同样的npx命令立刻就能分辨这两种情况。另外改完.mcp.json或~/.claude.json记得重启会话热改不一定立刻生效。5. 换个目录就消失project scope 的路径与版本库问题5.1 从子目录启动 Claude Code 会怎样前面提过一次这里说清原因。.mcp.json的识别从项目根开始如果你习惯在src/、packages/xxx里敲claude那它看到的工作目录就是子目录根目录的.mcp.json不参与匹配。排查手法很土但有效让 Claude Code 输出当前工作目录或者干脆回到项目根再启动一次。如果回到根目录就能在/mcp里看到问题就已经定位不用再折腾 JSON 结构。5.2.mcp.json要不要进 gitproject scope 的设计意图就是团队共享所以.mcp.json通常要提交进版本库。但有两件事得注意一是文件里别塞任何密钥Key 走环境变量或~/.claude/settings.json二是队友拉下来之后仍要各自确认通道配置——Base URL 是https://taotoken.net/apiKey 是各自在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 上创建的那一把不能互相顶替也不要把谁的 Key 直接写进仓库。如果.mcp.json里的命令依赖外部环境最好在项目说明里补一句「跑之前先确认npx可用」能省掉团队里一半的重复提问。6. 配置生效之后把这轮调用对一下账6.1 先在模型对话里用同一把 Key 发一条通道配好、/mcp也能列出 playwright 之后建议做个收尾动作用同一把 Key 在 TaoToken 模型对话 里发一条测试消息。如果对话正常、Claude Code 里也正常说明 Key、Base URL、模型 ID 三件套对上了如果只有一边不行问题就缩小到具体工具的配置而不是账号本身。Key 还没建的直接在 控制台 API Keys 里创建环境变量该怎么写可以对照 Claude Code 接入文档。6.2 长期跑 playwright 这类 MCP看套餐和用量MCP 接上以后工具调用会明显增加请求次数尤其 playwright 这类需要来回确认的服务器。如果每天都要跑可以打开 Coding Plan 看看当前套餐是否够用再回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的控制台对一下这几天的用量趋势确认这轮调试确实记在了你的账号上。如果你现在正卡在/mcp列表为空这一步顺序就是先确认通道本身通不通再打开加装时用的那个 scope 对应的文件.mcp.json看项目根目录~/.claude.json看顶层mcpServers和projects下的嵌套。通道、scope、进程三条线依次走完该出现的 playwright 就会出现真说起来这三处对完绝大多数「没反应」都会现出原形。