Claude Code 小课 · 2026年8月17日

2026-08-17 · 主题:MCP 服务器配置(claude mcp 全套命令、三种作用域、认证三形态、上下文成本与排障)

前 10 课覆盖了 CLAUDE.md、Plan Mode、Subagents、Hooks、复杂需求交付、斜杠命令、新功能速用、防漂移、上下文管理、权限与沙箱、会话管理。这一课补上最后一块基础设施:怎么给 Claude Code 接外部工具。四条技巧由浅入深。

技巧 1(入门):三步接一个 server —— add → list → 用

别一上来就配 GitHub、Notion 这些要 OAuth 的。先拿 Anthropic 自家的文档 server 跑通流程,它不需要任何认证:

# 在终端里运行,不是在 claude 会话里
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

命令四个部分各是什么:

部分	含义
`claude mcp add`	注册一个 server
`--transport http`	这个 server 挂在 URL 上,不是本地进程
`claude-code-docs`	你自己起的名字,叫 `docs` 也一样;它决定工具在输出里的标签
`https://...`	server 的地址

然后一定要 verify——Added 只代表条目写进去了,不代表连得上:

claude mcp list

对着状态表读:

✔ Connected —— 好了
! Connected · tools fetch failed —— 连上但列不出工具,claude mcp get <name> 看详情
! Needs authentication —— 需要浏览器登录或 token(见技巧 3)
✘ Failed to connect / ✘ Connection error —— 见技巧 4
⏸ Pending approval —— project 作用域的 server 你还没批准

本地 stdio server 写法不同,没有 --transport,-- 之后全是启动命令:

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

小坑:第一次 claude mcp list 可能显示 ✘ Failed to connect,因为 npx 还在下包。等一会儿再跑一次。

📖 Connect to MCP servers · Claude Code Docs

技巧 2(进阶):搞清三个作用域,别再「昨天还能用今天没了」

最常见的困惑是:「我明明加过这个 server,/mcp 却说 No MCP servers configured」。原因几乎总是作用域用错了。

claude mcp add 默认写的是 local 作用域——只对你、且只在当前项目生效。三种作用域落盘位置如下:

作用域	文件	谁能用
`local`(默认)	`~/.claude.json`,挂在当前项目路径那一条下面	只有你,只在这个项目
`project`	项目根目录的 `.mcp.json`	所有 clone 这个仓库的人
`user`	`~/.claude.json` 顶层的 `mcpServers` 键	只有你,所有项目

作用域在添加时就定死了,改作用域 = 删了重加:

# 自己所有项目都要用 → user
claude mcp remove claude-code-docs --scope local
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

# 要和队友共享 → project(写进 .mcp.json,提交到 git)
claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

不确定某个 server 在哪个作用域?claude mcp get <name> 会告诉你。

团队场景直接手写 .mcp.json —— 它是唯一进版本库的那份,当作 configuration-as-code 来维护最合适:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

队友 clone 后启动 Claude Code 会看到一次批准提示——这道提示是故意的,防止你 clone 来的仓库在你机器上随便起进程。

⚠️ 路径别猜。Claude Code 只读 ~/.claude.json 和 <project>/.mcp.json。~/.claude/mcp.json、~/.claude/config/mcp.json、%APPDATA%\Claude\mcp.json 这些都不读,写了也白写。

📖 Where servers are saved

技巧 3(进阶):认证的三种形态,对号入座

! Needs authentication 或者「连上了但一个工具都没有」,基本就是认证问题。分三种,处理方式完全不同:

① OAuth 浏览器登录(Sentry / Linear / Notion 这类托管服务):

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# 此时 list 显示 ! Needs authentication,这是正常的
claude

进会话后 /mcp → 选中 sentry → 回车 → Authenticate,浏览器打开完成授权。

也可以完全不进交互菜单,直接在 shell 里做(v2.1.185+):

claude mcp login sentry     # 认证
claude mcp logout sentry    # 清掉存的凭据

② 静态 token(GitHub 这类):token 在 add 的时候用 header 传:

claude mcp add --transport http github https://api.githubcopilot.com/mcp \
  --header "Authorization: Bearer <token>"

③ 环境变量(server 自己要 API key,典型症状是「连上了但工具列表是空的」):

claude mcp add my-server --env API_KEY=xxx -- npx -y some-mcp-server

或者在 .mcp.json 条目里写 env 字段。

排查技巧:claude mcp list 会标记出配置值里藏着的首尾空格——粘贴 token 时最容易踩、也最难肉眼看出来的一类失败。

📖 Connect a server that requires sign-in · Week 26 digest(claude mcp login)

技巧 4(高阶):把 MCP 当上下文预算来管,并建立一套排障顺序

先说最容易被忽略的一点:每个已连接的 server 都在花你的上下文。 官方文档写得很直白——server 的工具名和 server instructions 会加载进每一个会话。接了八个 server,你还没说第一句话,上下文就已经被啃掉一块了。所以:

claude mcp remove <name>   # 不用的就删,别囤着

配合第 8 课的上下文预算思路,进会话后用 /usage 看各 MCP server 分别占了多少——/usage 会按 skill、subagent、plugin、MCP server 拆开展示什么在推高你的用量。

排障请按这个顺序走,别乱试:

# 1. 先看状态和详情(v2.1.219 起 Failed to connect 会直接带上 HTTP 状态码/错误文本)
claude mcp list
claude mcp get <name>

# 2. HTTP server:确认 URL 从你这台机器可达
curl -I https://mcp.sentry.dev/mcp
#    404 / 405 → server 活着(很多 MCP 端点只answer POST),URL 没问题
#    401 / 403 → 活着,但要认证 → 回技巧 3
#    毫无响应   → URL 或网络问题
# (PowerShell 里要写 curl.exe,否则走的是 Invoke-WebRequest 别名)

# 3. stdio server:直接在终端跑那条命令,看真实报错
npx -y @playwright/mcp@latest
#    能起来并等输入 → server 没问题,是你的配置错了
#    (最常见:add 时漏了 -- 分隔符,用 claude mcp get 对一下命令)

# 4. 启动超时(默认 30 秒,首次 npx 下包常超)
MCP_TIMEOUT=60000 claude
#    PowerShell: $env:MCP_TIMEOUT = "60000"; claude

# 5. 改了 .mcp.json 不生效 → 它只在会话启动时读,重启会话
#    还是不出现 → /mcp 看有没有 parse warning(格式错的条目会被静默跳过)
#    之前手滑拒绝过 → 重置项目批准记录:
claude mcp reset-project-choices

最后两个进阶用法,顺手记一下:

@ 提及可以直接引用 MCP resource,/ 菜单里可以把 MCP prompt 当命令跑
组织级管控走 managed MCP settings,而不是让每个人自己 claude mcp add

📖 Troubleshooting · MCP quickstart · MCP reference

一句话总结

add 完必须 list 验证;作用域决定它明天还在不在;认证分 OAuth / header / env 三种对号入座;不用的 server 要删,因为它一直在吃你的上下文。

下期预告(候选):无头模式 claude -p 与 CI 集成 · git worktree 并行开发 · Skills 编写 · 成本控制。