02-4 claude.json：它存了什麼、為什麼你該認得它

這個單元解決什麼問題~/.claude.json 是 Claude Code 的全域狀態檔，存 MCP server 註冊、各專案的信任與工具核准紀錄、以及一堆 onboarding 與帳號後設資料。它不是給你手寫的策略檔，主要由工具自己寫入。但認得它存了什麼，能讓你在 MCP 連不上、權限對話反覆跳出、信任狀態錯亂時，直接打開檔案定位根因，而不是盲目重裝工具。這個單元給你欄位導覽、可查證的 MCP scope 模型，以及一條「何時能手改、何時別碰」的判準。

學習目標

能說出 ~/.claude.json 大致儲存哪幾類資訊，並指出排查時用得到的段落。
能分清 claude.json（狀態與註冊）與 settings.json（行為策略）的職責邊界，不混用。
能說明 MCP 的三種 scope（local / project / user）各存在哪，以及 .mcp.json 的專案信任如何運作。
能用 claude.json 的內容定位 MCP 不載入或信任對話重複跳出的根因。

1. claude.json 是什麼：狀態檔，不是策略檔

~/.claude.json 是使用者層級的狀態檔，位在你的 home 目錄（Windows 是 C:\Users\<你的帳號>\.claude.json）。它由 Claude Code 工具本身寫入為主，初次啟動時若不存在會自動建立。它和 02-3 的 settings.json 有一條根本分界：

檔案	回答的問題	誰寫	你該手動編輯嗎
`~/.claude.json`	「Claude Code 記住了什麼」（MCP 在哪、這專案信任嗎、哪些工具核准過）	工具自動寫入	否（少數排查情境例外，見第 5 節）
`settings.json`	「Claude Code 應該怎麼行動」（allow / deny 策略、hooks、env）	你	是

settings.json 描述「應該怎麼行為」：權限策略、hooks、env，是你編輯的策略檔。claude.json 記錄「已經發生了什麼」：哪些 MCP server 註冊過、哪個專案你信任過、哪些工具你按了「永遠允許」。這是工具維護的狀態，不是給你手寫的。記住這條分界，就能避開最常見的誤用：把「想永遠允許某工具」的意圖手寫進 claude.json，而不是寫 settings.json 的 permissions.allow。前者是狀態（工具寫的），後者是策略（你寫的），混用會在工具下次更新狀態時被覆蓋。

2. 它存了什麼：欄位導覽

~/.claude.json 最重要的段落是 projects：一個以專案絕對路徑為 key 的物件，每個專案底下記著它專屬的狀態，包括該專案 local scope 的 MCP server。官方文件給的結構長這樣（你從 /path/to/your/project 加一個 local server 後）[1]：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

除了 projects，這個檔案還存一批工具自管的後設資料：onboarding 是否完成、主題、啟動次數、登入帳號資訊等。

官方未提供 claude.json 的完整 schema 文件Anthropic 官方文件正式記載的是 MCP server 在 ~/.claude.json 的 projects.<path>.mcpServers 結構 [1]；至於檔案裡其餘欄位（主題、啟動計數、帳號後設資料、工具核准的持久化等）多屬工具內部狀態，官方未公開完整 schema（截至 2026-05）。所以本節對非 MCP 欄位的描述是實務常見內容，不是逐欄官方契約。這也正是你不該依賴手改這些欄位的原因：格式可能隨版本變動。

排查時你會用到的，主要就是 projects.<你的專案路徑> 底下的 mcpServers（MCP 連不上時第一個看這裡），以及該專案的信任與工具核准狀態（信任對話反覆跳出時看這裡）。

3. 與 settings.json 的分工：記憶 vs 策略

實務上的兩條規則：策略寫 settings.json，別把策略塞進 claude.json；狀態由工具維護，別繞過工具去手改 claude.json 裡的信任紀錄。

4. MCP 的三種 scope 與 .mcp.json 信任

這是認識 claude.json 最需要釐清的一塊，因為 MCP 設定散在不同地方，存錯位置就會「我明明加了卻在別的專案看不到」。Claude Code 的 MCP server 有三種 scope（截至 2026-05）[1]：

