MCPInstall

mcp-config

by libukaiAI & Agents

Configure MCP (Model Context Protocol) servers for Claude Code. Manage MCP servers at user or project scope with best practices to avoid context pollution.

Installs
505
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/libukai/awesome-agent-skills --skill mcp-config
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads mcp-config automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

TaskExample
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

FAQ

What does the mcp-config skill do?

Configure MCP (Model Context Protocol) servers for Claude Code. Manage MCP servers at user or project scope with best practices to avoid context pollution.

How do I install mcp-config?

Run npx skills add https://github.com/libukai/awesome-agent-skills --skill mcp-config in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mcp-config/ (personal) or .claude/skills/mcp-config/ (project).

Which AI agents can use mcp-config?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is mcp-config safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains mcp-config?

It is published by libukai in libukai/awesome-agent-skills. It has 505 recorded installs.

More from libukai/awesome-agent-skills

View all →

vscode-sftp-config

libukai/awesome-agent-skills

This skill should be used when setting up SFTP deployment for static websites to production servers, including converting projects from Docker/Express to static hosting, deploying Vue/React/Angular builds, setting up Slidev presentations, or configuring Hugo/Jekyll/Gatsby sites. Use this when the user asks to "setup SFTP deployment", "deploy static site to server", "configure Nginx for static files", "convert from Docker to static hosting", "deploy Vue build to production", "setup subdomain hosting", or "configure SFTP in VS Code". Provides SFTP configuration templates and production-ready Nginx configurations with security headers and caching.

DevOps & Cloud557 installs

vscode-httpyac-config

libukai/awesome-agent-skills

Configure VSCode with httpYac for API testing and automation. This skill should be used specifically when converting API documentation to executable .http files (10+ endpoints), setting up authentication flows with pre-request scripts, implementing request chaining with response data, organizing multi-file collections with environment management, or establishing Git-based API testing workflows with CI/CD integration.

Backend & APIs513 installs

vscode-port-monitor-config

libukai/awesome-agent-skills

This skill should be used when configuring VS Code Port Monitor extension for development server monitoring. Use when the user asks to "set up port monitoring for Vite", "monitor my dev server ports", "configure port monitor for Next.js", "track which ports are running", "set up multi-port monitoring", "monitor frontend and backend ports", or "check port status in VS Code". Provides ready-to-use configuration templates for Vite (5173), Next.js (3000), and microservices architectures with troubleshooting guidance.

Frontend & Design507 installs

obsidian-to-x

libukai/awesome-agent-skills

发布内容和文章到 X (Twitter)。支持常规推文(文字/图片/视频)和 X Articles(长文 Markdown)。使用真实 Chrome 浏览器绕过反机器人检测。当用户说"发推"、"发到 X"、"发到 twitter"、"分享到 X"、"分享到 twitter"、"发 tweet"、"同步到 X"、"发布到 X"、提到"X Articles"、想从 Obsidian 笔记发布长文内容、或需要转换 Obsidian Markdown 到 X 格式时使用。适用于所有 X/Twitter 发布任务。

Productivity & Automation507 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs