Claude Code 101：用 MCP 打通本地工具链的配置实战

1. 为什么你的 Claude Code 需要 MCPClaude Code 本身已经能读写文件、跑命令、查 Git但它默认只认识你当前这个代码仓库。真实开发里上下文往往散落在仓库之外接口文档在某个内部站点、数据库表结构在另一台机器、任务清单在项目管理工具里、日志在远端服务上。这些信息不在代码库里模型就看不见于是你只能手动复制粘贴来回切换窗口。MCPModel Context Protocol就是补这块短板的。它是一套让 Claude Code 连接外部工具和数据源的协议你可以把它理解成给 Claude Code 装扩展插槽插上一个数据库 MCP server它就能直接查表结构插上一个文档 MCP server它就能检索内部知识库。对刚接触 MCP 的开发者来说最容易卡住的不是概念而是配置写完不生效、/mcp里看不到、工具调用报错。这篇就聚焦一件事从零把 Claude Code 接入本地工具链给出可复制的settings.json与 MCP server 配置骨架再演示一次真实的工具调用验证让你跑通配置到生效的完整链路。适合已经装好 Claude Code、想接第一个 MCP server 的人。如果你还没配好模型接入可以先用 TaoToken 的 API Key 把底层通道打通再回来接 MCP顺序会更顺。2. 前置准备接入通道与 MCP 基础认知在写配置之前先把两件事理清楚否则后面报错你会分不清是通道问题还是 MCP 问题。第一是模型接入通道。Claude Code 需要一个可用的 API 端点TaoToken 提供兼容的接入方式你可以在 控制台 里创建 Key然后按 接入文档 配置环境变量。这一步和 MCP 是两回事但通道不通MCP 配得再对也调不动。第二是 MCP 的两种传输方式这决定了你配置怎么写传输方式适用场景配置关键字段stdio本地进程如本地脚本、本地数据库 CLIcommandargsHTTP远端服务如托管的知识库、SaaS 工具urlheadersstdio 是本地起一个子进程Claude Code 通过标准输入输出和它通信最常见也最好调试。HTTP 是连一个已经跑起来的服务端点。新手建议从 stdio 起步因为出问题时你能直接在终端手动跑一遍那个命令看它到底输出什么。还有一个概念要提前知道作用域scope。MCP server 可以配在三个层级——Local 只对当前项目生效、User 对你所有项目生效、Project 写进.mcp.json并可以提交到版本库让团队共用。选错作用域是配了但没生效的高频原因。3. 可复制的 settings.json 与 MCP server 配置骨架Claude Code 的 MCP 配置有两种落地方式用命令行claude mcp add添加或者直接写配置文件。命令行适合快速试配置文件适合版本化管理。我建议你两种都了解先看配置文件长什么样。项目级配置放在项目根目录的.mcp.json骨架如下{ mcpServers: { local-tools: { command: node, args: [/absolute/path/to/your-mcp-server/index.js], env: { TOOL_API_KEY: your-key-here } }, remote-docs: { type: http, url: https://your-mcp-endpoint.example.com/mcp, headers: { Authorization: Bearer your-token-here } } } }几个必须注意的点。command和args里的路径要用绝对路径相对路径在不同工作目录下会解析失败这是新手第一大坑。env用来给 stdio server 传环境变量别把密钥硬编码进args。HTTP 类型的 server 要显式写type: http否则 Claude Code 可能按 stdio 去解析直接报找不到命令。如果你更习惯命令行等价操作是claude mcp add local-tools --scope project -- node /absolute/path/to/your-mcp-server/index.js--scope可选local、user、project。加完之后 Claude Code 会把它写进对应层级的配置。想确认写到哪里了用claude mcp list这个命令会列出当前所有已注册的 server 及其作用域是排查到底配没配上的第一站。至于settings.json它管的是 Claude Code 自身的行为比如权限、环境变量、模型端点和 MCP server 列表是分开的。一个常见的settings.json片段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: your-taotoken-key }, permissions: { allow: [Bash(node:*)] } }注意ANTHROPIC_BASE_URL指向接入端点ANTHROPIC_API_KEY填你在 TaoToken 拿到的 Key。MCP 的 server 列表不要写进settings.json它属于.mcp.json或~/.claude.json的管辖范围混着写会导致加载不到。4. 验证一次工具调用从 /mcp 到真实生效配置写完不算完得看到工具真的被调用。验证分三步。第一步在 Claude Code 交互界面里输入斜杠命令/mcp它会列出所有已连接的 MCP server 和它们暴露的工具。如果这里看不到你刚配的 server别急着改配置先看下一节的排查清单。看到 server 名字后面跟着工具列表说明连接建立成功。第二步确认上下文开销。/mcp里同时会显示每个 server 占用的上下文比例。MCP 工具的描述会占用上下文窗口如果你接了一堆 server光工具描述就可能吃掉大量 token。经验值是如果 MCP 工具占用超过上下文窗口的 10%Claude Code 会自动切换到工具搜索模式按需发现工具而不是全量加载。所以不用的 server 记得在/mcp里禁用别让它白占位置。第三步发起一次真实调用。假设你接的是一个查询本地 SQLite 表结构的 server直接在对话里说用 local-tools 里的工具列出当前数据库所有表名和字段Claude Code 会先判断需要调用哪个工具然后弹出权限确认取决于你的permissions配置执行后把结果返回。你会看到类似这样的调用痕迹调用工具: query_schema 参数: { database: ./data/app.db } 结果: users(id, name, email), orders(id, user_id, amount)看到真实数据返回整条链路就通了。如果工具被调用但报错错误信息通常会指明是 server 进程崩了、参数不对还是权限被拒按信息定位即可。5. 本篇常见错误排查配 MCP 踩的坑高度集中我把最常见的几个列出来对照着查能省很多时间。/mcp里看不到 server。先确认作用域如果你在项目 A 配了 Local 作用域的 server切到项目 B 自然看不到。用claude mcp list看它注册在哪个层级。再确认配置文件位置对不对项目级必须是根目录的.mcp.json文件名和位置错一个字符都不行。stdio server 启动即退出。九成是路径问题。把command和args拼成一条命令在终端手动跑一遍node /absolute/path/to/your-mcp-server/index.js如果手动跑就报错那是 server 本身的问题跟 Claude Code 无关。如果手动能跑但 Claude Code 里不行检查env里的环境变量是不是漏了很多 server 依赖特定变量才能启动。HTTP server 连不上。检查url是否可达headers里的鉴权是否正确。用 curl 先验证端点curl -X POST https://your-mcp-endpoint.example.com/mcp \ -H Authorization: Bearer your-token-here \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:tools/list,id:1}能返回工具列表说明服务端没问题问题在 Claude Code 的配置格式上重点看type字段有没有写。工具调用被权限拦截。这是settings.json里permissions的锅。默认情况下 Claude Code 对工具调用会请求确认如果你配了白名单但没覆盖到就会被拒。要么在交互时手动允许要么把对应工具加进allow列表。上下文被工具描述撑爆。表现是响应变慢、模型开始忘事。回到/mcp禁用不常用的 server。如果你有一批低频但重要的能力考虑用 Skill 替代 MCPSkill 只把名称和描述加载进上下文真正需要时才加载完整内容比常驻的 MCP 工具省得多。6. 把 MCP 用顺的下一步跑通第一个 server 之后你会想接更多。这时候有两个方向值得投入。一是把配置版本化。项目级的.mcp.json提交到版本库团队里任何人拉下来就有一致的工具链不用各自配一遍。注意别把密钥提交进去用环境变量引用。二是区分场景选工具。日常编码、需要长期挂着的 Agent 类任务用 Coding Plan 会更省心它把接入和额度管理打包好了你专注在 MCP 配置上就行。想先验证某个模型接上 MCP 后的表现可以直接在 模型对话 里试一轮确认工具调用符合预期再落到项目里。如果你用的是 Claude Code 的 Anthropic 兼容模式ClaudeCodeAnthropic 接入说明 里有对应的端点配置细节。最后一句实操建议每接一个新 server先只接它一个用/mcp确认工具列表再发一次真实调用。确认没问题了再接下一个。一次性堆五个 server 再调试你会分不清是哪个在报错。