Scope	載入範圍	與團隊共享	存在哪
local（預設）	僅當前專案	否	`~/.claude.json`（該專案路徑下）
project	僅當前專案	是（經版控）	`.mcp.json`（專案根）
user	你所有專案	否	`~/.claude.json`

用 claude mcp add 加時用 --scope 指定（options 要放在 server 名稱前面，-- 後接命令）[1]：

# local（預設）：只在當前專案、私有，存 ~/.claude.json
claude mcp add --transport http stripe https://mcp.stripe.com

# project：團隊共享，寫進 .mcp.json（進版控）
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# user：跨你所有專案
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

同一個 server 在多處定義時，Claude Code 依優先序取最高的那一份完整 entry（不跨 scope 合併欄位）：local > project > user > plugin 提供 > claude.ai connector [1]。

MCP 的「local scope」不是 settings.local.json這是官方特別標出的易混點 [1]：MCP 的 local-scoped server 存在 ~/.claude.json（你的 home 目錄）；而 02-3 講的 general local 設定存在 .claude/settings.local.json（專案目錄）。名字都有 local，位置與用途完全不同。一個是「這個 MCP server 只在這專案、只給我」，一個是「我的個人設定覆寫層」。

.mcp.json 的專案信任：官方明說，基於安全考量，使用來自 .mcp.json 的 project-scoped server 前，Claude Code 會先要求你核准 [1]。等待核准的 server 在 claude mcp list 顯示 ⏸ Pending approval，被拒的顯示 ✗ Rejected。要重設這些核准選擇，用 claude mcp reset-project-choices。

4.1 .mcp.json：專案 scope 的設定檔

.mcp.json 放在專案根目錄，是 project-scoped MCP server 的設定來源。它的定位與用途和 claude.json / settings.json 不同，三者差異如下（截至 2026-05）[1][2]：

檔案	scope	進版控	誰寫	誰讀
`~/.claude.json`	local（當前專案私有）& user（跨所有專案）	否	Claude Code 工具自動寫入	Claude Code
`~/.claude/settings.json`	user 全域	依個人習慣	你	Claude Code
`.claude/settings.json`	project	是（團隊共享）	你	Claude Code
`.claude/settings.local.json`	local 個人覆寫	否（gitignore）	你	Claude Code
`.mcp.json`	project MCP server	是（團隊共享）	你（或 `claude mcp add --scope project`）	Claude Code

.mcp.json 的格式與 ~/.claude.json 裡的 mcpServers 區塊相同：

