企业官网建设流程全解析

在 Claude Code 里敲完claude mcp add，回到对话框输入/mcp，清单却空着、或者少了自己刚加的那一个——多数时候问题不在 MCP 服务器本身，而在 scope 加错了层。先别急着删配置重装，去 TaoToken（https://taotoken.net/?utm_source=taotoken_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_source=taotoken_aicg_blog_end 注册账号，进控制台创建 API Key，复制出来的那串就是下文配置里出现的YOUR_API_KEY。顺手去 TaoToken 的模型广场看一眼当前可用的模型 ID，记下来——模型名以模型广场当时列表为准，不要照抄别人文章里的旧 ID，也不要自己拼日期后缀。

这里有件事必须分清楚：给人点的网页地址，和填进工具的接口地址不是同一个。

把/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填你在模型广场看到的那一串 ID；ANTHROPIC_AUTH_TOKEN填刚创建出来的 Key。改完重启 Claude Code，让它重新读一遍配置。

2.3 临时启动：环境变量或taotokenCLI

不想动全局配置，也可以在终端里临时带一次：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY" export ANTHROPIC_MODEL="YOUR_MODEL_ID"

习惯用命令行拉起的，装一下官方 CLI：

npm 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.json

claude mcp add playwright --scope project -- npx -y @playwright/mcp@latest

这个命令会在当前工作目录的根生成（或修改）.mcp.json：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } } }

.mcp.json跟着项目走，别人 clone 下来也有。反过来说，你必须在包含这个文件的那个目录启动 Claude Code，它才认。从src/子目录启动，匹配不到根目录的.mcp.json。

3.2--scope user：写进~/.claude.json顶层的mcpServers

claude mcp add playwright --scope user -- npx -y @playwright/mcp@latest

落点是这样，注意它在文件的顶层，没有嵌套：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } } }

这一层是所有项目都生效的，和具体目录无关，适合那些「我到处都想用」的 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/mcp@latest"] } } } } }

这就是「文件里有、列表里没有」的根源：你加的时候在/Users/you/code/demo，后来在/Users/you/code/other里开 Claude Code，当然看不见。回查时先搜顶层的mcpServers，再往下翻projects，两边都确认一遍。

3.4 三个落点放一起对照

提示：回查时先回想「我加的时候用的哪个--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 服务器首次启动往往要先下载依赖包，第一次调用慢是正常的，别把「慢」当成「没配上」。在终端里手动执行一次同样的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要不要进 git

project scope 的设计意图就是团队共享，所以.mcp.json通常要提交进版本库。但有两件事得注意：一是文件里别塞任何密钥，Key 走环境变量或~/.claude/settings.json；二是队友拉下来之后仍要各自确认通道配置——Base URL 是https://taotoken.net/api，Key 是各自在 https://taotoken.net/?utm_source=taotoken_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_source=taotoken_aicg_blog_end 的控制台对一下这几天的用量趋势，确认这轮调试确实记在了你的账号上。

如果你现在正卡在/mcp列表为空这一步，顺序就是：先确认通道本身通不通，再打开加装时用的那个 scope 对应的文件，.mcp.json看项目根目录，~/.claude.json看顶层mcpServers和projects下的嵌套。通道、scope、进程三条线依次走完，该出现的 playwright 就会出现；真说起来，这三处对完，绝大多数「没反应」都会现出原形。