这篇讲什么
怎么把 MCP server 真正接到 Claude Code——不是抽象讲 MCP 是什么，是讲具体 claude mcp add 怎么用、三种 transport（stdio、sse、http）、scope 标志（user / project / local）、第一天该装哪几个 server。痛点：人们看完 MCP 规范一兴奋一口气装五个，权限弹窗每五秒一次，一气之下全关。这篇先装一个跑通，再讲怎么没摩擦地加更多。
核心概念：
- MCP（Model Context Protocol）：Anthropic 开源的协议，把工具、文件、数据暴露给 LLM。
claude mcp add：在 Claude Code 里注册 server 的 CLI 子命令。- Transport：
stdio（本地子进程，默认）、sse（HTTP server-sent events）、http（流式 HTTP）。 - Scope：
--scope user（你这台机）、--scope project（提交到仓库）、--scope local（当前目录、不共享）。 - 工具命名：注册的工具在 Claude Code 工具列表里叫
mcp__servername__toolname。
这篇适合谁看
走完Claude Code 新手指南、想把 agent 能干的事拓展到读改文件以外的人。尤其是你常常往 chat 里贴数据库查询结果、GitHub issue 内容、Slack 对话——这些正是 MCP 要消灭的拼贴动作。
什么时候适合用
一次会话里同样的”从别的工具复制粘贴”动作出现两次。数据库查询、GitHub PR 评论、Slack 搜索、仓库外文件访问——每一个都是 MCP server 候选。别预防性装；看到自己在重复手动动作了再装。
开始前准备
- Claude Code 装好能用（
claude --version）。不行的话看新手指南。 - PATH 上 Node 18+——多数参考 MCP server 走
npx。 - 项目作用域 server 要在 git repo 里、你愿意把
.mcp.json提交进去。 - 要接的东西的凭据（Postgres URL、GitHub token、Slack token）——拿到再开始装。
具体步骤
- 先看当前注册了哪些 server，知道起点：
claude mcp list- 加 filesystem 参考 server，scope 给 user（到处能用）。它暴露指定目录的读写工具：
claude mcp add filesystem --scope user \
-- npx -y @modelcontextprotocol/server-filesystem ~/work-- 分隔符必须有；后面是 Claude Code 启 stdio 时要 spawn 的命令。
- 重启 Claude Code 会话（或者 chat 里
/mcp重载）。确认 server 已列出：
claude mcp list
# 期望：filesystem (stdio) - user scope - ok- 试一个工具。在 Claude Code 问：
用 filesystem 工具列 ~/work 里的文件。第一次会请求权限——按工具一次性同意，不是按调用同意（只读工具有”始终允许”就勾上）。 - 加一个项目作用域 server，要队友共享。Postgres 常见——会在仓库根写一个
.mcp.json：
claude mcp add postgres --scope project \
--env DATABASE_URL=$DATABASE_URL \
-- npx -y @modelcontextprotocol/server-postgres- 验
claude mcp list里它 scope 是project，.mcp.json在仓库根。.mcp.json提交但带密钥的.env不提交。 - server 不正常时按这个顺序排查：
claude mcp list（注册了吗？）→claude mcp get servername（命令是啥？）→ 看 Claude Code 日志（macOS/Linux 通常~/.claude/logs/）。会话中途断了看Claude MCP server 断连。
一份”逼它说实话”的配置
第一天值得装的三个 MCP server，附理由。存成 .mcp.json 模板：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/work"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": { "DATABASE_URL": "postgres://localhost/myapp_dev" }
}
}
}为啥是这三个：filesystem 让 agent 摸到当前仓库外的文件（日志、scratch 目录）。GitHub 干掉”把 PR 评论粘到 chat”的循环。Postgres 把”我查一下 schema 长啥样”从粘贴变成查询。这三个用一周再考虑加第四个。
完成后检查
claude mcp list里每个 server 是ok，不是error/disconnected。- 工具在 chat 里以
mcp__servername__toolname出现——问”你有哪些工具”它能列出来。 - 权限弹窗合理：只读工具第一次后自动允许，写工具每次问。
.mcp.json提交了，密钥在环境变量、不内联。- agent 不用提醒就会用 MCP 工具。Postgres MCP 在线还老让你贴查询结果，就是 prompt 没点名工具——前几次显式说”用 postgres 工具查……”。
怎么复用这套流程
- 维护一份个人
~/.claude/mcp-user.json（或你 user scope 的文件名），放日常 user 级 server——filesystem、GitHub。 - 每个项目仓库提交最小
.mcp.json，带项目专属 server（项目数据库、项目用的 tracker 如果有 MCP）。 - 在 CLAUDE.md 里写 MCP 用法：“查数据库问题用 postgres MCP”——显式指引帮 Claude 选对工具。
- 新流行的 MCP server 先自己试一周，再共享给团队。烂 server 浪费大家时间。
建议的操作流程
发现手动粘贴动作 → 找对应 MCP server → claude mcp add 用对 scope → claude mcp list 验 → 头几次显式调用 → 习惯让 agent 自己用。
容易踩的坑
- 第一天装五个。权限疲劳直接把实验杀死。先装一个、证明有用、再加。
- 密钥直接写进
.mcp.json提交。环境变量在.env里，.mcp.json引用环境变量。 claude mcp add忘了--分隔符——后面的命令被当 flag 解析、注册悄悄失败。- 队友要用的 server 用了
--scope local。Local 不共享；仓库级 server 用project。 - 不挑 transport。stdio 最快最简，本地 server 默认它；只在 server 真是独立进程、你不 spawn 它时才上 sse/http。
- 断开的 server 放着不管。要么修要么
claude mcp remove。挂着的 server 让工具列表混乱、迷惑模型（MCP server 断连）。
FAQ
- 只写代码也需要 MCP 吗？: 不需要。MCP 是伸到代码库外的——数据库、API、外部文件。纯写代码用不上。
- 能自己写 MCP server 吗？: 能，协议开源、有 Python 和 TypeScript SDK。参考 server 是好模板。
- MCP 工具和 Claude Code 内置工具有啥区别？: 内置（read、write、bash 等）烤进 agent。MCP 工具可插拔——你的 server、你的 transport、你的鉴权。
- MCP server Cursor 也能用吗？: Cursor 也支持 MCP，有自己的 UI。协议共享、注册流程不同。
相关阅读
标签: #AI 编程 #教程 #Claude Code