如何在 Claude Code 里安全地用上 MCP

如何在 Claude Code 里安全地用上 MCP

2026年5月18日
123 次阅读
claude-code mcp mcp-server security oauth scope ai-agent developer-tools

嗨,我是 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(本地进程)。

Bash
# 远程 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:

相关文章