{
  "mcpServers": {
    "stripe": {
      "type": "http",
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer ${STRIPE_API_KEY}"
      }
    },
    "local-tools": {
      "type": "stdio",
      "command": "node",
      "args": [".claude/mcp-tools/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

個人啟停控制：settings.local.json（不進版控）可用 enabledMcpjsonServers 與 disabledMcpjsonServers 控制哪些 .mcp.json 裡的 server 對你生效，不影響其他人 [2]：

{
  "enabledMcpjsonServers": ["stripe"],
  "disabledMcpjsonServers": ["local-tools"]
}

供應鏈風險：.mcp.json 裡禁止明文密鑰.mcp.json 進版控，整個團隊都看得到它的內容，也包括 git 歷史。密鑰（API key / token）一律改用環境變數引用（${ENV_VAR_NAME}），由每個人的本機環境或 CI 注入；明文寫進 .mcp.json 等於把密鑰推上 git，難以乾淨清除。安全邊界：clone 外部 repo 時，先看它的 .mcp.json 有沒有不認得的 server，再決定是否信任並核准（詳見 03-3）。

MCP 連不上：分支診斷

5. 安全邊界與排查：何時能動、何時別碰

claude.json 多數時候別手改，但有兩類情境手改是合理的，另兩類則會弄壞狀態。 可以手改：移除過期的 MCP server 項目（從 mcpServers 刪一個 key）；清掉指向已搬移專案的錯誤路徑信任紀錄。 不要手改：繞過工具直接改信任或核准紀錄，會讓檔案狀態與工具認知不一致；改了 MCP server 命令卻沒同步更新它的 env 變數，server 會啟動失敗，而 Claude Code 仍嘗試連線。

手改前先備份claude.json 損壞會讓所有 MCP 與信任設定失效。手改前先備份，確認工具正常後再刪：

Copy-Item ~/.claude.json ~/.claude.json.bak

MCP 連不上的排查順序：

查 claude.json / .mcp.json

看 ~/.claude.json 的 projects.<當前專案路徑>.mcpServers（或 .mcp.json）裡該 server 的命令路徑、URL 是否正確。

確認 env 變數完整

stdio server 缺 key 會啟動失敗。

用工具指令查狀態

用 claude mcp list / claude mcp get <name> 看狀態，或在 Claude Code 內用 /mcp 看連線與工具數 [1]。

確認是否 Pending

project-scoped server 若顯示 ⏸ Pending approval，是還沒核准，不是連線壞。

信任對話反覆跳出的排查：通常是 projects 裡沒有對應路徑、或路徑不符。Windows 特別注意：路徑大小寫、反斜線與正斜線、trailing slash 不一致都會被當成不同專案，於是每次都重新要求信任。

供應鏈風險：外來 repo 的 .mcp.jsonclone 一個外部 repo 時，它可能帶 .mcp.json，裡面定義你不認得的 MCP server。雖然 project-scoped server 預設要你核准才會用 [1]，但若 enableAllProjectMcpServers 這類自動核准選項被開啟，等於對外來 repo 敞開 MCP 執行權 [2]。檢查點：clone 外部 repo 後、信任目錄前，先看一眼它的 .mcp.json 與你的 ~/.claude.json，確認沒有不認得的 server 被自動加入。完整的威脅模型與相關 CVE 見 03-3。

工具對照

「工具自維護的狀態檔」與「MCP scope 分層」這兩個概念，各家成熟度差異大（截至 2026-05，精確路徑與鍵以各官方文件為準）：

概念	Anthropic Claude（主範本）	OpenAI (Codex)	Google (Gemini CLI)	Cursor
工具自維護的狀態檔	`~/.claude.json`（MCP 註冊、信任、工具核准）[1]	以 OpenAI 官方文件為準	以 Google 官方文件為準	以 Cursor 官方文件為準
MCP server 設定位置	local / user 存 `~/.claude.json`；project 存 `.mcp.json` [1]	config.toml 內 MCP 區段（精確鍵以官方文件為準）	settings.json 的 `mcpServers` 區段	`.cursor/mcp.json`（以官方文件為準）
MCP scope 分層	local / project / user 三層 [1]	以官方文件為準	以官方文件為準	以官方文件為準
專案級 MCP 需信任核准	是，`.mcp.json` 預設要核准 [1]	以官方文件為準	以官方文件為準	以官方文件為準

MCP 是跨工具標準，scope 模型各異MCP 本身是開放標準，多數 agent 工具都支援連接 MCP server；差別在「設定存哪、有沒有 scope 分層、專案級 server 要不要強制核准」。Claude Code 的 local / project / user 三層加 .mcp.json 強制核准目前最完整 [1]；其他工具多半只有單一設定位置，scope 與信任模型較弱或未明確文件化，精確細節以各工具官方文件為準。

動手做

讀出 ~/.claude.json，辨認三個關鍵段落

打開檔案，找到 projects.<你的某個專案路徑>，辨認它底下的 mcpServers（local scope 的 server）。對照 claude mcp list 的輸出，確認檔案內容與工具認知一致。

模擬一次 MCP 連線失敗並定位它

先 Copy-Item ~/.claude.json ~/.claude.json.bak 備份。把某個 stdio server 的命令路徑故意改錯，啟動 Claude Code，用 /mcp 觀察它的狀態（應顯示連線失敗），再用第 5 節的排查順序定位、改回。確認沒問題後刪備份。

常見誤區

反模式清單

把「永遠允許」手寫進 claude.json：要批量預先允許工具，改 settings.json 的 permissions.allow（策略）。手改 claude.json 的核准紀錄（狀態）會在工具更新狀態時被覆蓋。
MCP 連不上就重裝工具：先看 claude.json / .mcp.json 裡 server 項目的命令路徑與 env 是否正確，多數問題在這裡，不在工具本身。
信任對話跳出時點「僅此工作階段允許」，事後抱怨每次都要確認：那個選項本來就不持久化。要它記住，選持久化選項讓工具寫入狀態。
把 MCP 的 local scope 當成 settings.local.json：兩者位置與用途不同（見第 4 節 callout）。存錯地方就會找不到 server。
手改 claude.json 不備份：檔案損壞會讓所有 MCP 與信任設定失效。

自我檢核

通過本單元的標準

你能不能用一句話分清 claude.json（狀態，工具寫）與 settings.json（策略，你寫）？要批量允許一個工具，你改哪個檔？
你想讓某個 MCP server 只對特定專案可見且不分享給團隊，該用哪個 scope、存在哪個檔？要團隊共享呢？
MCP 的 local scope 存在 ~/.claude.json，那 .claude/settings.local.json 又是什麼？兩者差在哪？
信任對話在同一個專案反覆跳出，你會先檢查 claude.json 的哪個段落？Windows 上最可能的成因是什麼？
clone 一個帶 .mcp.json 的外部 repo，預設情況下它的 server 會直接執行嗎？什麼設定會讓它被自動核准？

來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。

[1] Anthropic, “Connect Claude Code to tools via MCP,” Claude Code Docs. （MCP 三種 scope local / project / user 與儲存位置；~/.claude.json 的 projects.<path>.mcpServers 結構；.mcp.json project-scoped server 需核准、claude mcp reset-project-choices、⏸ Pending approval；claude mcp add --scope；MCP local scope 不同於 settings.local.json；scope 優先序；.mcp.json 的 mcpServers 格式） https://code.claude.com/docs/en/mcp （截至 2026-05）
[2] Anthropic, “Claude Code settings,” Claude Code Docs. （enableAllProjectMcpServers 自動核准專案 MCP；enabledMcpjsonServers / disabledMcpjsonServers 個人啟停 .mcp.json 中的 server；managed 層 allowedMcpServers / deniedMcpServers） https://code.claude.com/docs/en/settings （截至 2026-05）

銜接：02-3 settings.json 的策略面與 local 設定、02-5 plugin 提供的 MCP server、01-6 權限與信任在 harness 中的位置、03-3 外來 repo 與 MCP 的供應鏈威脅模型、04-9 MCP 整合的深入設定。

總覽

Part I 基礎與進階認識

Part II 進階調適與設定

Part III 認知與思維

Part IV 客製化、整合與自動化

Part V Agentic 案例研究

附錄

02-4 claude.json：它存了什麼、為什麼你該認得它

學習目標

1. claude.json 是什麼：狀態檔，不是策略檔

2. 它存了什麼：欄位導覽

3. 與 settings.json 的分工：記憶 vs 策略

4. MCP 的三種 scope 與 .mcp.json 信任

4.1 .mcp.json：專案 scope 的設定檔

MCP 連不上：分支診斷

5. 安全邊界與排查：何時能動、何時別碰

工具對照

動手做

常見誤區

自我檢核

來源與延伸閱讀

​學習目標

​1. claude.json 是什麼：狀態檔，不是策略檔

​2. 它存了什麼：欄位導覽

​3. 與 settings.json 的分工：記憶 vs 策略

​4. MCP 的三種 scope 與 .mcp.json 信任

​4.1 .mcp.json：專案 scope 的設定檔

​MCP 連不上：分支診斷

​5. 安全邊界與排查：何時能動、何時別碰

​工具對照

​動手做

​常見誤區

​自我檢核

​來源與延伸閱讀

學習目標

1. claude.json 是什麼：狀態檔，不是策略檔

2. 它存了什麼：欄位導覽

3. 與 settings.json 的分工：記憶 vs 策略

4. MCP 的三種 scope 與 .mcp.json 信任

4.1 .mcp.json：專案 scope 的設定檔

MCP 連不上：分支診斷

5. 安全邊界與排查：何時能動、何時別碰

工具對照

動手做

常見誤區

自我檢核

來源與延伸閱讀