嗨,我是 Lena。MCP 已经不是新概念了,但要在 Claude Code 里把一个 server 真正接好,又不踩坑,里面的弯弯绕绕比大多数人预期的要多。
过去几个月我一直在用 Claude Code 加各种 MCP server 做日常开发——从 GitHub 到 Sentry,再到自己写的内部数据库查询工具,都跑过。说真的,接入这件事本身并不难——难的是搞清楚什么能信、OAuth 挂了去哪儿排查、scope 到底是怎么工作的。 这篇文章是我踩过的坑和翻官方文档翻出来的细节,写给那些已经在用 Claude Code、准备接 MCP server 的开发者。
接 MCP server 之前要先看的几件事
Claude Code 版本和平台支持
先看版本。OAuth 相关的行为是在 v2.1.64 之后才稳定下来的——那一版才把 authServerMetadataUrl 的支持加进去。更老的版本在跟 remote server 做认证时会直接抛错。Windows 上还有个已知的怪毛病:claude mcp add-json 在加 HTTP server 的时候偶尔会返回 "Invalid input"。官方 MCP 文档的建议是,遇到这种情况回退用 claude mcp add --transport http 那种写法。
MCP 在 Claude Code 里到底能干啥
MCP 让 Claude Code 从一个只能读写本地文件、跑 bash 的工具,升级成一个能直接跟外部系统打交道的 agent——拉 Jira ticket、开 GitHub PR、去 Sentry 查生产报错,都是它的活儿。但有个细节经常被忽略:MCP server 之间是完全隔离的。 没有 passthrough,每一层都是独立的。
Tools、resources、prompts
按 MCP 规范的说法,一个 server 可以暴露三类能力:tools(可执行动作)、resources(可读数据源)、prompts(预设交互模板)。/mcp 面板会显示每个已连接 server 的工具数量,并且会把那些声明了 tools capability、但实际没暴露任何工具的 server 标出来。
一步步把第一个 MCP server 加进来
用 CLI 加 server
Claude Code 支持三种 transport 类型:HTTP(推荐用于远程服务)、SSE(已废弃,能绕就绕)、stdio(本地进程)。
# 远程 HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
# 本地 stdio server
claude mcp add --transport stdio --env API_KEY=your_key myserver \
-- npx -y my-mcp-server
这里有个最容易绊倒人的细节:所有 option 都必须写在 server name 前面。 双横线 -- 是用来把 Claude 自己的 flag 跟传给 MCP server 进程的参数分开的。顺序写错,命令会静默失败。这个坑我自己踩过不止一次。
通过 .mcp.json 给团队共用
用 --scope project 可以把配置写进一个 .mcp.json 文件,提交到版本控制里跟队友共享。永远不要把真实 token 直接写进这个文件——用环境变量引用代替。同名 server 在 local scope 会覆盖 project scope,这样能保住凭证不外泄。
验证 server 是否真的连上了
在 Claude Code 里跑 /mcp 看状态和工具数量。从 v2.1.121 开始,HTTP/SSE server 在初次连接时会自动重试最多三次,但认证错误和 404 不在重试范围——这类错只能靠改配置解决。
第一次调用时审批
新 server 第一次被调用的时候,Claude Code 会弹权限确认。这是设计上的信任校验。Claude Code 安全文档写得很清楚:新接入的 MCP server 必须用户确认。你可以单次允许,也可以选 "Always allow" 把它加进白名单。
认证和 OAuth 流程
需要 OAuth token 的 server
大多数 remote server——GitHub、Slack、Notion 这些——都要 OAuth。Claude Code 内置 OAuth 2.1 支持,整个流程基本是自动的:server 返回 401,Claude Code 先按 RFC 9728 Protected Resource Metadata 去发现 OAuth 元数据,找不到就回退到 RFC 8414;如果支持 Dynamic Client Registration,就自动注册成一个 client,浏览器弹出来让用户授权,然后拿回 token。
如果 server 不支持 Dynamic Client Registration,你会看到 "Incompatible auth server" 这条错。这种情况下要去 server 的开发者后台手动注册一个 OAuth app,拿到 client ID 和 secret,然后用 --client-id 和 --client-secret 把 server 加进去。有些 server 还要求固定的 callback 端口——用 --callback-port 对上你注册的 redirect URI。
凭证存哪儿、怎么轮换
Token 存在系统的安全凭证库里——macOS 上是 Keychain,其他平台是加密的凭证文件。它从来不会以明文形式落到 config 文件里。 要轮换的话,打开 /mcp 重新对相关 server 做一次认证就行。SSH 环境里没有浏览器的时候,Claude Code 会显示一个 "Paste code here" 的提示,让你在另一台机器上完成授权之后,把结果粘回来。
别让 token 在共享配置里泄漏
这点我得说得直接一点——我见过不止一个团队把硬编码 token 的配置推到公开仓库上去。凭证永远要用 ${ENV_VAR} 引用。 企业环境里管理员可以下发一份 managed-mcp.json,用 allowlist 和 denylist 控制哪些 server 能用。
信任一个 server 之前要看的安全边界
MCP server 在你机器上能读到什么
stdio 类型的 server 跑在你当前用户的权限下,这一点很多开发者没认真想过。理论上它能读你的 .env、SSH key、AWS 凭证——所有你这个账户能访问到的东西。Claude Code 自己也有一些防护——写操作被限制在工作目录里,网络请求要审批。Anthropic 工程团队的安全博客详细写了 sandboxing 机制,文件系统隔离和网络隔离是协同工作的。他们内部数据显示,sandboxing 把权限提示减少了 84%,这对日常工作流来说差别很大。
它能执行什么、能写入什么
MCP tool 可以包含任意执行能力。一个挂在生产数据库上的 "run SQL" 工具,是真的会对生产数据执行查询的。这不是假设——我见过那种 setup:一个配置不当的 tool 拿到了对线上客户数据库的写权限。接任何 server 之前,你需要清楚地知道它暴露了哪些 tool、每个 tool 实际能做什么。 拿不准的就留在 ask 模式里,别图省事自动批准。
审批前要审的几样东西
在信任一个 server 之前,我一般会做三件事:翻源码(去 GitHub 看主入口文件,确认它实际在干啥)、评估维护状态(一个三天前刚发布的包,和一个已经维护了两年的包——风险完全是两个量级)、看权限声明(按 MCP 授权规范,server 应该声明自己要的 scope——任何超出合理边界的都得警惕)。
常见问题和修法
server 加完之后没出现
最常见的原因:scope 写错了。 在项目 A 目录下用 --scope local 加的 server,切到项目 B 就看不见。用 claude mcp list 确认 scope,需要全局可用就换 --scope user。还有一个要注意的:workspace 是保留名,用它做 server name 会被跳过并给一个 warning。
tool 调用静默失败
先看输出是不是超了默认 10,000 token 的上限。Claude Code 在超限时会出一个 warning,但很容易被漏掉。设 MAX_MCP_OUTPUT_TOKENS=50000 可以把上限拉高。另一种可能是连接断了——HTTP/SSE server 会按指数退避自动重连(最多 5 次),但 stdio server 不会自动重连。
local 和 project 配置冲突
同名 server 同时存在于 local 和 project scope 时,local 覆盖 project。 这是设计如此,但你要是不知道这点,就会奇怪 .mcp.json 里的改动怎么不生效。用 claude mcp get <name> 看当前实际生效的是哪个配置。
每次新会话都要重新批准权限
如果你当初没选 "Always allow",审批就不会保留。用 /permissions 来管你的永久白名单。Claude Code GitHub 仓库里有 PreToolUse hooks 的文档,可以做更细粒度的自动审批逻辑。
连上之后还不够的地方
MCP 给的是工具,但保不住那些已经走通的方案
这是我日常用下来感受最深的一个局限。MCP 解决的是 "连接" 问题——它解决不了 "记忆" 问题。你可能今天花 20 分钟把一套数据库查询加报表生成的工作流调通,明天打开新会话,所有这些 context 全没了。你得重新解释要查哪些表、输出什么格式、要处理哪些 edge case。MCP 协议里没有任何会话持久化机制,每一次连接都是无状态的。这不是 bug——这是一条设计边界。
为什么团队还在跨会话、跨机器重复修同一件事
开发者 A 摸清了某个 server 的正确用法,磕过某个 edge case,把流程跑顺了。但这份辛苦换来的知识没地方落。一周后开发者 B 加入项目,碰到的是一模一样的问题,花的是一模一样的调试时间。.mcp.json 共享的是配置——不共享 "怎么用" 和 "上次坏了我们是怎么修的"。CLAUDE.md 文件能起一部分缓解作用,但它是静态的、需要手动维护。MCP 把自己分内的事做得很好,但只要工作流稍微复杂一点,你迟早会撞上 context 丢失和经验重复的问题。
FAQ
MCP 和 plugin 是一回事吗?
不完全是。MCP 是一个开放协议标准,定义的是 AI 应用怎么跟外部工具通信。Plugin 是 Claude Code 里一个更上层的概念,可以包含 MCP server 配置以及其他类型的扩展。Anthropic 的官方发布页有 MCP 最早的发布稿。
用 MCP server 需要 API key 吗?
看 server。本地 stdio server 一般不需要任何认证。Remote HTTP server 通常要凭证——要么是 Bearer token(通过 --header 传),要么是 OAuth(自动处理)。
队友能看到我的 MCP server 吗?
只有 --scope project 的配置会写进 .mcp.json 并被团队看到。local(默认)和 user scope 都是私有的。
local、project、user scope 有啥区别?
local(默认):只对你、只在当前项目目录可见。project:写进项目根目录的 .mcp.json,通过版本控制跟整个团队共享。user:对你、在你这台机器上的所有项目都可见。注意旧版里 local 叫 "project"、user 叫 "global"——名字后来改过,别被老博客或老指南里的旧叫法搞糊涂了。
为啥 Claude Code 老是反复让我批准同一个 tool?
新会话默认不继承临时批准。用 "Always allow" 或 /permissions 把 tool 加进永久白名单。企业环境里,managed-settings.json 的 deny 规则会覆盖你本地的 allow 规则,这也可能导致反复被拒。
Previous Posts:
- 想要对 MCP 本身有一个更清楚的心智模型,理解它为什么正在变成 AI 工具连接的标准层?读:What Is MCP AI Tool Connection Standard
- 如果你准备在 Claude Code 里把 MCP 真正用起来,这篇关于实际配置和扩展的指南跟本文工作流是天然配套:Claude Code MCP Setup Extensions Guide
- 想知道哪些 MCP server 在日常开发里是真有用、而不是只能演示?这篇实战盘点值得加书签:Best MCP Servers Real World Usefulness
- MCP 管的是连接,Claude Skills 管的是可复用的行为层——这篇开发者参考把 stack 的另一面讲得更细:Claude Code Skills Developer Reference
- 文中提到的"连接 vs 记忆"局限,直接延伸到本地持久化和工作流连续性问题,这里有更深入的讨论:Claude Code Local Skills Memory Persistence




