MCP Configuration Management

Overview

This skill helps you properly configure MCP servers in Claude Code. It ensures MCP servers are configured in the right location and scope to avoid unnecessary context pollution across all sessions.

Critical Concepts

Two Valid Configuration Locations

ONLY these two locations are valid for MCP configuration:

1. User/Local scope:

   ~/.claude.json

   • In the

     mcpServers

     field (global for all projects)
   • Or under specific project paths (project-specific in user config)

2. Project scope:

   .mcp.json

   in your project root
   • Checked into source control
   • Only affects the current project

⚠️ Important Rules

• DO NOT configure MCPs in

  ~/.claude.json

  global

  mcpServers

  - This loads MCPs in ALL sessions and wastes context space
• DO configure MCPs in project-level

  .mcp.json

  - This only loads MCPs when working in that specific project
• Avoid

  settings.json

  for MCP control - The

  permissions.allow

  field can override disabled settings and cause confusion

When to Use This Skill

Invoke this skill when:

• Adding a new MCP server to a project
• Removing/disabling an MCP server
• MCP servers are loading when they shouldn't be
• Need to clean up MCP configuration
• Want to understand why an MCP is or isn't loading

Quick Start

Task	Example
Add MCP to current project	"添加 pencil MCP 到当前项目"
Remove MCP from all projects	"从所有项目中移除 shadcn-studio-mcp"
Check MCP configuration	"检查当前的 MCP 配置"
Clean up global MCPs	"清理全局 MCP 配置"

---

Configuration Workflow

1. Check Current MCP Status

First, understand what MCPs are currently loaded:

# Check user-level configuration
cat ~/.claude.json | grep -A 20 '"mcpServers"' | head -25

# Check project-level configuration
cat .mcp.json 2>/dev/null || echo "No project .mcp.json found"

# Check settings.json (should NOT have MCP config)
cat ~/.claude/settings.json | grep -A 5 '"permissions"'

2. Add MCP to Current Project

Best Practice: Always add MCPs at project level

Create or edit

.mcp.json

in your project root:

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

3. Remove MCP Configuration

From global config (

~/.claude.json

):

import json

with open('/Users/likai/.claude.json', 'r') as f:
    data = json.load(f)

# Remove from global mcpServers
if 'mcpServers' in data and 'server-name' in data['mcpServers']:
    del data['mcpServers']['server-name']
    print(f"Removed server-name from global config")

with open('/Users/likai/.claude.json', 'w') as f:
    json.dump(data, f, indent=2)

From project config (

.mcp.json

):

import json

try:
    with open('.mcp.json', 'r') as f:
        data = json.load(f)

    if 'mcpServers' in data and 'server-name' in data['mcpServers']:
        del data['mcpServers']['server-name']

    with open('.mcp.json', 'w') as f:
        json.dump(data, f, indent=2)
    print("Removed server-name from project config")
except FileNotFoundError:
    print("No .mcp.json found in project")

4. Clean Up settings.json

Remove any MCP-related permissions that might override configuration:

import json

with open('/Users/likai/.claude/settings.json', 'r') as f:
    data = json.load(f)

# Remove permissions block if it contains MCP references
if 'permissions' in data:
    if 'allow' in data['permissions']:
        data['permissions']['allow'] = [
            item for item in data['permissions']['allow']
            if not item.startswith('mcp__')
        ]
        if not data['permissions']['allow']:
            del data['permissions']

with open('/Users/likai/.claude/settings.json', 'w') as f:
    json.dump(data, f, indent=2)

---

Common MCP Servers

Pencil (Design Tool)

{
  "mcpServers": {
    "pencil": {
      "command": "/Users/likai/.vscode/extensions/highagency.pencildev-0.6.29/out/mcp-server-darwin-arm64",
      "args": ["--app", "visual_studio_code"],
      "env": {},
      "type": "stdio"
    }
  }
}

Shadcn Studio

{
  "mcpServers": {
    "shadcn-studio-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "shadcn-studio-mcp",
        "API_KEY=your-api-key",
        "EMAIL=your-email"
      ],
      "env": {}
    }
  }
}

