MCP Config: Scope, Inheritance & Isolation Guide

When using Claude Code, MCP (Model Context Protocol) is a crucial mechanism for extending functionality. But you might have encountered these issues:

Too many MCP tools consuming Context
Accidentally triggering unwanted MCPs
Wanting to load specific MCPs only for specific tasks

This article will thoroughly explain MCP configuration mechanisms and provide an “MCP Isolation Architecture” solution.

1. MCP Configuration Sources

Through testing, Claude Code reads MCP configurations from these locations:

CLI Command	Storage Location	Description
`--scope project`	`.mcp.json`	Project level, can be committed to git
`--scope local`	`~/.claude.json` (per-project)	Personal use, stored by project path
`--scope user`	`~/.claude/.mcp.json`	Global, loaded for all projects

Locations NOT Read

The following locations are NOT read by Claude Code:

Location	Status
`.mcp.local.json`	❌ This setting doesn’t exist
`.claude/.mcp.json`	❌ Known Bug (Issue #5037)
mcpServers in `.claude/settings.json`	❌ Not read

2. Scope Priority

When the same MCP exists in multiple scopes, priority is:

Local > Project > User > Managed

For example, if database MCP exists in both local and project scope, the local setting is used.

3. Inheritance Behavior (Critical!)

This is the most important part. Different configuration sources have different inheritance behaviors:

`.mcp.json` Inheritance Behavior

Searches upward through all parent directories, merging all configurations.

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

When running Claude Code in sub-folder/, it loads: A + B + C

Key point: This behavior is independent of git! Even if the subdirectory has its own .git, it still inherits parent directory’s .mcp.json.

`~/.claude.json` Inheritance Behavior

Only effective for projects matching git root.

~/.claude.json structure stores settings by project path:

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

Situation	Loads MCP from `~/.claude.json`?
Subdirectory without `.git`	✅ Yes (git root is main project)
Subdirectory with `.git`	❌ No (git root is subdirectory itself)

4. Test Verification

Test Environment

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

Test Results

Directory	Loaded MCPs
project/	filesystem, memory, discord-mcp
sub-no-git/	filesystem, memory, discord-mcp, unique-no-git
sub-with-git/	filesystem, memory, unique-with-git

Observations:

sub-no-git inherited all main project MCPs (including ~/.claude.json)
sub-with-git inherited .mcp.json MCPs, but NOT ~/.claude.json MCPs

5. MCP Isolation Architecture

Based on these findings, we can design an “MCP Isolation Architecture”:

Architecture Design

project/
├── .mcp.json                    ← Empty or shared MCPs only
│
└── .mcp-workspaces/
    ├── .git/                    ← Only need git init once at this level!
    ├── .mcp.json                ← Keep empty
    │
    ├── discord/
    │   ├── .mcp.json            ← Only discord MCP
    │   └── CLAUDE.md            ← Discord-specific rules
    │
    └── memory/
        ├── .mcp.json            ← Only memory MCP
        └── CLAUDE.md            ← Memory-specific rules

Optimization: You only need to run git init once at the .mcp-workspaces/ level. All subdirectories will share this git root, isolating them from the main project’s ~/.claude.json MCPs.

Setup Steps

1. Use `--scope local` for Main Project MCPs

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

This stores MCP settings in ~/.claude.json, not .mcp.json.

2. Create Isolated MCP Workspace

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

# Initialize git (critical!)
git init

# Add dedicated MCP
claude mcp add --scope project discord-mcp -- node /path/to/discord-mcp

3. Create Dedicated CLAUDE.md

# Discord MCP Workspace

## Available Tools
- `mcp__discord-mcp__send-message` - Send message
- `mcp__discord-mcp__read-messages` - Read messages

## Operation Rules
1. Confirm channel before sending
2. Keep messages professional

## Return Format
[OK] Message sent to #general
[ERROR] Channel not found

Invocation Method

Call isolated MCP Workspace through Skills:

cd .mcp-workspaces/discord && claude --print --model haiku -p "Send message to #general: Hello"

6. Architecture Benefits

Benefit	Description
Context Savings	Main session doesn’t load unnecessary MCP tool descriptions
Precise Triggering	Only loads corresponding MCP when needed, avoiding accidents
Dedicated Rules	Each workspace can have its own CLAUDE.md
Cost Optimization	Sub-sessions can use `--model haiku` for simple tasks
Permission Isolation	Sensitive MCPs (like DB) can have stricter rules

7. Alternative: `--strict-mcp-config`

If you don’t want to use git init, you can use --strict-mcp-config:

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

This completely ignores other MCP settings, using only the specified config file.

8. FAQ

Q: Why isn’t `.mcp.local.json` read?

This filename is not a supported configuration file in Claude Code. Only .mcp.json is officially supported.

Q: Why isn’t `.claude/.mcp.json` read?

This is a known bug, see Issue #5037.

Q: Must subdirectories have git init?

If you want to isolate MCPs from ~/.claude.json, yes. But if main project MCPs are all in .mcp.json, they’ll be inherited even with git init.

9. Summary

Configuration Source	Inheritance Behavior	How to Isolate
`.mcp.json`	Searches upward, inherits all	Cannot fully isolate
`~/.claude.json`	Only matches git root	Subdirectory `git init`

Best Practices:

Frequently used MCPs → --scope local (stored in ~/.claude.json)
Shared MCPs → .mcp.json (inherited by subdirectories)
Isolated MCPs → Subdirectory git init + .mcp.json

References

This article is based on Claude Code v2.1.9 testing. Configuration behavior may change with version updates.