Claude Code MCP 权限模型与最佳实践：GitHub / CodeGraph / API 最小权限隔离指南

前置：MCP 三连通总览（先连通再谈权限）；安装见 安装教程。要快步骤见下方「适用问题」跳转；要完整规范读全文——本文是 MCP 权限权威规范（v1.0），不是连通教程。

阅读路径（约 15 分钟 · 规范全文）：适用问题 → 一句话总结 → 系统模型 → 信任边界与数据流 → 策略矩阵与控制平面 → 配置片段 → 攻击链。可引用为团队标准操作程序（SOP）或安全评审附件。

定位：权威规范（解决问题 + 可审计）

上文「适用问题」把搜索意图绑回具体章节；本节起进入安全架构规范正文。连通验收看工具是否注册（mcp__github__*）；权限验收看调用时的触达面：路径、API、GitHub 资源与密钥权限范围。

Claude Code、CodeGraph、GitHub Runner 常同机部署时，MCP token 与 Runner 密钥必须分账，禁止共用 GitHub App 私钥或把生产 DATABASE_URL 放进 Agent 工作区（远程 Mac 场景见 Cloud Mac vs 本地 Mac）。

第一层 · 系统模型（读矩阵前先建立锚点）

三连通 MCP 按职责分成三类——每一类对应不同的读写风险边界，而不是三种「连上就行」的插件（架构详见 MCP 总览）：

Claude Code 会话
    │
    ├─ GitHub MCP     →  意图 intent   （需求从哪来：issue / PR / 评论）
    ├─ CodeGraph MCP  →  上下文 context（改哪里：impact / 符号 / 依赖）
    └─ API MCP        →  真相 truth    （对不对：预发数据 / 契约）

风险轴：意图层误写会触发协作面；上下文层误写会污染索引或源码；真相层误写会把预发/生产数据搞混。

部署侧对照：CodeGraph 五分钟 负责「图谱可用」；本篇负责「图谱与 API 在 Agent 面前默认只读」。系列第一篇为架构 / 三连通，第三篇计划为 MCP 威胁模型（STRIDE · 攻击面 · 凭据流）。

信任边界

架构师评审时可引用下图：Agent 会话位于内圈，MCP 是触达外系统的唯一网关；任何跨越生产、可写文件系统或 CI 凭据的调用，都视为边界违规。

┌─────────────────────────────────────────────────────────┐
│  信任区 A · Claude Code 会话（用户 / Agent）              │
│                                                         │
│   ┌──────────────── MCP 层 ───────────────────┐         │
│   │  GitHub MCP（意图）  ──► 外部协作系统       │         │
│   │  CodeGraph MCP（上下文）──► 本地索引/图谱    │         │
│   │  API MCP（真相）     ──► 预发数据库          │         │
│   └───────────────────────────────────────────┘         │
└─────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
   [ GitHub API ]      [ .codegraph/ ]      [ 预发 API ]
   外部 · 协作面         本地 · 只读默认        非生产环境

信任边界（禁止默认跨越）:
  ✗ 生产数据库 / 生产 API 地址
  ✗ 可写文件系统（整仓 / monorepo 根）
  ✗ CI / Runner 凭据（GITHUB_TOKEN · App 私钥）
  ✗ .env.production · 相邻项目密钥

与策略矩阵的对应关系：矩阵中「生产环境 = 禁止」「CI/Runner = 禁止挂 MCP」两行，即上述边界的可执行化表述。

数据流

权限问题本质是数据在 Agent → MCP → 外部系统之间如何流动，并在哪一步产生副作用。边界图回答「能不能跨」；数据流回答「跨了之后发生什么」。

用户提示词
   ↓
Claude Code（Agent 状态 · 对话上下文）
   ↓
MCP 工具调用（GitHub / CodeGraph / API）
   ↓
外部系统响应（issue 正文 · 图谱 JSON · 预发行集）
   ↓
Agent 解读（写入计划 · PR 描述 · 下一工具参数）
   ↓
副作用（PR 评论 · 数据库 INSERT · .codegraph/ 改写 · CI 触发）

控制点（本篇策略矩阵对应行）:
  · MCP 调用前 → MCP 服务只读 / 权限范围最小化
  · 响应回注前 → PII 脱敏 · 禁止生产字段
  · 产生副作用前 → 写服务未启用则工具链应失败

攻击链复盘（下文 § 误配置攻击链）即沿此数据流逐步展示：哪一跳的响应被 Agent 误用，最终触发 PR / 库表 / 索引副作用。

常见权限事故路径（Agent 如何误操作）

下列路径在「配置看似合理」时仍会发生——适合作为代码评审 / 安全评审的检查项：

