MCP 設定完全指南：Scope、繼承與隔離架構

在使用 Claude Code 時，MCP (Model Context Protocol) 是擴展功能的重要機制。但你可能遇過這些問題：

MCP 工具太多，佔用大量 Context
不小心觸發了不需要的 MCP
想在特定任務才載入特定 MCP

本文將深入解析 MCP 的設定機制，並提供一個「MCP 隔離架構」的解決方案。

一、MCP 設定來源

經過實測，Claude Code 會讀取以下位置的 MCP 設定：

CLI 指令	存儲位置	說明
`--scope project`	`.mcp.json`	專案層級，可 commit 到 git
`--scope local`	`~/.claude.json` (per-project)	個人專用，按專案路徑存放
`--scope user`	`~/.claude/.mcp.json`	全域，所有專案都會載入

不被讀取的位置

以下位置不會被 Claude Code 讀取：

位置	狀態
`.mcp.local.json`	❌ 不存在此設定
`.claude/.mcp.json`	❌ 已知 Bug (Issue #5037)
`.claude/settings.json` 中的 mcpServers	❌ 不讀取

二、Scope 優先級

當同名 MCP 存在於多個 Scope 時，優先級為：

Local > Project > User > Managed

例如，如果 database MCP 同時存在於 local 和 project scope，會使用 local 的設定。

三、繼承行為（關鍵！）

這是最重要的部分。不同設定來源有不同的繼承行為：

`.mcp.json` 的繼承行為

向上搜尋所有父目錄，全部合併載入。

project/
├── .mcp.json              ← MCP-A, MCP-B
└── sub-folder/
    └── .mcp.json          ← MCP-C

在 sub-folder/ 執行 Claude Code 時，會載入：A + B + C

重點：這個行為跟 git 無關！ 即使子目錄有自己的 .git，仍會繼承父目錄的 .mcp.json。

`~/.claude.json` 的繼承行為

只對 git root 匹配的專案有效。

~/.claude.json 的結構是按專案路徑存放：

{
  "/Users/xxx/my-project": {
    "mcpServers": {
      "discord-mcp": { "command": "node", "args": [...] }
    }
  }
}

情況	是否載入 `~/.claude.json` 的 MCP
子目錄沒有 `.git`	✅ 載入（git root 是主專案）
子目錄有 `.git`	❌ 不載入（git root 是子目錄自己）

四、實測驗證

測試環境

project/                         ← git root
├── .mcp.json                    ← filesystem, memory
├── ~/.claude.json               ← discord-mcp (per-project)
│
├── sub-no-git/
│   └── .mcp.json                ← unique-no-git
│
└── sub-with-git/
    ├── .git/
    └── .mcp.json                ← unique-with-git

測試結果

目錄	載入的 MCP
project/	filesystem, memory, discord-mcp
sub-no-git/	filesystem, memory, discord-mcp, unique-no-git
sub-with-git/	filesystem, memory, unique-with-git

觀察：

sub-no-git 繼承了所有主專案的 MCP（包括 ~/.claude.json 的）
sub-with-git 繼承了 .mcp.json 的 MCP，但沒有繼承 ~/.claude.json 的

五、MCP 隔離架構

基於以上發現，我們可以設計一個「MCP 隔離架構」：

架構設計

project/
├── .mcp.json                    ← 空或只放共用 MCP
│
└── .mcp-workspaces/
    ├── .git/                    ← 只需在這層 git init 一次！
    ├── .mcp.json                ← 保持空
    │
    ├── discord/
    │   ├── .mcp.json            ← 只有 discord MCP
    │   └── CLAUDE.md            ← Discord 專屬操作規則
    │
    └── memory/
        ├── .mcp.json            ← 只有 memory MCP
        └── CLAUDE.md            ← Memory 專屬操作規則

優化：只需在 .mcp-workspaces/ 層級執行一次 git init，所有子目錄都會共享這個 git root，從而隔離主專案 ~/.claude.json 的 MCP。

設定步驟

1. 主專案 MCP 使用 `--scope local`

cd my-project
claude mcp add --scope local discord-mcp -- node /path/to/discord-mcp

這樣 MCP 設定會存到 ~/.claude.json，而不是 .mcp.json。

2. 建立隔離的 MCP Workspace

mkdir -p .mcp-workspaces/discord
cd .mcp-workspaces/discord

# 初始化 git（關鍵！）
git init

# 加入專屬 MCP
claude mcp add --scope project discord-mcp -- node /path/to/discord-mcp

3. 建立專屬 CLAUDE.md

# Discord MCP Workspace

## 可用工具
- `mcp__discord-mcp__send-message` - 發送訊息
- `mcp__discord-mcp__read-messages` - 讀取訊息

## 操作規則
1. 發送前確認 channel 正確
2. 訊息內容保持專業

## 回傳格式
[OK] 訊息已發送到 #general
[ERROR] 找不到頻道

呼叫方式

透過 Skill 呼叫隔離的 MCP Workspace：

cd .mcp-workspaces/discord && claude --print --model haiku -p "發送訊息到 #general: Hello"

六、架構優點

優點	說明
Context 節省	主 session 不載入不需要的 MCP tools 描述
精準觸發	只在需要時才載入對應 MCP，避免誤觸
專屬規則	每個 workspace 可以有自己的 CLAUDE.md
成本優化	子 session 可用 `--model haiku` 處理簡單任務
權限隔離	敏感 MCP（如 DB）可以設更嚴格的規則

七、替代方案：`--strict-mcp-config`

如果不想使用 git init 的方式，可以用 --strict-mcp-config：

claude --strict-mcp-config --mcp-config .mcp-workspaces/discord/.mcp.json -p "..."

這會完全忽略其他 MCP 設定，只使用指定的設定檔。

八、常見問題

Q: 為什麼 `.mcp.local.json` 不被讀取？

這個檔案名稱不是 Claude Code 支持的設定檔。官方只支持 .mcp.json。

Q: 為什麼 `.claude/.mcp.json` 不被讀取？

這是已知的 Bug，參見 Issue #5037。

Q: 子目錄一定要 git init 嗎？

如果你想隔離 ~/.claude.json 中的 MCP，是的。但如果主專案的 MCP 都在 .mcp.json 中，就算 git init 也會繼承。

九、總結

設定來源	繼承行為	如何隔離
`.mcp.json`	向上搜尋，全部繼承	無法完全隔離
`~/.claude.json`	只對 git root 匹配	子目錄 `git init`

最佳實踐：

主專案常用 MCP → --scope local（存 ~/.claude.json）
共用 MCP → .mcp.json（會被子目錄繼承）
隔離 MCP → 子目錄 git init + .mcp.json

參考資料

本文基於 Claude Code v2.1.9 實測，設定行為可能隨版本更新而改變。