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
2. In the mcpServers field (global for all projects)

3. Or under specific project paths (project-specific in user config)

4. Project scope: .mcp.json in your project root

5. Checked into source control
6. 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

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