企业官网建设流程全解析

1. 从 settings.json 到 JSON-RPC：Claude Code MCP 搭建为什么总在同一个坑里翻车

Claude Code MCP 搭建这件事，说难不难，说简单也真不简单。MCP 全称 Model Context Protocol，是让 Claude Code 这类编码助手能调用外部工具、读写文件、访问自定义服务的一套协议。你可以在 Claude Code 里挂一个自己写的 MCP Server，让它帮你分析项目、生成面试笔记、查数据库、跑脚本。适合谁？适合已经用 Claude Code 写代码、想把自己的工作流自动化、又不想每次都手动复制粘贴的开发者。

但问题在于，Claude Code 的配置层太多：.claude.json、.claude/settings.json、环境变量、会话缓存、slashCommands、MCP Server 注册，每一层都有自己的优先级和加载时机。网上教程又混杂着不同版本的写法，低版本和高版本的配置结构完全不一样。结果就是：模型改了不生效、MCP 启动直接 failed、命令写了提示 Unknown command、每次调用工具弹权限确认框。

我试过把整个流程从零走一遍，踩了七个典型报错点，每一个都能让你卡半天。下面按 settings.json 配置层、SDK 接入层、JSON-RPC 通信层三层拆开讲，每个报错都给出可复制的配置片段和逐步验证动作。你对照着排查，基本能一次跑通。

核心检索词先明确：Claude Code MCP 搭建的核心是让 Claude Code 通过标准 JSON-RPC 协议与外部 MCP Server 通信，配置入口在.claude.json和.claude/settings.json，SDK 接入必须用官方@modelcontextprotocol/sdk。搞清这三层，后面所有报错都有迹可循。

2. TaoToken 前置：模型接入层不锁死，后面全白搭

在讲 MCP 之前，得先把模型接入层搞定。因为 Claude Code 的模型配置分两层控制：表层是.claude.json，底层是.claude/settings.json里的环境变量。很多人只改表层，重启后发现模型又变回去了，就是因为底层环境变量在强制覆盖。

TaoToken 在这里的角色是提供统一的 API 接入点。你不需要在本地折腾各种代理配置，直接把 Base URL 指向 TaoToken 的 API 地址，用 API Key 做鉴权，模型 ID 填你需要的模型就行。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。

具体操作上，你需要先拿到 API Key。进入 API Keys 页面创建一个新 Key，复制出来。然后配置接入文档里说明的 Base URL 和模型 ID。对于 Claude Code 来说，最关键的是把环境变量写进.claude/settings.json，而不是只写在.claude.json根节点。

为什么强调这个？因为 Claude Code 的模型加载顺序是这样的：会话缓存 >.claude.json根节点 >.claude/settings.json环境变量。但环境变量是最终强制生效层，只要它设了，前面两层都会被覆盖。所以正确做法是：在.claude/settings.json里写死ANTHROPIC_MODEL和ANTHROPIC_DEFAULT_XXX_MODEL，这样无论你怎么重启会话，模型都不会回弹。

如果你需要长期跑编码任务或者 Agent 工作流，可以考虑 Coding Plan，它适合高频调用场景。如果只是验证模型对话效果，用模型对话页面就行。接入文档里有完整的配置说明，建议先过一遍再动手。

这里有个易错点：很多人把model写到.claude.json的settings嵌套节点里，但 Claude Code 2.1.121 这个版本根本没有settings顶层节点，高版本才用这个结构。低版本直接写在根节点，高版本才包在settings里。抄教程之前先确认自己的版本号。

3. 可复制配置：settings.json、MCP Server 注册与 SDK 接入三件套

这一节给可直接复制的配置片段。路径以 Windows 为例，macOS 和 Linux 把C:\Users\DELL换成你的 home 目录即可。

3.1 底层模型锁定：.claude/settings.json

