Claude Code MCP 權限模型與最佳實務：GitHub / CodeGraph / API 最小暴露指南

前置：MCP 三連通總覽（先打通再談權限）；安裝步驟見安裝教學（撰寫中）。要快速對照請用下方「適用情境」跳轉；要完整規範請讀全文——本文是 MCP 權限權威規範（v1.0），不是連通教學。

建議閱讀路徑（約 15 分鐘 · 規範全文）：適用情境 → 一句話模型 → 系統模型 → 信任邊界與資料流 → 策略矩陣與控制平面 → 設定片段 → 攻擊鏈。可當團隊 SOP 或資安審查附件引用。

定位：權威規範（可解問題 + 可稽核）

上方「適用情境」把搜尋意圖綁回章節；從本節起進入安全架構規範正文。連通驗收看工具是否註冊（mcp__github__*）；權限驗收看呼叫當下的觸達面：路徑、API、GitHub 資源與 token scope。

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 呼叫前 → 服務唯讀 / scope 最小化
  · 回應注入前 → PII 去識別 · 禁止正式環境欄位
  · 產生副作用前 → 寫入服務未啟用則工具鏈應失敗

攻擊鏈復盤（下文 § 誤設定攻擊鏈）沿此資料流逐步展示：哪一跳的回應被 Agent 誤用，最終觸發 PR / 資料表 / 索引副作用。

常見權限事故路徑（Agent 如何誤操作）

下列路徑在「設定看起來合理」時仍會發生——適合當 code review / 資安審查檢查項：

• GitHub MCP 寫留言 / 標籤 → 觸發依留言運作的 CI bot 或自動合併規則，在未人工確認下推進 pipeline。
• CodeGraph 或檔案系統 MCP 對 repo 可寫 → Agent 修 issue 時改寫 .codegraph/ 或相鄰子專案設定，索引被污染，codegraph_impact 不可信。
• API MCP 對預發可寫 → 測試資料與正式 mock 欄位混用，後續 Agent 把錯誤 schema 當「真相」寫進 PR。
• 檔案系統 MCP 讀工作區根目錄 → 掃到 .env.production 或相鄰 monorepo 密鑰，內容進入對話或 issue 留言。

第二層 · 預設策略原則（矩陣前的結論）

矩陣回答「每一列怎麼配」；本節只保留三條可寫進團隊規範的結論：

1. Claude 工作階段預設只掛唯讀 MCP（*-ro 命名）；任何寫入需短命 token + 明確啟用第二個 MCP 服務。
2. CI / Runner 不透過 MCP 暴露；夜間重建索引、整合測試寫庫由 workflow 完成，不由對話觸發。
3. 正式環境對 Agent 不可見：無正式 URL、無 DATABASE_URL、無 merge/push 級 PAT 常駐 ~/.claude.json。

策略矩陣（建議預設列）

下表依「可機器執行 / 可審查」設計：除資源與預設策略外，標示Claude 自動呼叫、CI 觸發、正式環境觸達三欄，便於對照 Policy as Code 或上手檢查清單。有寫入需求須在 PR 註明原因與過期時間。

控制平面（策略由誰強制執行）

策略矩陣回答「應該怎麼做」；本節回答「誰在哪個環節強制執行」——把最佳實務變成可落地的分層。

策略強制執行點:

  1. MCP 服務設定（~/.claude.json · 靜態 scope · 唯讀服務預設啟用）
  2. 作業系統 / 檔案系統（repo 與 .codegraph/ 唯讀掛載 · 工作目錄隔離）
  3. GitHub App / PAT 主控台（細粒度 · 單一 repo · 過期寫入 token）
  4. CI pipeline（正式 URL 閘門 · 密鑰掃描 · 禁止 PAT 進 repo）
  5. Runner 金庫（CI 憑證與 MCP 環境變數分帳 · 不掛進 mcpServers）

對應策略矩陣欄:
  · Claude 工作階段  → ①②
  · CI / Runner      → ④⑤
  · 正式環境         → ③④（拒絕正式端點 / 全寫 PAT 常駐）

完整可列印清單將單頁化（計畫 MCP 最佳實務檢查清單，見 § 延伸閱讀）；連通類錯誤見計畫中的 MCP 常見故障，與本篇權限規範分工。

