1. 为什么 Claude Code 需要 MCP 才能碰到本地服务
Claude Code 本身是个很强的代码生成器，但它默认只能读写你当前项目目录里的文件，跑跑 shell 命令。一旦你想让它去查蓝耘上的模型推理结果、读本地某个服务的日志、或者调一个跑在 127.0.0.1 上的接口，它就抓瞎了。MCP（Model Context Protocol）就是补上这块短板的协议层，它把「本地服务能做什么」抽象成一组工具（tools）和资源（resources），Claude Code 作为客户端去消费这些能力。
我试过最直观的场景：你让 Claude Code 帮你写了个 FastAPI 接口，它写完了，你想让它自己 curl 一下验证返回。没有 MCP 的时候，你得手动复制命令去终端跑，再把报错贴回来。有了 MCP，Claude Code 可以直接调用一个叫http_request的工具，自己发请求、自己看响应、自己改代码。蓝耘在这里的角色是提供本地算力和模型服务，你通过 MCP 把蓝耘的 API 封装成工具，Claude Code 就能在对话里直接调用蓝耘的模型做推理，而不是只能靠云端那个默认模型。
适合谁看：已经有蓝耘账号、本地装了 Node.js 和 Claude Code、想让 AI 编程工具直接调用本地算力或本地服务的开发者。如果你还没装 Claude Code，下面会带一句安装命令，但重点在 MCP 配置和连通性验证。
核心检索词先摆出来：MCP 协议、Claude Code、蓝耘、AI 编程工具、本地服务。这四个词贯穿全文，你搜到这篇大概率就是卡在「怎么把本地服务接进 Claude Code」这一步。
先说清楚一个常见误解：MCP 不是让 Claude Code 变成万能遥控器，它只是定义了一套 JSON-RPC 的通信格式。服务端暴露什么能力，客户端才能用什么能力。所以你得先写一个 MCP 服务端，把蓝耘的 API 或者本地服务包装成工具，然后在 Claude Code 的 settings 里注册这个服务端。两步缺一不可。
另外，Claude Code 默认走的是 Anthropic 的 API 端点。如果你想把模型请求也切到 TaoToken 这类兼容端点，需要在环境变量或 settings 里改 Base URL。这一步和 MCP 配置是独立的，但经常一起出现，因为很多人既想用 MCP 调本地工具，又想用更灵活的 API 端点跑模型。下面会分开讲，避免混在一起排障时抓瞎。
2. TaoToken 前置准备与蓝耘 API Key 获取
在写 MCP 服务端之前，先把两个 Key 准备好：蓝耘的 API Key 和 TaoToken 的 API Key。蓝耘的 Key 用来让 MCP 服务端能调蓝耘的模型或算力接口；TaoToken 的 Key 用来让 Claude Code 的模型请求走 TaoToken 的兼容端点。两者用途不同，别搞混。
蓝耘 API Key 的获取路径：登录蓝耘控制台，找到 API Key 管理页面，生成一个 Key。这个 Key 通常是一串以sk-开头的字符串。把它存到环境变量里，别硬编码在代码里。比如在~/.zshrc或~/.bashrc里加一行：
export LANYUN_API_KEY="sk-你的蓝耘key"然后source ~/.zshrc让它生效。验证一下：
echo $LANYUN_API_KEY能打印出 Key 就说明环境变量没问题。
TaoToken 这边，你需要去官网注册并生成 API Key。地址是https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。注册后在控制台的 API Keys 页面生成 Key，同样存到环境变量：
export TAOTOKEN_API_KEY="sk-你的taotoken key"TaoToken 的 API 端点基础地址是https://taotoken.net/api，这个后面配置 Claude Code 的 Base URL 时会用到。注意这个地址不带 UTM 参数，直接写进配置里就行。
Node.js 版本确认一下，MCP SDK 要求 v18 以上：
node -v npm -v如果低于 18，去 Node.js 官网下个 LTS 版本装上。Claude Code 的安装命令是一行：
npm install -g @anthropic-ai/claude-code装完后claude --version能打印版本号就 OK。
这里插一句关于 TaoToken 的定位：它提供的是 OpenAI 兼容的 API 端点，所以 Claude Code 里改 Base URL 的时候，格式和改 OpenAI 端点类似。但 Claude Code 本身是 Anthropic 系的工具，它的配置字段名可能和纯 OpenAI 客户端不一样，下面会给出具体的 settings 片段。
还有一个前置检查：确认你的本地服务或蓝耘接口能通。比如蓝耘的 API 端点，你可以先用 curl 测一下：
curl -X POST https://api.lanyun.net/v1/chat/completions \ -H "Authorization: Bearer $LANYUN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"你的模型ID","messages":[{"role":"user","content":"ping"}]}'如果返回 401，说明 Key 不对；如果返回 404，说明端点路径不对；如果返回 200 但内容为空，检查模型 ID。这一步别跳过，否则后面 MCP 调不通你会以为是 MCP 配置问题，其实是 Key 或端点错了。
TaoToken 的 Key 也测一下：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'能返回 choices 数组就说明 Key 和端点都通。这两个 curl 测试是后面排障的基线，记住它们。
3. 可复制的 MCP 服务端与 Claude Code settings 配置
这一节是全文的核心，所有配置片段都可以直接复制。先建一个目录放 MCP 服务端代码：
mkdir -p ~/mcp-lanyun && cd ~/mcp-lanyun npm init -y npm install @modelcontextprotocol/sdk然后创建mcp-server.js，内容如下。这个服务端暴露两个工具：lanyun_chat用来调蓝耘的模型接口，read_local_file用来读本地文件（演示本地服务能力）。
import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new Server( { name: "lanyun-mcp-server", version: "1.0.0" }, { capabilities: { tools: {} } } ); server.setRequestHandler("tools/list", async () => ({ tools: [ { name: "lanyun_chat", description: "调用蓝耘模型接口进行对话", inputSchema: { type: "object", properties: { prompt: { type: "string", description: "用户输入" } }, required: ["prompt"] } }, { name: "read_local_file", description: "读取本地文件内容", inputSchema: { type: "object", properties: { path: { type: "string", description: "文件绝对路径" } }, required: ["path"] } } ] })); server.setRequestHandler("tools/call", async (request) => { const { name, arguments: args } = request.params; if (name === "lanyun_chat") { const resp = await fetch("https://api.lanyun.net/v1/chat/completions", { method: "POST", headers: { "Authorization": `Bearer ${process.env.LANYUN_API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ model: "你的蓝耘模型ID", messages: [{ role: "user", content: args.prompt }] }) }); const data = await resp.json(); return { content: [{ type: "text", text: JSON.stringify(data.choices?.[0]?.message ?? data) }] }; } if (name === "read_local_file") { const fs = await import("fs/promises"); const content = await fs.readFile(args.path, "utf-8"); return { content: [{ type: "text", text: content }] }; } throw new Error(`Unknown tool: ${name}`); }); const transport = new StdioServerTransport(); await server.connect(transport);注意model字段要换成你蓝耘控制台里实际的模型 ID，别照抄。LANYUN_API_KEY从环境变量读，所以启动这个服务端之前要确保环境变量已经 export。
接下来配置 Claude Code。在项目根目录创建.claude/settings.json，内容如下：
{ "mcpServers": { "lanyun-local": { "command": "node", "args": ["/Users/你的用户名/mcp-lanyun/mcp-server.js"], "env": { "LANYUN_API_KEY": "sk-你的蓝耘key" } } }, "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的taotoken key" } }这里有两个关键点。第一，mcpServers里的args必须写绝对路径，相对路径在 Claude Code 启动时的工作目录不确定，容易找不到文件。第二，env里的ANTHROPIC_BASE_URL改成 TaoToken 的 API 地址，ANTHROPIC_API_KEY填 TaoToken 的 Key。这样 Claude Code 的模型请求走 TaoToken，MCP 工具调用走本地服务端，两条链路分开。
如果你用的是 Claude Code 的全局配置而不是项目级配置，路径在~/.claude/settings.json，字段结构一样。项目级配置优先级更高，建议先用项目级测试。
配置写完后，重启 Claude Code。在项目目录下运行claude，然后输入/mcp命令，应该能看到lanyun-local这个服务端的状态是 connected。如果显示 failed，看下一节的排障。
还有一个细节：Claude Code 的 settings 里env字段的ANTHROPIC_BASE_URL是否生效，取决于你用的 Claude Code 版本。有些版本读的是ANTHROPIC_BASE_URL，有些读的是ANTHROPIC_API_BASE。如果改完发现模型请求还是走默认端点，检查一下版本，或者直接在 shell 里 export 这两个变量做兜底：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的taotoken key"这样无论 settings 读哪个字段，环境变量都能覆盖。
4. 验证 MCP 连通性与一次本地工具调用
配置写完了，怎么确认真的通了？分两步：先验证 MCP 服务端本身能跑，再验证 Claude Code 能调到它。
第一步，单独跑 MCP 服务端，看它能不能正常启动：
cd ~/mcp-lanyun LANYUN_API_KEY="sk-你的蓝耘key" node mcp-server.js如果没有任何报错，光标停在那里，说明服务端在等 stdio 输入，这是正常的。按 Ctrl+C 退出。如果报Cannot find module，说明npm install没跑或者路径不对；如果报LANYUN_API_KEY is undefined，说明环境变量没传进去。
第二步，在 Claude Code 里发一条指令，让它调用lanyun_chat工具。启动 Claude Code：
cd 你的项目目录 claude然后在对话里输入：
请调用 lanyun_chat 工具，prompt 参数填 "用一句话解释什么是 MCP 协议"Claude Code 应该会弹出一个工具调用确认，你按回车允许。如果一切正常，它会返回蓝耘模型的回复。这个过程你能看到 Claude Code 的界面上显示Calling tool: lanyun_chat，然后返回结果。
如果这一步成功了，说明 MCP 链路通了。再测一下read_local_file：
请调用 read_local_file 工具，读取 /etc/hosts 文件的前几行这个工具读的是本地文件，验证的是 MCP 服务端对本地环境的访问能力。如果返回了 hosts 文件内容，说明本地服务能力也通了。
第三步，验证 TaoToken 的模型请求。在 Claude Code 里直接问一个普通问题，比如「写一个 Python 的快速排序」，然后看它的响应。如果响应正常，说明ANTHROPIC_BASE_URL改到 TaoToken 生效了。你可以通过查看 TaoToken 控制台的用量记录来确认请求确实走了 TaoToken，而不是默认端点。
这里有个实测细节：Claude Code 在调用 MCP 工具时，可能会同时发起模型请求和工具请求。如果 TaoToken 的并发限制比较严，可能会看到工具调用成功但模型回复延迟。这时候检查 TaoToken 控制台的并发设置，或者把 MCP 工具调用和模型请求错开测试。
成功的结果长这样：Claude Code 界面上先显示工具调用，然后显示工具返回的文本，最后模型基于工具返回的内容继续对话。整个链路是：你的输入 → Claude Code → MCP 服务端 → 蓝耘 API → 返回 → Claude Code → 显示给你。中间任何一环断了，都会在界面上看到对应的错误。
如果lanyun_chat返回的是{"error": "invalid api key"}，说明蓝耘 Key 不对；如果返回{"error": "model not found"}，说明模型 ID 写错了；如果 Claude Code 显示MCP server lanyun-local failed to start，说明args路径不对或者 Node.js 版本太低。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节按真实报错来，每个报错给出原因和修法。
401 Unauthorized：最常见。出现在两个地方。一是 MCP 服务端调蓝耘时返回 401，说明LANYUN_API_KEY不对或没传进服务端。检查.claude/settings.json里mcpServers.lanyun-local.env.LANYUN_API_KEY是否填了正确的 Key，或者 shell 里有没有 export。二是 Claude Code 调 TaoToken 时返回 401，说明ANTHROPIC_API_KEY不对。检查 settings 里的env.ANTHROPIC_API_KEY或者 shell 里的TAOTOKEN_API_KEY。注意 TaoToken 的 Key 和蓝耘的 Key 是两套，别混用。
local proxy failed：这个报错通常出现在 Claude Code 启动时，提示无法连接到本地代理或 MCP 服务端。原因一般是mcpServers里的command或args路径不对。比如你写了"command": "node"但系统 PATH 里 node 不在默认位置，或者args用了相对路径。修法：把command改成 node 的绝对路径，用which node查；args改成 MCP 服务端 JS 文件的绝对路径。另外检查 MCP 服务端有没有语法错误，单独跑一次node mcp-server.js看能不能启动。
reading choices 报错：这个报错一般出现在模型返回的 JSON 结构不符合预期时。比如你调蓝耘接口，返回的不是标准的choices数组，而 MCP 服务端代码里写了data.choices[0]，就会报Cannot read properties of undefined (reading 'choices')。修法：在 MCP 服务端里加一层判断，先打印data看实际返回结构，再决定取哪个字段。蓝耘的接口如果和 OpenAI 不完全兼容，字段名可能不一样。另外 TaoToken 返回的也是 OpenAI 兼容格式，如果 Claude Code 报 reading choices，检查 TaoToken 的响应是否被中间层改过。
OAuth 相关报错：Claude Code 某些版本会尝试 OAuth 登录，如果你改了 Base URL 到 TaoToken，OAuth 流程可能走不通，报OAuth token exchange failed或invalid_grant。修法：在 settings 里显式设置ANTHROPIC_API_KEY，让 Claude Code 走 API Key 认证而不是 OAuth。如果还是报 OAuth 错误，检查 Claude Code 版本，升级到最新版，或者在启动时加--api-key参数。有些版本需要设置CLAUDE_CODE_USE_API_KEY=true环境变量来强制走 Key 认证。
MCP 工具调用无响应：Claude Code 显示调用了工具，但一直卡住不返回。原因可能是 MCP 服务端里的 fetch 请求超时，或者蓝耘接口响应太慢。修法：在 MCP 服务端的 fetch 里加AbortController设置超时，比如 30 秒。另外检查蓝耘接口的延迟，如果延迟太高，考虑换模型或换端点。
settings.json 不生效：改完配置重启 Claude Code 后，/mcp里看不到服务端。检查文件路径是不是.claude/settings.json（项目根目录下），而不是settings.json放在别处。另外 JSON 格式必须严格，多一个逗号都会导致解析失败。用cat .claude/settings.json | python -m json.tool验证 JSON 合法性。
CC Switch / Cline MCP / Codex auth.json 三件套：如果你同时用多个 AI 编程工具，注意每个工具的配置格式不一样。CC Switch 用的是自己的配置文件，Cline MCP 用的是 VS Code 的 settings，Codex 用的是auth.json。不管哪个工具，接入任何兼容端点都需要三件套：Base URL、API Key、Model ID。Base URL 填https://taotoken.net/api，API Key 填 TaoToken 的 Key，Model ID 填你要用的模型名。这三个字段缺一不可，少一个就会报认证或模型找不到的错误。
排障的通用思路：先单独测蓝耘接口（curl），再单独测 TaoToken 接口（curl），再单独跑 MCP 服务端（node），最后在 Claude Code 里测。逐层排除，别一上来就怀疑 Claude Code 本身。
6. 把 MCP 链路用起来：从验证到日常编码
连通性验证通过后，日常怎么用？最直接的方式是把 MCP 工具当成 Claude Code 的扩展能力。比如你让 Claude Code 写一个调用蓝耘模型的函数，写完直接让它用lanyun_chat工具测一下返回，不用你手动复制代码去跑。
再比如你本地有个日志文件，以前你得手动tail -f看，现在可以让 Claude Code 调read_local_file读日志，然后让它分析报错。整个过程在编辑器里完成，不用切终端。
如果你想让 MCP 服务端支持更多本地服务，比如查数据库、调本地 HTTP 接口，照着mcp-server.js里的tools/list和tools/call加就行。每加一个工具，在tools/list里声明 schema，在tools/call里实现逻辑。Claude Code 会自动发现新工具，不用改 Claude Code 的配置。
关于 TaoToken 的 Coding Plan，如果你长期用 Claude Code 做编码和 Agent 任务，可以了解一下它的套餐，比按量计费更适合高频使用。模型对话功能可以用来单独验证模型响应，API Keys 页面管理你的 Key，接入文档里有更详细的端点说明。这些入口在 TaoToken 控制台都能找到。
最后说一个实用技巧：MCP 服务端的日志默认走 stderr，Claude Code 不会显示。如果你想调试 MCP 服务端，在代码里用console.error打印日志，然后在启动 Claude Code 的终端里看 stderr 输出。这样能定位到具体是哪一步卡住了。
链路通了之后，你会发现 Claude Code 能做的事情多了一大截。以前它只能改代码，现在它能读日志、调接口、跑本地命令，真正变成一个能动手的编程助手。蓝耘的算力和模型通过 MCP 接进来，TaoToken 的端点让模型请求更灵活，两者配合起来，日常编码效率提升很明显。
