Claude Code MCP 怎么配置？本地服务器、远程工具与安全检查

Claude Code 的 MCP（Model Context Protocol）用于把外部工具、资源或数据连接到开发工作流。配置 MCP 不只是复制一条安装命令，还要决定服务器范围、传输方式、凭据保存、审批机制和可撤销性。本文依据 Claude Code 当前官方文档核验，日期为 2026 年 10 月 12 日。

已有 Claude MCP 入门教程 解释了协议概念；本文聚焦 Claude Code 中更容易出错的配置范围和安全检查。

MCP 先解决什么问题

MCP Server 可以向 Claude Code 暴露工具或资源，例如查询测试数据库、读取项目文档、连接代码托管服务或调用内部系统。它不会因为“接入成功”就自动拥有整台电脑的所有权限；实际能力取决于服务器实现、运行账号、Claude Code 权限和配置范围。

不要把 MCP、Skills 和 Plugin 混成一件事：MCP 主要解决外部连接，Skills 主要复用任务流程，Plugin 可能把多种资源组织起来。需要选择时可参考 三种扩展机制对比。

三种安装范围

范围	生效范围	配置位置	适合场景
local	当前项目、当前用户	~/.claude.json 中的项目条目	个人实验、带私密凭据的开发服务器
project	当前项目、团队成员	项目根目录 .mcp.json	团队共享的无密钥配置
user	当前用户的多个项目	~/.claude.json	个人常用工具和跨项目服务

当前官方文档说明，local 是默认范围；它和 .claude/settings.local.json 不是同一个概念。范围优先级通常是 local、project、user，再到插件服务器和 claude.ai connectors；同名或同端点可能产生覆盖，不能只看一份配置文件判断最终加载了什么。

用 CLI 添加服务器的基本形式

远程 HTTP 服务器的示例形式：

claude mcp add --transport http shared-server --scope project https://example.com/mcp

本地 stdio 服务器通常需要命令和参数：

claude mcp add --transport stdio local-tools -- npx -y example-mcp-server

示例中的域名和包名只是格式演示，不要未经核验就执行。添加后使用 claude mcp list 或会话内的 /mcp 查看状态；需要删除时使用当前版本支持的 claude mcp remove <name>，并保留原配置备份。

.mcp.json 如何写得可共享

项目范围的配置一般类似：

{
  "mcpServers": {
    "docs-readonly": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://example.com/mcp}",
      "headers": {
        "Authorization": "Bearer ${DOCS_MCP_TOKEN}"
      }
    }
  }
}

把 URL 和令牌写成环境变量占位符，提交前确认仓库中没有真实值。环境变量没有设置时，服务器可能连接失败；这比把真实凭据硬编码进 Git 更容易修复。

如果配置来自不可信仓库，不要在第一次打开项目时自动批准所有 project-scoped Server。先查看 .mcp.json 的命令、参数、URL、环境变量和工具清单。

stdio、HTTP、SSE 怎么选

• stdio：服务器作为本地进程启动，适合本机工具；要检查启动命令、包来源和子进程权限。
• HTTP：连接远程服务，适合托管工具；要检查 TLS、认证、域名、数据发送范围和服务条款。
• SSE / WebSocket：具体支持与服务器实现和版本有关；要确认连接保持、超时、重连和事件数据。

传输方式不是安全等级。一个本地 stdio 进程也可能上传数据，一个远程 HTTPS 服务也可能拥有过大的账户权限。

OAuth 与 API Key 的保存

部分远程 MCP Server 支持 OAuth 2.0。授权前确认客户端、回调地址、申请的 scope 和令牌保存位置。不要把 OAuth token、API Key 或个人访问令牌写进 .mcp.json、Skill、提示词、截图或日志。

使用数据库类服务器时，优先创建只读数据库用户；使用 GitHub 类连接器时，只授权必要仓库和操作。凭据应可单独撤销，开发、测试、生产环境不要共用。

第一次连接的安全流程

1. 画出数据流

记录输入文件、MCP Server、上游系统、返回内容和可能的写入动作。先回答“哪些数据会离开本机或项目”。

2. 只启用只读工具

第一次只允许列目录、读公开样例或查询测试数据库。不要同时开启删除、发布、发信、支付、数据库写入和网络抓取。

3. 看清审批和信任提示

交互式会话可能对 project-scoped Server 或敏感工具请求批准；非交互模式、云会话和某些 bypass 设置的审批行为不同。不能因为本地测试时看到了提示，就假设 CI 或后台任务也会弹窗。

4. 验证返回结果

要求工具返回来源、时间、查询条件和字段。连接成功不等于数据正确，Claude 对工具结果的总结也不能替代原系统核对。

5. 记录和撤销

保存服务器名称、版本、范围、权限、批准人和撤销命令。出现异常时先断开服务器、撤销凭据，再检查日志和数据访问。

Prompt Injection 和不可信内容

网页、Issue、README、数据库记录和第三方文档都可能包含试图改变代理行为的恶意指令。Claude Code 官方安全文档强调权限、工作区信任、网络审批和命令注入防护，但没有任何防护能替代人工审查。

处理外部内容时：

• 不要把不可信文本直接管道传给 Shell 或自动执行器。
• 查看 Claude Code 提出的完整命令和参数。
• 对关键文件检查 diff，对外发动作保留人工确认。
• 对 Windows 路径、网络盘和 WebDAV 目录格外谨慎。
• 高风险环境考虑沙箱、开发容器或隔离虚拟机。

与 ZeoAPI 等 API 网关的边界

MCP 是工具连接协议，ZeoAPI 是独立第三方多模型 API 网关，两者不是同一个层次。如果你通过 ZeoAPI 把模型接入 Claude Code，仍要单独核对 API 令牌、ANTHROPIC_BASE_URL、模型映射、日志、数据处理和费用；不要因为 API 请求成功就把 MCP Server 当成可信组件。

排查 MCP 连接失败

1. 运行 claude mcp list，确认服务器是否存在以及属于哪个范围。
2. 检查 JSON 格式、环境变量和 URL，不要先扩大权限。
3. 对 stdio 查看启动命令和本地运行时；对 HTTP 检查状态码、TLS 和 OAuth。
4. 在会话中使用 /mcp 查看 connected、failed 或需要授权的状态。
5. 用公开测试数据重试，并把服务器输出与模型解释分开记录。

如果仍无法确认数据流向，先移除服务器，回到 Claude Code 安全清单 重新审查。

官方参考

• Claude Code MCP 官方文档
• Claude Code 安全说明
• Claude Code 权限说明