D9 · MCP · Claude Code 学习站

Claude 的一切行动都通过工具完成,但内置工具只覆盖「本机文件 + shell + 网页」。MCP 让你把 issue 跟踪器、数据库、浏览器、监控系统变成 Claude 能直接调用的工具。本课讲协议本身、接入与管理、以及代价。

为什么这天学这个

D1 讲过:agentic loop 里模型每一步都在「从工具列表里挑一个工具来执行」。工具列表有多长,Claude 的行动半径就有多大。前两课的 Skills 和 Hooks 分别解决「知识注入」和「流程拦截」,但都没有给 Claude 增加新的行动能力——MCP 补的正是这一块:把外部系统包装成新工具,插进那张工具列表。

学完本课,D10 Subagents 里给子代理分配工具、D14 Plugins 里插件捆绑 MCP server 分发,才有讨论的基础。跳过这课,后面凡是出现 mcp__... 前缀的工具名你都会看不懂它从哪来。

概念讲清楚

MCP 是什么

官方MCP(Model Context Protocol)是一个开源标准,专门规范「AI 应用如何接入外部工具」。工具由 MCP server 提供——server 可以是你本机跑的一个进程,也可以是云端托管的服务;Claude Code 作为 client 去连接它们,连上之后 server 提供的工具、资源(resources)、提示词(prompts)都可以在会话里用。

本站观点类比:MCP 之于 AI 工具,相当于 USB-C 之于外设。Claude Code 只需要实现一个「插口」(协议),任何按协议实现的 server 插上就能用,不需要为每个服务写专门的集成。什么时候该接一个 server?官方给的判断标准很实用:官方当你发现自己反复把别的工具里的数据(issue 内容、监控面板数字、数据库查询结果)复制粘贴进对话时,就该把那个系统接成 server,让 Claude 直接读写。

接入方式:stdio、HTTP、SSE(与 WebSocket)

官方server 按「跑在哪、怎么通信」分几种 transport:

transport	跑在哪	怎么加	适用场景
`stdio`	本机子进程,Claude Code 负责启动	默认 transport,`claude mcp add <name> -- <命令>`	需要本地资源:浏览器、文件系统、数据库 socket
`http`	远程 URL,云服务托管	`--transport http`,支持 OAuth 登录	远程服务的推荐方式(Notion、Sentry、GitHub 等)
`sse`	远程 URL	`--transport sse`	已弃用,仅用于只提供 SSE 端点的旧服务
`ws`	远程 URL,持久双向连接	只能通过 `.mcp.json` 或 `add-json` 配置,不支持 OAuth	server 需要主动向 Claude 推送事件时

官方stdio 命令里的 -- 分隔符很关键:它前面是 Claude Code 自己的选项(--transport、--env、--scope),后面整段原样作为 server 的启动命令。漏掉 --,server 自己的 flag 会被 Claude Code 误当成自己的选项解析。

Claude Code 作为 MCP client,同时连接多个 server;每个 server 的工具以 mcp__<server>__<tool> 的名字进入工具列表。

claude mcp:加、管、删

官方管理 server 的命令都在 claude mcp 下,在终端运行(不是在 claude 会话里);会话内用 /mcp 面板查看状态、认证、临时开关某个 server:

# 加远程 HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 加本机 stdio server(-- 后面是启动命令)
claude mcp add playwright -- npx -y @playwright/mcp@latest

# 带环境变量 / 带静态 token
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer <token>"

# 查、看、删
claude mcp list          # 列出所有 server 和连接状态
claude mcp get notion    # 看单个 server 的详情与 scope
claude mcp remove notion

官方claude mcp add 打印 Added ... 只代表配置写入成功,不代表能连上;要用 claude mcp list 看真实状态:✔ Connected、! Needs authentication、✘ Failed to connect 等。stdio server 第一次检查可能因 npx 还在下载而显示失败,稍等重试即可。

scope:配置放在哪,给谁用

官方加 server 时用 --scope 决定配置的归属,共三档:

scope	存在哪	生效范围	团队共享
`local`(默认)	`~/.claude.json` 里当前项目的条目下	只有你,只在本项目	否
`project`	项目根的 `.mcp.json`	本项目所有人	是,提交进版本库
`user`	`~/.claude.json` 顶层 `mcpServers`	只有你,所有项目	否