这是最终强制生效层，路径是C:\Users\DELL\.claude\settings.json。内容如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的API Key", "ANTHROPIC_MODEL": "你的模型ID", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "你的模型ID", "ANTHROPIC_DEFAULT_SONNET_MODEL": "你的模型ID" } }

注意ANTHROPIC_BASE_URL不要加 UTM 参数，API 地址就是https://taotoken.net/api。API Key 从 API Keys 页面获取。模型 ID 填你实际要用的。

3.2 MCP Server 注册：.claude.json

MCP Server 的注册入口在.claude.json里，路径是C:\Users\DELL\.claude.json。找到mcpServers节点，加入你的服务：

{ "mcpServers": { "project-interview": { "command": "node", "args": [ "C:\\Users\\DELL\\.claude\\skills\\project-interview\\server.js" ], "alwaysLoad": true } } }

三个关键点：command用node，args里路径必须双反斜杠，alwaysLoad设为true减少权限弹窗。注意alwaysLoad在 2.1.121 里只对当前项目免询问，换项目还是会问，这是版本行为。

3.3 SDK 接入：官方包安装与标准写法

拒绝手写裸 JSON-RPC。新版 Claude Code MCP 有强协议校验，必须正确响应tools/list、必须走标准 MCP 生命周期。手写简易协议字段不全，直接判定服务异常。

安装官方 SDK：

npm i @modelcontextprotocol/sdk

服务端标准写法：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new McpServer({ name: "project-interview", version: "1.0.0" }); server.tool( "analyze-interview-project", "分析当前项目并生成面试复习笔记", {}, async () => { return { content: [ { type: "text", text: "分析完成，已生成 Project_Interview_Note.md" } ] }; } ); const transport = new StdioServerTransport(); await server.connect(transport);

这段代码用了McpServer和StdioServerTransport，是官方推荐的标准写法。server.tool注册工具，工具名和描述要精准，否则调用时匹配不到。

3.4 三件套对照表

配置改完后，必须完全关闭终端再新开，只重启 claude 会话不生效。这是 2.1.121 的已知行为。

4. 验证请求：从 tools/list 到成功结果的全链路检查

配置写完不算完，得验证。验证分三步：模型层验证、MCP 连接层验证、工具调用层验证。

4.1 模型层验证

新开终端，启动 Claude Code，输入一个简单问题，看模型是否按你配置的模型 ID 响应。如果还是旧模型，检查.claude/settings.json的环境变量是否写对，路径是否准确。可以用echo $ANTHROPIC_MODEL在终端里确认环境变量是否加载。

4.2 MCP 连接层验证

启动 Claude Code 后，查看 MCP Server 状态。如果显示connected，说明 JSON-RPC 握手成功。如果显示failed，说明协议层有问题。常见原因是手写裸协议、SDK 版本不对、tools/list响应格式错误。

验证tools/list是否正常，可以在服务端加日志：

server.tool("ping", "测试连通性", {}, async () => { console.error("tools/list 被调用"); return { content: [{ type: "text", text: "pong" }] }; });

启动后如果 stderr 输出tools/list 被调用，说明协议通信正常。

4.3 工具调用层验证

在 Claude Code 里输入提示词，明确要求调用指定工具。比如：

请调用 project-interview-skill 提供的 analyze-interview-project 工具，分析当前项目，完成业务背景、架构、技术栈、核心流程、难点复盘、技术亮点、高频定制面试问答，生成一份完整的面试复习笔记，保存为 Project_Interview_Note.md 到项目根目录。

如果工具被调用并生成文件，说明全链路通了。如果提示 Unknown command，检查 slashCommands 配置和终端是否完全重启。

4.4 成功结果对照

全绿说明搭建成功。任何一项红，对照下一节排查。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 对照表

这一节把七个报错点逐个拆开，给出真实报错信息和修复动作。

5.1 报错一：模型改了不生效，回弹旧模型

报错现象：.claude.json根节点写了"model": "xxx"，重启后还是旧模型。

