×−+
MCP第 7 课 · Claude Code 教程
第 7 课 · MCP

MCP：
给 Claude 发门禁卡

Claude Code 平时主要在你电脑上看代码、改代码。Sentry 上的报错、GitHub 上的 PR、数据库里的数据，都得你复制粘贴给它。MCP 像门禁卡和系统账号：连上之后，Claude 自己进去查、自己动手。

约 45 分钟 11 节 · 8 个动手练习 章末测验 改编自 luongnv89/claude-howto（MIT）
Claude Code每个 MCP 服务器
是一张门禁卡
点一张门禁卡
入门先用起来 原理弄懂为什么 实战动手练 深入进阶与避坑

时间紧就先看"入门"和"实战"；"原理"讲清楚密钥怎么放、服务器怎么占上下文，决定你能不能放心地把它交给团队。

01入门

MCP 是什么？

MCP（Model Context Protocol）是一套开放标准，让 AI 工具用同一种方式接入外部系统。每接入一个系统，就是连上一个"MCP 服务器"。

什么时候该连一个？官方给了个很好的判断标准：你发现自己总在把另一个工具里的东西复制到对话里。比如看同一个报错：

五样东西，各管一摊

学到这里，Claude Code 的五个核心概念你已经见过四个了。它们经常被混用，放在一起对比最清楚：

概念比喻管什么第几课
CLAUDE.md贴在工位上的员工守则每次都要知道的约定第 2 课
Skill书架上的操作手册某类任务的做法，用到才翻第 5 课
Hook自动打卡机到点一定执行的命令第 6 课
MCP门禁卡和系统账号能进哪些外部系统、能做什么操作本课
子代理找个同事帮忙把一块活交给另一个 Claude 单独做第 8 课
Skill 和 MCP 常一起用

MCP 给的是"能力"：能查 Sentry、能建 GitHub issue。Skill 给的是"做法"：查到报错之后按什么步骤排查、issue 怎么写。门禁卡让你进得去，操作手册告诉你进去之后怎么干。

02入门

连上第一个服务器

先用官方的文档服务器练手：不用注册、不用登录，四步走完添加、检查、使用、删除。

① 添加

在终端里运行（不是在 claude 对话里）：

终端
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
  • --transport http：服务器在网上，用网址连接。
  • claude-code-docs：你给它起的名字，叫 docs 也行。以后删除、查看都用这个名字。
  • 最后是服务器的网址。

② 检查

终端
claude mcp list
状态意思
✔ Connected连上了，可以用
! Needs authentication服务器在，但要先登录；也可能是它要令牌，得用 --header 带上（第 6 节）
✘ Failed to connect没连上，后面会附上原因（第 10 节）
⏸ Pending approval团队共享的服务器，你还没同意使用（第 4、7 节）
⊘ Disabled for this project在 /mcp 里被关掉了，没删除

③ 使用

启动 claude，说：用 claude-code-docs 查一下 MCP_TIMEOUT 是做什么的。第一次调用时会问你是否允许，批准即可。回答里的工具调用会标着服务器名，说明答案确实来自这个服务器。平时不用点名，Claude 会自己挑合适的工具。

④ 用完删掉（可选）

终端
claude mcp remove claude-code-docs
在对话里看状态

对话中输入 /mcp：列出所有服务器、各有几个工具，还能在里面登录、重连、临时关掉某个服务器。

03入门

远程还是本地：连接方式

服务器要么在网上（给一个网址），要么在你电脑上运行（给一条启动命令）。

方式是什么怎么加
http（推荐）网上的服务，Notion、Sentry、GitHub 都是这种claude mcp add --transport http 名字 网址
stdioClaude Code 在你电脑上启动一个程序，适合浏览器、本地文件、数据库claude mcp add 名字 -- 启动命令
sse旧的远程方式，已不推荐。新版本用 http 添加时会自动退回到 sse--transport sse
wsWebSocket，适合会主动推送消息的服务器只能写 JSON 配置
stdio 一定要写 --

-- 前面是 Claude Code 自己的选项（--env、--scope），后面是启动服务器的命令，原样交出去。漏掉它，命令里的 -y、--port 会被 Claude Code 当成自己的选项。

试一试：把别人的说明书翻译成 Claude Code 命令

很多服务器的安装说明是写给 Claude Desktop、Cursor 等其他工具的，不会直接给你 claude mcp add。看它给的是哪种东西：

说明书里写的

                
→

                
在终端里这样加

              

              

            

          


          
          

            

              04入门
              
存在哪里：三种范围

              
添加时用 --scope 决定这张门禁卡给谁、在哪些项目里有效。不写就是 local。

            

            

              

                
范围在哪些项目生效团队共享吗存在哪

                
                  