• GitHub MCP 写评论 / 标签 → 触发依赖评论的 CI 机器人或自动合并规则，在未人工确认下推进流水线。
• CodeGraph 或文件系统 MCP 对仓库可写 → Agent 修 issue 时改写 .codegraph/ 或相邻子项目配置，索引被污染，codegraph_impact 结果不可信。
• API MCP 对预发环境可写 → 测试数据写入与生产 mock 字段混用，后续 Agent 把错误 schema 当成「真相」写进 PR 描述。
• 文件系统 MCP 读取工作区根目录 → 扫到 .env.production 或相邻 monorepo 的密钥，内容进入对话上下文或 issue 评论。

第二层 · 默认策略原则（矩阵前的结论层）

矩阵解决「每一行怎么配」；本节只保留三条可写入团队规范的结论（不在此重复三类 MCP 的定义）：

1. Claude 会话默认只挂只读 MCP 服务（*-ro 命名）；任何写操作需要短命 token + 显式启用第二个 MCP 服务。
2. CI / Runner 不通过 MCP 暴露；夜间重建索引、集成测试写库由工作流完成，不由对话触发。
3. 生产环境对 Agent 不可见：无生产 URL、无 DATABASE_URL、无 merge/push 级 PAT 常驻 ~/.claude.json。

策略矩阵（建议默认行）

下表按「机器可执行 / 可评审」设计：除资源与默认策略外，标明Claude 自动调用、CI 触发、生产环境触达 三列，便于对照策略即代码或上手检查清单。有写需求须在 PR 中注明原因与过期时间。

控制平面（策略由谁强制执行）

上文策略矩阵回答「应该怎么做」；本节回答「谁在什么环节强制执行」——把最佳实践升级为可落地的强制执行分层。

策略强制执行点:

  1. MCP 服务配置（~/.claude.json · 静态权限范围 · 只读服务默认启用）
  2. 操作系统 / 文件系统（仓库与 .codegraph/ 只读挂载 · 工作目录隔离）
  3. GitHub App / PAT 控制台（细粒度 · 单仓库 · 过期写 token）
  4. CI 流水线（生产 URL 门禁 · 密钥扫描 · 禁止 PAT 进仓库）
  5. Runner 保险库（CI 凭据与 MCP 环境变量分账 · 不挂进 mcpServers）

对应策略矩阵列：
  · Claude 会话  → ①②
  · CI / Runner  → ④⑤
  · 生产环境     → ③④（拒绝生产端点 / 全写 PAT 常驻）

完整可打印清单将单页化（计划 MCP 最佳实践检查清单，见下文 § 延伸阅读）；连通类报错见计划中的 MCP 常见故障 页，与本篇权限规范分工。

GitHub MCP · PAT 与权限范围

目标：让 Claude Code 能读 issue、在评论里引用，但不要把「合并 PR」能力长期交给对话里的 Agent。

推荐分档

• 日常开发（只读为主）：repo（private 仓库读）、read:org（若需 org 下多 repo）；issue 流加 issues。
• 自动化写操作（短命）：单独细粒度 PAT，仅指定仓库，权限勾选 Contents/Issues 的写权限，过期时间 7–30 天，用完即从 mcpServers 移除。

Token 存放：环境变量（如 GITHUB_MCP_TOKEN）优先，不要写进仓库；Cloud Mac 上用实例级 secret，本地 Mac 用 Keychain / 1Password 注入。

# 示例：仅示意权限范围思路，以 GitHub 当前 PAT 界面为准
# 细粒度 · 单仓库 · Contents 只读 + Issues 读写

CodeGraph · 只读索引实践

CodeGraph 的价值在查询图谱，不是让 MCP 改索引文件。建议：

1. 在仓库根 codegraph init 后，将 .codegraph/ 视为构建产物（可 gitignore 或单独备份）。
2. MCP 服务进程对仓库源码只读；重建索引用人工或 CI 脚本，不用对话触发。
3. 若 Agent 报 codegraph_impact 为空，先查索引与工作目录（见总览页问题表），不要先给写权限。

大仓场景可结合 CodeGraph 与 AI Coding Agent；权限策略仍适用：图谱只读。

API MCP · 预发环境只读

API MCP 用于对齐「真实数据长什么样」。最小权限做法：

• 只配置预发环境基础 URL；生产 URL 不出现在 mcpServers 环境块里。
• 数据库账号仅 SELECT；需要写入时用另一个 MCP 服务名（如 api-staging-rw），默认不在 Claude 配置里启用。
• 响应里若含 PII，在 MCP 层做字段脱敏或禁止把原始 JSON 贴进 issue 评论。