根因：Claude Code 模型分两层控制，表层.claude.json易被会话缓存覆盖，底层.claude/settings.json环境变量才是最终强制生效层。

修复：把模型配置写到.claude/settings.json的env节点，用ANTHROPIC_MODEL和ANTHROPIC_DEFAULT_XXX_MODEL锁死。

5.2 报错二：MCP 启动 failed

报错现象：MCP Server 状态显示failed，日志里可能有local proxy failed或协议校验错误。

根因：手写裸 JSON-RPC，字段不全，没走标准 MCP 生命周期。新版 Claude Code 有强协议校验。

修复：安装@modelcontextprotocol/sdk，用McpServer和StdioServerTransport标准写法，确保tools/list正确响应。

5.3 报错三：401 鉴权失败

报错现象：请求返回 401，提示鉴权失败。

根因：API Key 没配、配错位置、或者 Base URL 带了多余参数。

修复：检查.claude/settings.json里ANTHROPIC_API_KEY是否正确，ANTHROPIC_BASE_URL是否为https://taotoken.net/api，不要加 UTM 参数。Key 从 API Keys 页面重新获取。

5.4 报错四：reading choices 解析错误

报错现象：日志里出现reading choices相关解析错误。

根因：模型返回格式与客户端预期不一致，通常是模型 ID 配错或 Base URL 指向了不兼容的端点。

修复：确认模型 ID 与接入文档一致，Base URL 用标准 API 地址。如果用的是兼容层，检查返回结构是否符合 Anthropic 格式。

5.5 报错五：OAuth 相关报错

报错现象：提示 OAuth 认证失败或 token 过期。

根因：Claude Code 某些版本会走 OAuth 流程，如果环境变量没覆盖，会尝试默认认证。

修复：确保ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL都正确设置，环境变量优先级高于 OAuth 默认流程。

5.6 报错六：Windows 路径转义错误

报错现象：MCP Server 启动失败，日志提示路径不存在或 JSON 解析错误。

根因：JSON 里单反斜杠\会被转义，C:\Users\DELL写成单斜杠直接报错。

修复：路径用双反斜杠C:\\Users\\DELL\\.claude\\skills\\project-interview\\server.js，或者用正斜杠C:/Users/DELL/.claude/skills/project-interview/server.js。

5.7 报错七：Unknown command 与权限弹窗

报错现象：slashCommands 配置正确但提示 Unknown command；每次调用工具弹权限确认框。

根因：2.1.121 版本 slashCommands 加载时机问题，改完.claude.json只重启会话不生效，必须完全关闭终端再新开。权限弹窗是因为没有全局信任标记。

修复：完全退出 Claude Code，关闭终端，新开终端再启动。权限方面加"alwaysLoad": true，注意这个在 2.1.121 里只对当前项目生效，换项目还会问。

5.8 通用易错清单

排查顺序建议：先看模型层，再看 MCP 连接层，最后看工具调用层。每层验证通过再进下一层，不要跳步。

6. 语义一致 CTA：接入文档与 API Keys 是排障终点

搭建 Claude Code MCP 的过程，本质是把模型接入层、配置层、协议层三层对齐。模型层用 TaoToken 的 API 地址和 Key 锁死，配置层分清.claude.json和.claude/settings.json的优先级，协议层用官方 SDK 走标准 JSON-RPC。

如果你在排障过程中遇到 401、local proxy failed、reading choices 解析错误，优先检查 API Keys 和接入文档。Key 从 API Keys 页面获取，配置细节看接入文档。需要验证模型对话效果，用模型对话页面。长期跑编码任务或 Agent 工作流，考虑 Coding Plan。

最后给一个实用技巧：每次改完配置，先完全关闭终端，再新开终端启动 Claude Code。这个动作能解决大部分「配置写了不生效」的问题。另外，MCP Server 的日志输出到 stderr，启动时留意终端输出，能快速定位协议层问题。路径统一用双反斜杠，工具名和描述写精准，基本就能一次跑通。