MCP設定完全ガイド：Scope、継承、分離アーキテクチャ

Claude Codeを使用する際、MCP（Model Context Protocol）は機能拡張の重要なメカニズムです。しかし、以下のような問題に遭遇したことはありませんか？

MCPツールが多すぎてContextを消費する
不要なMCPを誤ってトリガーしてしまう
特定のタスクでのみ特定のMCPをロードしたい

本記事では、MCP設定メカニズムを徹底解説し、「MCP分離アーキテクチャ」というソリューションを提供します。

1. MCP設定ソース

実際のテストにより、Claude Codeは以下の場所からMCP設定を読み取ります：

CLIコマンド	保存場所	説明
`--scope project`	`.mcp.json`	プロジェクトレベル、gitにコミット可能
`--scope local`	`~/.claude.json`（プロジェクト別）	個人用、プロジェクトパスごとに保存
`--scope user`	`~/.claude/.mcp.json`	グローバル、全プロジェクトでロード

読み取られない場所

以下の場所はClaude Codeによって読み取られません：

場所	ステータス
`.mcp.local.json`	❌ この設定は存在しない
`.claude/.mcp.json`	❌ 既知のバグ（Issue #5037）
`.claude/settings.json`内のmcpServers	❌ 読み取られない

2. Scope優先順位

同名のMCPが複数のScopeに存在する場合、優先順位は：

Local > Project > User > Managed

例えば、database MCPがlocalとproject scopeの両方に存在する場合、localの設定が使用されます。

3. 継承動作（重要！）

これが最も重要な部分です。異なる設定ソースには異なる継承動作があります：

`.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はサブディレクトリ自身）

4. テスト検証

テスト環境

project/                         ← git root
├── .mcp.json                    ← filesystem, memory
├── ~/.claude.json               ← discord-mcp（プロジェクト別）
│
├── 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は継承しなかった

5. 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を実行すればOKです。すべてのサブディレクトリがこの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設定は.mcp.jsonではなく~/.claude.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. 送信前にチャンネルを確認
2. メッセージはプロフェッショナルに

## 戻り値形式
[OK] #generalにメッセージを送信しました
[ERROR] チャンネルが見つかりません

呼び出し方法

Skillを通じて分離されたMCP Workspaceを呼び出します：

cd .mcp-workspaces/discord && claude --print --model haiku -p "#generalにメッセージを送信: Hello"

6. アーキテクチャの利点

利点	説明
Context節約	メインセッションは不要なMCPツール説明をロードしない
正確なトリガー	必要な時にのみ対応するMCPをロード、誤動作を防止
専用ルール	各workspaceは独自のCLAUDE.mdを持てる
コスト最適化	サブセッションは`--model haiku`を使用可能
権限分離	機密MCP（DBなど）により厳格なルールを設定可能

7. 代替案：`--strict-mcp-config`

git initを使用したくない場合は、--strict-mcp-configを使用できます：

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

これは他のMCP設定を完全に無視し、指定された設定ファイルのみを使用します。

8. よくある質問

Q: なぜ`.mcp.local.json`は読み取られないのですか？

このファイル名はClaude Codeでサポートされている設定ファイルではありません。公式には.mcp.jsonのみがサポートされています。

Q: なぜ`.claude/.mcp.json`は読み取られないのですか？

これは既知のバグです。Issue #5037を参照してください。

Q: サブディレクトリには必ずgit initが必要ですか？

~/.claude.jsonのMCPを分離したい場合は、はい。ただし、メインプロジェクトのMCPがすべて.mcp.jsonにある場合、git initしても継承されます。

9. まとめ

設定ソース	継承動作	分離方法
`.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のテストに基づいています。設定動作はバージョン更新により変更される可能性があります。