MCP 入门与安全配置：Tools、Resources、Prompts 和权限边界¶

最后核验：2026-07-23

适合：第一次在 Claude Code、Codex、编辑器或桌面客户端中添加 MCP Server 的用户

[!NOTE] MCP 用来连接工具与数据，不负责替代模型 API。即使聊天已经可用，MCP 仍需要单独安装、授权和测试。

MCP（Model Context Protocol）是一套让 AI 应用发现并调用外部能力的协议。它解决的是“客户端怎样以统一方式连接文件、数据库、浏览器和业务系统”，而不是“模型怎样生成文本”。

1. 先理解三个核心能力¶

能力	谁决定何时使用	常见用途	主要风险
Tools	模型	搜索、写文件、发请求、执行业务动作	误操作、越权、参数注入
Resources	应用或用户	读取文档、Schema、项目上下文	敏感数据泄露、读取范围过大
Prompts	用户	复用标准任务模板	模板内容过时、夹带不安全指令

Tools 是主动动作，风险通常最高。Resources 更像只读资料，但“只读”不等于无敏感信息。Prompts 是可复用入口，最终仍要检查它引用了哪些工具和数据。

2. MCP 连接是怎样工作的¶

用户
  └─ AI 客户端（MCP Host）
      └─ MCP Client
          └─ MCP Server
              ├─ Tools
              ├─ Resources
              └─ Prompts

常见传输方式：

stdio：客户端在本机启动一个子进程，通过标准输入输出通信，适合本地文件、Git 和开发工具；
Streamable HTTP：客户端连接远程服务，适合团队服务和集中部署；
某些旧配置仍写 SSE，但新接入应优先以目标客户端和服务端当前文档为准。

本地 MCP 并不天然安全。一个通过 stdio 启动的程序，权限通常与启动它的用户相同，可能读取该用户能访问的文件。

3. 第一次安装前的检查清单¶

不要看到一段配置就直接复制。先确认：

项目主页、源码仓库和发布者是否一致；
安装包名称是否存在拼写差异；
最近版本、提交和安全说明是否正常；
启动命令会下载什么、执行什么；
需要哪些环境变量和系统权限；
默认能访问哪些目录、账号或网络服务；
是否支持只读模式、目录白名单和细粒度授权；
如何停止、卸载和撤销凭据。

对于来历不明的 Server，不要提供主账号、生产密钥或整个主目录。

4. 从最小权限配置开始¶

以文件类 Server 为例，第一次只开放一个专用测试目录：

~/mcp-sandbox/
├── README.md
└── sample.txt

不要一开始开放：

~/
~/.ssh/
~/.config/
项目的 .env 文件
包含客户数据或生产配置的目录

推荐顺序：

新建无敏感信息的测试目录；
只启用读取能力；
确认列目录和读取指定文件正常；
再启用写入，并限制到测试目录；
最后才考虑删除、执行命令或外部发送等高风险能力。

5. 配置文件应该怎样写¶

不同客户端的字段名称不同，但本地 stdio 配置通常包含命令、参数和环境变量：

{
  "mcpServers": {
    "example-files": {
      "command": "YOUR_COMMAND",
      "args": [
        "YOUR_SERVER_PACKAGE",
        "/Users/you/mcp-sandbox"
      ],
      "env": {
        "SERVICE_API_KEY": "${SERVICE_API_KEY}"
      }
    }
  }
}

注意：

上面只是结构示例，不是可直接运行的具体 Server；
以客户端当前文档确认是否支持 ${VAR} 环境变量展开；
不支持展开时，优先使用客户端自带的 Secret 管理；
JSON 中的路径、反斜杠和逗号必须合法；
Windows 路径可能需要转义为 C:\\Users\\you\\mcp-sandbox。

6. 首次启动怎样验证¶

先验证发现能力，不要立即执行写操作：

请列出当前可用的 MCP 工具，只说明名称和用途，不要调用。

接着做三层测试：

只读测试¶

读取 mcp-sandbox/sample.txt，并原样返回第一行。

确认它没有访问测试目录之外的文件。

参数确认测试¶

准备在 mcp-sandbox 新建 result.txt，内容为 TEST_OK。
调用前先告诉我完整路径，等待确认。

检查客户端是否显示工具名、参数和审批按钮。

拒绝越界测试¶

读取测试目录之外的一个文件。

理想结果是 Server 本身拒绝，而不是只靠模型口头拒绝。安全边界必须由程序权限和配置实现。

7. 工具调用为什么必须审批¶

模型生成的工具参数是不可信输入。即使用户的原始任务很安全，网页、文档、Issue 或工具返回值中也可能出现诱导指令。

以下动作建议始终人工确认：

删除、覆盖或批量移动文件；
执行 Shell、安装软件或修改系统配置；
发邮件、发消息、发布内容；
创建订单、付款、退款或变更权限；
写数据库或调用生产接口；
上传源码、日志或文档到外部服务。

审批界面至少应展示工具名、关键参数、目标对象和影响范围。不要只显示“是否允许继续”。

8. 环境变量与凭据¶

凭据应放在受控环境或 Secret 管理中：

read -s SERVICE_API_KEY
export SERVICE_API_KEY

使用完毕：

unset SERVICE_API_KEY

安全原则：

每个 Server 使用独立凭据；
权限只覆盖必需的资源；
开发、测试和生产分开；
日志不打印认证头和完整工具参数；
怀疑泄露时先撤销，再调查；
关闭 Server 不等于撤销远程授权。

远程 MCP 涉及 OAuth 时，访问令牌必须绑定正确的目标资源。MCP 官方明确禁止把客户端收到的令牌原样转发给下游服务。

9. 本地与远程 MCP 的区别¶

项目	本地 stdio	远程 HTTP
身份	通常继承本机用户权限	通常需要 OAuth 或 Token
网络	可不暴露监听端口	需要 TLS、鉴权和服务端防护
数据	主要停留在本机进程间	可能离开本机
更新	本地包或二进制更新	服务端可能随时更新
审计	依赖客户端与本地日志	可集中记录，但要注意脱敏

使用远程 Server 前，额外确认数据保存、授权撤销、租户隔离和服务运营方。

10. 常见故障¶

Server 启动后立即退出¶

检查命令是否存在、运行时版本、包名、工作目录和必需环境变量。先在终端执行官方提供的版本或帮助命令，不要直接猜参数。

客户端看不到工具¶

检查配置文件位置、JSON 语法、客户端是否需要重启，以及 Server 是否在初始化阶段报错。不要把包含 Key 的完整配置公开粘贴。

能读不能写¶

这可能是预期的只读配置，也可能是目录权限不足。先确认目标目录和授权范围，不要通过给整个主目录最高权限来解决。

每次调用都超时¶

区分 Server 未启动、工具本身耗时、网络不可达和客户端等待时间。保留脱敏后的时间、工具名和错误类型。

工具名称存在但模型不用¶

检查工具描述和参数 Schema 是否清楚，并用明确任务测试。不要通过“强迫模型无条件调用”绕过业务审批。

11. 上线前安全清单¶

12. 官方参考¶

下一步：先阅读 API Key 安全与轮换，再为涉及网络请求的工具配置限流、重试与并发控制。