local（默认）只有当前项目不，只有你~/.claude.json 里这个项目的条目下

                  
project只有当前项目是，提交到 git项目根目录的 .mcp.json

                  
user你所有的项目不，只有你~/.claude.json 最外层

                
              

            

            
    
              
  • 同一个服务器在几处都定义了，只连一份，优先级：local > project > user > 插件提供的 > claude.ai 连接器。前三个范围按名字判断是不是同一个；插件和连接器按网址或启动命令判断。整条配置一起替换，不会逐项合并。
    • 
              
  • 注意：MCP 的 "local" 存在你家目录的 ~/.claude.json，和第 6 课的 .claude/settings.local.json 不是一回事。
    • 
              
  • 范围定了不能改，要换就 claude mcp remove 再用新的 --scope 加一次。
    • 
            


            
练一练：放哪个范围？

            

            

          


          
          

            

              05原理
              
Claude 怎么用这些工具

              
每个服务器提供若干"工具"。Claude 看到工具的名字和说明，自己决定什么时候调用哪一个。

            


            
    
              
  • 工具的全名是 mcp__服务器名__工具名，比如 mcp__github__create_issue。写权限规则、写 hook 的 matcher（第 6 课）都用这个名字。插件带来的服务器名字更长：mcp__plugin_插件名_服务器名__工具名（第 10 课），给它写规则、写 matcher 要用这个全名。
    • 
              
  • hook 也能调 MCP 工具：第 6 课提到的 mcp_tool 类型 hook，会在事件发生时直接调用某个服务器的工具，比如每次改完文件就调一次安全扫描。服务器要先连上，hook 不会替你登录；没连上就跳过，不会卡住。
    • 
              
  • 权限：和改文件一样，第一次用会问你。想一次允许某个服务器的所有工具，写规则 mcp__github 或 mcp__github__*。
    • 
              
  • 资源：有的服务器还提供可以直接引用的内容。输入 @ 会和文件一起列出来，格式如 @github:issue://123。
    • 
              
  • 提示词命令：服务器提供的提示词会变成斜杠命令，菜单里显示为 /服务器名:提示词名 (MCP)，也可以输入 /mcp__github__pr_review 456。
    • 
            


            
工具会占上下文吗？

            
每个工具都有一份说明（参数、用法），全部塞进上下文会很占地方。所以 Claude Code 默认开着工具搜索：对话开始时只加载工具的名字，真要用时再去取完整说明。勾选你连的服务器，对比一下：

            

              

              
全部提前加载

              
工具搜索（默认）

              

            

            
示意估算：工具数量和每份说明的长度因服务器而异，条形长度按 20 万 token 的上下文计算。

            
    
              
  • 个别服务器的工具每次都要用，可以在它的配置里写 "alwaysLoad": true，跳过搜索、启动时就全部加载。少用。
    • 
              
  • 例外：如果你通过第三方中转或代理使用 Claude Code（ANTHROPIC_BASE_URL 指向的不是官方地址），工具搜索默认是关的，所有工具说明一开始就全部加载。这时更要少连服务器；确认代理支持的话，可以设 ENABLE_TOOL_SEARCH=true 打开。
    • 
              
  • 工具的返回结果也占上下文：超过 1 万 token 会有警告，默认上限 2.5 万 token。超过上限的结果会整份存成文件，对话里只留一句文件路径，Claude 需要时再去读。上限可用环境变量 MAX_MCP_OUTPUT_TOKENS 调高。
    • 
              
  • 不用的服务器就删掉，工具名和服务器说明每次对话都会加载。
    • 
            

          


          
          

            

              06原理
              
登录与密钥

              
门禁卡要有身份。服务器验证身份有两种方式：在浏览器里登录，或者带着一个令牌。

            


            

              

                
方式怎么做例子

                
                  
浏览器登录（OAuth）添加后状态是 ! Needs authentication。在对话里输入 /mcp，选这个服务器，选 Authenticate，浏览器里批准。也可以在终端运行 claude mcp login 名字Sentry、Notion、Linear

                  
令牌添加时用 --header "Authorization: Bearer 你的令牌" 带上GitHub（个人访问令牌）

                
              

            

            
浏览器登录拿到的凭证由 Claude Code 保存、自动续期；删除服务器时会一起删掉。在 /mcp 里选 "Clear authentication" 可以撤销。


            
团队共享的配置里，密钥怎么放？

            
.mcp.json 要提交到 git，密钥绝对不能直接写进去。写成环境变量，每个人在自己电脑上设置：${VAR} 取变量的值，${VAR:-默认值} 在没设置时用默认值。

            

              

                

                  
.mcp.json（提交到 git）

                  

                  
你电脑上的环境变量

                  

                    
API_BASE_URL=https://staging.example.com

                    
API_KEY=sk-demo-123

                    
请求头改用 ${ANTHROPIC_API_KEY}

                  

                

                

                  
Claude Code 实际发出去的

                  

                  

                

              

            

          


          
          

            

              07原理
              
安全：门禁卡别乱发

              
连上一个服务器，就是让 Claude 能读它的内容、调它的操作。先确认你信任它。

            

            

              

                
风险怎么防

                
                  