Unsplash

{
  "mcpServers": {
    "unsplash": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@microlee666/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your-access-key"
      }
    }
  }
}

---

Troubleshooting

Problem: MCP loads in all sessions

Cause: MCP is configured in

~/.claude.json

global

mcpServers

Solution:

1. Remove from

   ~/.claude.json

   global config
2. Add to project-level

   .mcp.json

   instead
3. Restart Claude Code session

Problem: MCP won't disable despite

"disabled": true

Cause:

permissions.allow

in

settings.json

overrides disabled setting

Solution:

1. Remove MCP from

   settings.json

   permissions
2. Remove the entire

   permissions

   block if empty
3. Restart Claude Code session

Problem: MCP configuration conflicts

Cause: MCP configured in multiple locations with different settings

Solution:

1. Check all three locations:

   ~/.claude.json

   ,

   .mcp.json

   ,

   settings.json

2. Keep configuration in ONE place only (prefer

   .mcp.json

   )
3. Remove from other locations

Problem: Can't find where MCP is configured

Diagnostic commands:

# Search all possible locations
echo "=== Global Config ==="
grep -A 10 '"mcpServers"' ~/.claude.json | head -15

echo "=== Project Config ==="
cat .mcp.json 2>/dev/null || echo "No .mcp.json"

echo "=== Settings ==="
grep -A 5 '"permissions"' ~/.claude/settings.json 2>/dev/null || echo "No permissions"

echo "=== Project Settings ==="
grep -A 5 '"permissions"' .claude/settings.json 2>/dev/null || echo "No project settings"

---

Best Practices

1. ✅ Always use project-level

   .mcp.json

   for project-specific MCPs
2. ✅ Keep

   ~/.claude.json

   global

   mcpServers

   empty to avoid context pollution
3. ✅ Avoid MCP configuration in

   settings.json

   - use it only for permissions if needed
4. ✅ Restart Claude Code after configuration changes to ensure they take effect
5. ✅ Check into source control - Commit

   .mcp.json

   so team members get the same MCPs
6. ❌ Never use

   disabled: true

   - Just remove the MCP configuration entirely
7. ❌ Don't mix configuration locations - Pick one place and stick to it

---

Configuration Priority

When Claude Code loads MCPs, it follows this priority:

1. Project-level

   .mcp.json

   (highest priority)
2. User-level

   ~/.claude.json

   project-specific config
3. User-level

   ~/.claude.json

   global

   mcpServers

4. settings.json

   permissions can override all of the above

Recommendation: Use only project-level

.mcp.json

to avoid confusion.

---

Example: Complete Cleanup and Reconfiguration

# 1. Clean up global config
python3 << 'EOF'
import json
with open('/Users/likai/.claude.json', 'r') as f:
    data = json.load(f)
data['mcpServers'] = {}
with open('/Users/likai/.claude.json', 'w') as f:
    json.dump(data, f, indent=2)
print("✓ Cleaned global mcpServers")
EOF

# 2. Clean up settings.json
python3 << 'EOF'
import json
with open('/Users/likai/.claude/settings.json', 'r') as f:
    data = json.load(f)
if 'permissions' in data:
    del data['permissions']
with open('/Users/likai/.claude/settings.json', 'w') as f:
    json.dump(data, f, indent=2)
print("✓ Cleaned settings.json permissions")
EOF

# 3. Create project-level config
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "your-mcp-name": {
      "type": "stdio",
      "command": "your-command",
      "args": [],
      "env": {}
    }
  }
}
EOF
echo "✓ Created project .mcp.json"

# 4. Restart Claude Code
echo "⚠️  Please restart Claude Code for changes to take effect"

---

Summary

• Two valid locations:

  ~/.claude.json

  and

  .mcp.json

• Best practice: Use project-level

  .mcp.json

  only
• Avoid: Global

  mcpServers

  in

  ~/.claude.json

  (wastes context)
• Avoid: MCP config in

  settings.json

  (causes conflicts)
• Always restart Claude Code after configuration changes