Claude Code MCP 服务器

安全接入 Claude Code MCP server：选择 local 或 remote transport，配置 MCP 工具权限，排查连接问题，并管理 Tool Search。

Model Context Protocol（MCP）让 Claude Code 连接外部工具和上下文来源。只有当 Claude 需要仓库之外的能力时才值得接入，比如 GitHub issue、浏览器自动化、当前框架文档、内部 API 或受控数据库查询。

快速结论

只有当 MCP server 提供了内置文件、搜索、编辑和 shell 工具没有的明确能力时，才应该添加它。先从只读工作流开始，显式授权 MCP 工具，并记录每个 server 为什么存在。

适合使用 MCP	不建议使用 MCP
读取 GitHub issues、PR 和仓库元数据	替代仓库内普通文件搜索
对本地预览做浏览器检查	给每个会话开放宽泛浏览器自动化
获取当前框架文档或 API reference	抓取可以直接链接的静态文档
权限边界清晰的内部工具	负责人或 token 范围不清楚的工具
经常变化的团队共享上下文	一次性备注，应该放在 `CLAUDE.md` 或当前会话

MCP 在 Claude Code 里扮演什么角色

MCP server 会向 Claude Code 暴露 tools、prompts 或 resources。Claude 可以在任务中发现这些能力，并请求调用。

关键安全点是：MCP 工具仍然是工具。它们需要像文件编辑、shell 命令、WebFetch 和 subagents 一样配置权限。

层级	控制什么
Server 配置	Claude Code 可以连接哪些 MCP server。
工具权限	Claude Code 可以调用哪些 MCP tools。
凭证范围	底层 API token 或 OAuth grant 能访问什么。
提示词	你是否明确指定 server 和工作流。

选择合适的 Server 类型

Server 类型	适合场景	需要核对什么
Local stdio	本地工具、脚本、文件 helper、测试服务	命令路径、包管理器、环境变量、工作目录。
Remote HTTP	托管工具、SaaS 集成、组织服务	URL、OAuth、headers、组织权限、可用性。
Remote SSE	还没有迁移到 HTTP 的旧 server	是否已有 HTTP endpoint；能用 HTTP 时不优先选 SSE。
Project-scoped config	某个仓库的团队共享配置	`.mcp.json` 是否应该提交，是否需要每个开发者批准。
Managed MCP	组织统一管控的 MCP server	管理员 allowlist、denylist、managed settings 和策略来源。

选择合适的安装 Scope

transport 决定 Claude Code 如何连接 server，scope 决定配置存在哪里、谁会拿到这份配置。

Scope	加载范围	是否团队共享	存储位置	适合场景
`local`	当前项目	否	`~/.claude.json`	个人实验、私有凭证、一次性 server。
`project`	当前项目	是	项目根目录 `.mcp.json`	团队统一使用、需要代码审查的 server。
`user`	你的所有项目	否	`~/.claude.json`	多个仓库都会用到的个人工具。

添加 server 时可以用 --scope 明确指定：

claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

如果同名 server 出现在多个位置，Claude Code 会按优先级使用配置：local、project、user、plugin-provided servers、Claude.ai connectors。

团队共享的 .mcp.json 不要写入明文密钥，应该使用 ${API_KEY} 或 ${API_BASE_URL:-https://api.example.com} 这类环境变量展开。Claude Code 在使用 project-scoped .mcp.json server 前会要求批准，所以这份文件要像代码一样审查。

中文实战场景怎么选

很多团队接入 MCP 不是因为“功能多”，而是因为 Claude Code 需要稳定读取外部事实。先用下面这张表判断是否值得接：

场景	建议接入方式	推荐 scope	权限边界
根据 GitHub Issue 改代码	GitHub MCP 或 `gh` CLI	`project`	先只读 issue / PR，写操作单独批准。
查询当前框架文档	文档类 MCP 或直接链接官方文档	`user`	优先只读，避免把整个文档库塞进上下文。
读取内部接口或监控数据	内部 HTTP MCP	`project`	使用只读 token，限制 API 路径。
查询生产数据库	不建议直接连生产库	谨慎使用	用只读副本、白名单 SQL 或中间 API。
临时验证一个新 server	本地配置	`local`	先不提交 `.mcp.json`，确认价值后再共享。

如果一个 MCP server 既能读又能写，先按只读工作流上线。等团队确认它稳定、可审计、不会泄露 token，再逐步开放写操作。

最小接入流程

先确定一个工作流，例如“读取 GitHub Issue”或“查询当前库文档”。
按官方 server 文档添加一个 MCP server。
在 Claude Code 中运行 /mcp，确认 server 已连接。
只授权这个工作流需要的 MCP tools。
先在小仓库测试，再用于生产仓库。
记录 server 用途、负责人、凭证来源和权限边界。

权限写法

MCP tools 通常遵循这样的命名模式：

mcp__<server-name>__<tool-name>

例如 GitHub server 可能暴露：

mcp__github__list_issues
mcp__github__get_pull_request

尽量授权具体工具。只有当整个 server 都适合当前工作流时，才使用通配符：

{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",
      "mcp__github__get_pull_request",
      "mcp__context7__*"
    ]
  }
}

不要用 acceptEdits 来替代 MCP 授权。官方文档区分了文件编辑审批和 MCP 工具审批。需要 MCP 访问时，应直接配置 MCP 工具权限。

Tool Search 和上下文成本

有些 MCP server 会暴露很多工具。把所有工具都加载进上下文，会让 Claude Code 变慢、变散。Claude Code 可以延迟加载 MCP tools，并在需要时通过 Tool Search 发现。

情况	建议
小 server，工具很少且经常使用	通常可以直接加载。
大 server，很多工具很少使用	让 Tool Search 按需发现。
每次会话都需要的核心内部工具	只有在上下文成本值得时，才考虑 always-loaded。
工具输出很大	要求过滤查询、分页或摘要，不要一次倒出全部内容。

提示词最好明确 server 和动作：

Use the GitHub MCP server to read issue 42 and summarize reproduction steps. Do not edit files.

不要只写：

Look at GitHub.

调试检查表

症状	优先检查
server 没出现	运行 `/mcp`，检查配置位置、server 名称和 JSON 语法。
server 出现但 disconnected	在 Claude Code 外部运行命令或访问远程 URL。
tool 可见但被拒绝	检查 `permissions.allow`、deny rules 和组织策略。
OAuth 失败	重新完成 provider 授权，并确认账号或组织权限。
tool 输出太大	缩小查询、分页，或要求摘要。
自己可用，同事不可用	检查环境变量、`.mcp.json` 和项目级审批。

团队安全清单

不要把 token 写进 CLAUDE.md、提示词、截图或提交的配置。
新 MCP server 优先使用只读 token。
先为一个工作流开放一个 server，再逐步扩展。
对可写工具避免宽泛通配符。
像审查代码一样审查共享 .mcp.json。
在项目文档里记录 server 用途和负责人。
不再使用的 MCP server 要禁用或移除。

官方来源

下一步：自定义命令 - 工具面稳定后，再沉淀可复用命令。