提示词注入：服务器抓回来的网页、工单里可能藏着"给 AI 的指令"只连信任的服务器，优先从 Anthropic Directory 里找经过审核的；Claude 调用工具时留意它在做什么

                  
别人仓库里的 .mcp.json：clone 下来就可能启动程序交互模式下，第一次遇到项目共享的服务器会先问你，没信任文件夹时仓库也不能自己批准自己。选错了用 claude mcp reset-project-choices 重来

                  
claude -p 不会问-p 和 SDK 会不经询问直接加载 .mcp.json。跑陌生仓库时用 --strict-mcp-config（只用你用 --mcp-config 指定的服务器），或 --bare（第 4 课）

                  
权限给大了数据库用只读账号；GitHub 令牌只勾需要的仓库；不需要写操作的工具，可以用拒绝规则挡住

                  
密钥泄露密钥用环境变量或浏览器登录，别写进 .mcp.json、CLAUDE.md；Claude Code 也不会把自己的 ANTHROPIC_API_KEY 这类凭证展开给远程服务器

                
              

            

          


          
          

            

              08实战
              
6 个常用服务器，拿来就能加

              
都来自官方文档的示例。选一个，拷贝命令，按"怎么验证"试一遍。

            

            

              
服务器

              

                

                

              

            

            
更多服务器可以在 Anthropic Directory 里找。想自己写一个，官方插件 mcp-server-dev 能帮你搭好框架（插件在第 10 课）。

          


          
          

            

              09实战
              
终端演练：连上文档和 Sentry

              
一个不用登录的，一个要在浏览器里登录的。点"下一步"回放，放完可以自己输入。

            

            

              

                
my-app — zsh — 90×28

                

                

                  $
                  
                

              

              
            

            
终端画面为教学示意，查询结果、工具名、项目名是虚构的；命令与官方文档一致，面板样式为示意。

          


          
          

            

              10深入
              
进阶与避坑

              
连不上、没工具、改了不生效……按症状查。

            

            

              
/mcp 显示 No MCP servers configured
    
                
  1. 在别的项目里加的：local 范围只对加它的那个项目有效。在当前项目重新加，或者用 --scope user。
    2. 
                
  2. 手写配置写错了文件：自己手写时只有两个位置有效，~/.claude.json 和项目根目录的 .mcp.json；~/.claude/mcp.json、~/.claude/.mcp.json 这类路径不会被读取。
    3. 
                
  3. .mcp.json 格式有错：那一条会被跳过，claude mcp list 会指出哪个字段有问题。
    4. 
              

              
Failed to connect / Connection error
先看 claude mcp list 或 claude mcp get 名字 附带的原因。远程服务器用 curl -I 网址 看能不能访问（Windows PowerShell 里写 curl.exe）：返回 404、405 说明服务器在；401、403 说明要登录；没反应就是网址或网络的问题。本地服务器直接在终端运行那条启动命令，看报什么错。粘贴令牌时带进来的空格、换行也常导致失败，claude mcp list 会提示。

              
启动时连接超时
默认等 30 秒。npx 第一次运行要下载，可能不够。启动时加长：MCP_TIMEOUT=60000 claude（毫秒）。Windows PowerShell 里写成 $env:MCP_TIMEOUT = "60000"; claude。

              
连上了，但一个工具都没有
多半缺了必需的环境变量，比如 API key。用 --env KEY=value 重新加，或写进 .mcp.json 的 env 字段。服务器的说明文档会列出需要哪些。

              
改了 .mcp.json 没生效
Claude Code 只在对话开始时读 .mcp.json，改完要退出重开。之前拒绝过这个服务器的话，运行 claude mcp reset-project-choices。

              
想暂时不用某个服务器，又不想删
在 /mcp 里把它关掉。配置还在，只是这个项目里不连它；想用时再打开。

              
claude.ai 上加的连接器，Claude Code 里也能用吗
能。用 claude.ai 账号登录 Claude Code 时，你在 claude.ai 里添加的连接器会自动出现在 /mcp 里。用 API key 登录时不会加载。Gmail、Google 日历这类连接器只能在 claude.ai 那边登录。

              
反过来：把 Claude Code 当成 MCP 服务器
claude mcp serve 让 Claude Code 自己作为一个 stdio 服务器运行，别的 MCP 客户端（比如 Claude Desktop）就能调用它的读文件、改文件等工具。注意：这样用时，逐个确认工具调用要靠那个客户端自己做，Claude Code 不会替你弹确认。

              
老教程的写法和官方不一样
    
                
  1. 说"工具说明超过上下文的 10% 才自动开启工具搜索、Haiku 不支持"：现在工具搜索默认就开着，Haiku 4.5 及以后的模型都支持。
    2. 
                
  2. GitHub 的地址写成 https://api.github.com/mcp：官方文档用的是 https://api.githubcopilot.com/mcp/，配合个人访问令牌。
    3. 
                
  3. 示例配置里的 @modelcontextprotocol/server-github 在 npm 上已标记为不再支持；@modelcontextprotocol/server-database 在 npm 上查不到。连 GitHub、数据库请用第 8 节的写法。
    4. 
                
  4. 只写了 /mcp__服务器__提示词 这种命令格式：现在菜单里显示为 /服务器:提示词 (MCP)，两种都能用。
    5. 
              

            

          


          
          

            

              11检验
              
小测验

              
8 道题，每题选完会立刻看到解析。