GitHub MCP · PAT 與 scope

目標：讓 Claude Code 能讀 issue、在留言引用，但不要把「合併 PR」能力長期交給對話裡的 Agent。

建議分級

• 日常開發（以唯讀為主）：repo（private 讀取）、read:org（需 org 下多 repo 時）；issue 流程加 issues。
• 自動化寫入（短命）：獨立細粒度 PAT，僅指定 repo，勾選 Contents/Issues 寫入，效期 7–30 天，用完即從 mcpServers 移除。

Token 存放：優先環境變數（如 GITHUB_MCP_TOKEN），不要寫進 repo；Cloud Mac 用執行個體級 secret，本機 Mac 用 Keychain / 1Password 注入。

# 示意：scope 思路以 GitHub 現行 PAT 介面為準
# 細粒度 · 單一 repo · Contents 唯讀 + Issues 讀寫

CodeGraph · 唯讀索引實務

CodeGraph 的價值在查詢圖譜，不是讓 MCP 改索引檔。建議：

1. 在 repo 根 codegraph init 後，將 .codegraph/ 視為建置產物（可 gitignore 或另備）。
2. MCP 行程對原始碼唯讀；重建索引用人工或 CI，不用對話觸發。
3. 若 Agent 回報 codegraph_impact 為空，先查索引與工作目錄（見總覽問題表），不要先開寫入權限。

大倉可搭配 CodeGraph 與 AI Coding Agent；權限策略仍適用：圖譜唯讀。

API MCP · 預發環境唯讀

API MCP 用來對齊「真實資料長什麼樣」。最小權限做法：

• 只設定預發 base URL；正式 URL 不出現在 mcpServers 環境區塊。
• 資料庫帳號僅 SELECT；需寫入時用另一服務名（如 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 文件為準；若無此開關，用 OS 權限（唯讀掛載）達成相同效果。

上線前檢查清單（摘要 · 完整版將單頁化）

• □ GitHub PAT 是否為最小 scope，且未 commit 進 git？
• □ 是否存在寫正式環境的 API MCP？若有，是否預設停用？
• □ CodeGraph 是否僅開放 impact/query 類工具？
• □ Cloud Mac 上 Claude 工作目錄是否指向單一 repo，避免讀到相鄰 .env？
• □ Runner 註冊 token 是否與 MCP token 分離？
• □ 團隊是否知道：收緊權限後應改哪份文件？（本篇 + 總覽）

誤設定攻擊鏈復盤

以下為常見組合：表面為了效率合理，但 Agent 鏈式呼叫後權限越界。

1. 初始設定（看似合理）

• 單一 mcpServers：GitHub MCP（repo 寫）+ 檔案系統 + CodeGraph 同行程。
• CodeGraph 對 monorepo 根可寫；API MCP 指預發，但帳號具 INSERT。
• Claude 工作目錄 = repo 根，未排除 .env*。

2. Agent 觸發點

使用者：「依 issue #42 修 bug 並更新 PR 描述裡的 repro 步驟。」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 → 細粒度唯讀、單 repo、7–30 天過期寫 token 獨立設定檔。
2. CodeGraph 唯讀掛載；重建索引僅 Runner 夜間任務。
3. API 拆 api-ro / api-rw；Claude 預設僅 api-ro。
4. Runner 密鑰掃描 + 禁止 MCP 與 CI 共用 App 私鑰。

系列延伸閱讀（分層 · 已列入部落格計畫）

本篇 = 第 1 頁 · 權威規範（架構 + 策略 + 審查）。下列輕量頁承接操作 / 排錯，與本篇互鏈：

計畫 slug（en）：mcp-permissions-how-to-configure（操作）· mcp-common-troubleshooting（故障）· mcp-threat-model-stride（威脅模型）。

演進方向：Policy as Code

本篇策略矩陣已具「可稽核表格」形態；下一階段可將列規則抽象為可執行製品，例如：JSON 策略（mcpServers 允許集）、MCP 權限 DSL、CI 閘門（禁止正式 URL / 全寫 PAT 進 repo）。威脅模型（③）定稿後，再單獨開強制執行操作手冊，避免與本篇混篇。

常見問題

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 權限模型與威脅控制。