~/.claude.json 最小示例（结构示意）

不同版本字段名可能略有差异；重点是分 MCP 服务、分环境变量、默认可用集最小化。

{
  "mcpServers": {
    "github-readonly": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_MCP_TOKEN_READONLY}"
      }
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"],
      "env": {
        "CODEGRAPH_READ_ONLY": "1"
      }
    }
  }
}

说明：CODEGRAPH_READ_ONLY 为示意环境变量——以你使用的 CodeGraph / MCP 实现文档为准；若无此开关，用操作系统权限（只读挂载）达到同样效果。

上线前检查清单（摘要 · 完整版将单页化）

• □ GitHub PAT 是否为最小权限范围，且未提交到 git？
• □ 是否存在写生产环境的 API MCP 服务？若有，是否默认禁用？
• □ CodeGraph 是否仅开放 impact/query 类工具？
• □ Cloud Mac 上 Claude 会话工作目录是否指向单一仓库，避免读到相邻项目的 .env？
• □ Runner 注册 token 是否与 MCP token 分离？
• □ 团队成员是否知道：收紧权限后应改哪篇文档？（本篇 + 总览）

误配置攻击链复盘

以下基于真实常见组合：配置表面「为了效率」合理，但 Agent 链式调用后权限越界。

1. 初始配置（看似合理）

• 单一 mcpServers 配置档：GitHub MCP（repo 写）+ 文件系统 + CodeGraph 同进程。
• CodeGraph 对 monorepo 根目录可写；API MCP 指向预发，但账号具备 INSERT。
• Claude 工作区目录 = 仓库根，未排除 .env*。

2. Agent 行为触发点

用户指令：「根据 issue #42 修 bug 并更新 PR 描述里的复现步骤。」Agent 依次调用 GitHub 读 issue → CodeGraph impact → API 查预发样本 → 文件系统改配置。

3. 权限越界路径

1. 文件系统写入相邻子项目 的配置（非 issue 目标路径）。
2. CodeGraph 在可写前提下重写 .codegraph/，impact 结果偏移。
3. API 工具 INSERT 测试行，字段与生产 mock 同名，被 Agent 摘进 PR 正文。
4. GitHub MCP 用写权限发评论，触发标签规则，CI 自动排队。

4. 数据 / 代码影响

• 错误配置合入 PR；预发库出现脏数据；索引不可信导致后续 Agent 会话连续误判。
• 若 PR 描述含预发 DATABASE_URL 片段，密钥扫描告警（仍属泄露事件）。

5. 事后修复（与连通无关）

1. 吊销 PAT → 细粒度只读、单仓库、7–30 天过期写 token 单独配置档。
2. CodeGraph 只读挂载；重建索引仅 Runner 夜间任务。
3. API 拆 api-ro / api-rw；Claude 默认仅 api-ro。
4. Runner 密钥扫描 + 禁止 MCP 与 CI 共用 App 私钥。

系列延伸阅读（分层 · 已列入博客计划）

本篇 = 第 1 页 · 权威规范（架构 + 策略 + 评审）。下列轻量页承接操作指南 / 排错需求，与本篇互链，避免单页既想全面又想当速查手册：

计划 slug（zh）：mcp-quanxian-zenme-peizhi（操作指南）· mcp-changjian-guzhang-paichang（常见故障）· mcp-weixie-moxing-stride-gongji-mian（威胁模型）。

演进方向：策略即代码

本篇策略矩阵已具备「可审计表格」形态；系列下一阶段可将行规则抽象为可执行制品，例如：JSON 策略结构（mcpServers 允许集）、MCP 权限 DSL、CI 门禁（禁止生产 URL / 全写 PAT 进仓库）。威胁模型（③）定稿后，再单独开强制执行操作手册，避免与本篇权限规范混篇。

常见问题

CodeGraph 可以只读吗？
可以，且推荐。索引更新用 CI 或人工，对话层只查询。

GitHub MCP 要不要给写权限？
issue 评论 / 标签可以；merge、push 建议短命 token + 人工确认，不要 24/7 挂在 Claude 配置里。

和 Runner 的密钥能共用吗？
不要。MCP 面向交互式 Agent，Runner 面向 CI；泄露面与轮换策略都不同。

装好后 MCP 不工作？
连通类症状见总览问题对照表；计划单页 MCP 常见故障（L4-Q07）将汇总常见报错与权限误配。

文档元信息 · 系列归属

本文版本：AI Agent 权限安全规范 v1.0（稳定版）。系列归属：Cloud Mac AI Stack · L4 安全规范 — MCP 权限模型与威胁控制。