官方两条容易踩的规则:一,project scope 的 server 出于安全首次使用前会弹批准提示(克隆下来的仓库不能未经你同意就在你机器上启动进程),拒绝过想重来用 claude mcp reset-project-choices;二,同名 server 在多个 scope 都有定义时,按 local > project > user > 插件 > claude.ai connector 的优先级取整条定义,字段不跨 scope 合并。scope 加完即固定,想换 scope 只能 remove 后重加。

认证:OAuth 与 token

官方很多云端 server(Sentry、Linear、Notion 等)走 OAuth 2.0:先 claude mcp add 加上,此时 list 显示 ! Needs authentication;再在会话里运行 /mcp 选中该 server 选 Authenticate,浏览器完成登录;或者直接在终端跑 claude mcp login <name>(v2.1.186 起)。token 会被安全存储并自动刷新,claude mcp logout <name> 清除。用静态 token 认证的服务(如 GitHub 的 PAT)则在 add 时用 --header "Authorization: Bearer <token>" 传入。另外,你在 claude.ai 网页端添加并登录过的 connector,用同一订阅账号登录 Claude Code 时会自动出现在 /mcp 列表里。

工具怎么进入工具列表,花多少上下文

官方server 连上后,它的每个工具以 mcp__<server>__<tool> 的名字进入 Claude 的工具列表(例如 mcp__github__get_issue),权限规则、hooks、subagent 的工具配置都用这个全名引用;Claude 首次调用某个新工具时会请求你授权。

官方成本方面:每个已连接的 server 的工具名和 server instructions 会加载进每一个会话的上下文窗口。好消息是 tool search 默认开启——完整的工具定义被推迟(defer),Claude 需要时才通过搜索按需加载,所以多接几个 server 对上下文的冲击比早期小得多;此外单次 MCP 工具输出超过 10,000 tokens 会警告,默认上限 25,000 tokens(MAX_MCP_OUTPUT_TOKENS 可调)。本站观点但「影响小」不等于免费:工具名、instructions、以及每次真实调用的输出都持续占用 D2 讲过的那个有限窗口。server 装了一堆却变慢变笨的诊断与治理,见 Tip 「MCP server 装多了会怎样」。

当天能做完的实操

用官方教程里那个免认证的文档搜索 server 走完「加 → 验 → 用 → 删」全流程,30 分钟内可完成:

在终端(不要在 claude 会话里)注册 server:预期打印 Added HTTP MCP server claude-code-docs ... 和一行 File modified: 指明写入了哪个配置文件。
运行 claude mcp list:预期该 server 显示 ✔ Connected。
运行 claude 进入会话,粘贴下面的 prompt。预期:首次调用弹出工具授权,批准后回答里的工具调用带着 claude-code-docs 的 server 名——这就是答案来自 MCP server 而非模型记忆的证据。
运行 claude mcp get claude-code-docs:预期看到它登记在 local scope。想让它在你所有项目可用,先 remove 再加 --scope user 重新添加。
清理(可选):claude mcp remove claude-code-docs,预期打印 Removed ... 确认。

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list
claude
# ……会话内实验后……
claude mcp remove claude-code-docs

用 claude-code-docs 这个 MCP server 查一下 MCP_TIMEOUT 环境变量是干什么的,
并告诉我你是通过哪个工具调用拿到答案的。

验收标准

能不看笔记说清:MCP 是什么协议,server 和 client 分别指谁,server 能提供哪三类东西(tools / resources / prompts)。
能说出 stdio 和 HTTP 两种 transport 的本质区别(本机子进程 vs 远程 URL),以及 SSE 的现状(已弃用)。
能画出三个 scope 各自的存放文件和生效范围,并解释 project scope 为什么要弹批准提示。
实操五步全部跑通,且能指出会话输出里哪一处证明答案来自 MCP server。
自测题:同一个名字的 server 同时定义在你的 local scope 和仓库的 .mcp.json 里,你连到哪份配置?克隆仓库的同事呢?(参考答案:你连 local 那份——local 优先于 project,整条定义生效、字段不合并;同事机器上没有你的 ~/.claude.json 条目,连 .mcp.json 那份,且首次使用前要先批准。)