claude-configs/skills/mcp-manager/SKILL.md

name	description
mcp-manager	Intelligent MCP server management - automatically loads/unloads MCP servers on-demand to minimize context usage. Detects when MCPs are needed based on task requirements and manages configuration dynamically.

MCP Manager - Intelligent MCP Loading System

Purpose

Minimize context consumption by only loading MCP servers when they're actually needed for a task, then unloading them when complete.

How It Works

Auto-Detection

When user makes a request, analyze the task to determine if any MCPs would be useful:

n8n Workflow Automation:

• Keywords: "n8n", "workflow", "automation", "webhook", "n8n node", "n8n template"
• MCPs: n8n-mcp

Web Scraping & Automation:

• Keywords: "scrape", "extract from website", "crawl", "get data from", "browser automation", "screenshot website"
• MCPs: playwright

MCP Registry

{
  "n8n-mcp": {
    "type": "stdio",
    "category": "automation",
    "description": "n8n workflow automation - node docs, templates, workflow management via API",
    "triggers": ["n8n", "workflow", "automation", "webhook", "n8n node", "n8n template"],
    "command": "npx",
    "args": ["n8n-mcp"],
    "env": {
      "MCP_MODE": "stdio",
      "N8N_API_URL": "http://10.10.0.210:5678",
      "N8N_API_KEY": "~/.claude/secrets/n8n_api_key",
      "N8N_MCP_TELEMETRY_DISABLED": "true",
      "DISABLE_CONSOLE_OUTPUT": "true",
      "LOG_LEVEL": "error"
    }
  },
  "playwright": {
    "type": "stdio",
    "category": "automation",
    "description": "Browser automation and testing",
    "triggers": ["browser", "screenshot", "playwright", "automate browser"],
    "command": "npx",
    "args": ["@anthropic/mcp-playwright"]
  }
}

Note: The actual MCP server definitions (with real credentials) live in ~/.claude/.mcp-full.json. The registry above documents triggers and categories for auto-detection. Credentials like N8N_API_KEY are stored in ~/.claude/secrets/ and referenced by the full config.

Commands & Usage

Automatic Mode (Default)

The skill operates proactively - no explicit invocation needed:

1. User makes request → Skill analyzes for MCP requirements
2. If MCPs needed → Enable them, notify user, proceed with task
3. Task complete → Offer to unload MCPs to free context

Manual Commands

User can explicitly manage MCPs:

• load mcp [name] - Enable specific MCP(s)
• unload mcp [name] - Disable specific MCP(s)
• list mcps - Show all available MCPs and their status
• mcp status - Show currently loaded MCPs
• reset mcps - Restore to minimal default configuration

Example Workflow

User: "Help me create an n8n workflow for monitoring Proxmox backups"

Claude:

Detected need for n8n workflow automation.
Loading MCP: n8n-mcp

[Modifies .mcp.json to enable n8n-mcp from .mcp-full.json]
⚠️  Note: Claude Code restart required for MCP changes to take effect.
Would you like me to continue with the task after restart?

After task completion:

Task complete!
Currently loaded MCPs: n8n-mcp (consuming ~1500 tokens)
Would you like me to unload n8n-mcp to free up context? (yes/no)

Configuration Files

Where Claude Code Actually Reads MCP Config

Claude Code reads MCP server definitions from two locations:

1. Global: ~/.claude.json → top-level mcpServers key (always-on MCPs like gitea-mcp, n8n-mcp, tui-driver)
2. Project: <project-root>/.mcp.json → mcpServers key (on-demand MCPs)

IMPORTANT: ~/.claude/.mcp.json is NOT read by Claude Code. Global servers go in ~/.claude.json. The mcp-manager operates on the project-level .mcp.json (auto-detected via git root) for on-demand servers.

Locations

• Global Config: ~/.claude.json → always-on MCPs
• Project Config: <project-root>/.mcp.json → on-demand MCPs (n8n-mcp, playwright, etc.)
• Full Registry: ~/.claude/.mcp-full.json (all available MCP definitions with credentials)
• Backup: <project-root>/.mcp.json.backup (auto-created before changes)

Safety

• Always backup before modifications
• Validate JSON before writing
• Preserve API keys and credentials
• Log all changes to ~/.claude/logs/mcp-manager.log

Implementation Details

Enable MCP

1. Detect project root (git root or CWD)
2. Read current <project>/.mcp.json
3. Backup to <project>/.mcp.json.backup
4. Read full MCP definition from ~/.claude/.mcp-full.json
5. Merge MCP into project config
6. Write updated <project>/.mcp.json
7. Log change
8. Notify user (restart required)

Disable MCP

1. Read current <project>/.mcp.json
2. Backup to <project>/.mcp.json.backup
3. Remove MCP from mcpServers object
4. Write updated <project>/.mcp.json
5. Log change
6. Notify user (restart required)

Detection Logic

def detect_required_mcps(user_request: str) -> list[str]:
    """Analyze user request and return list of recommended MCPs"""
    request_lower = user_request.lower()
    required = []

    for mcp_name, mcp_info in MCP_REGISTRY.items():
        for trigger in mcp_info["triggers"]:
            if trigger in request_lower:
                required.append(mcp_name)
                break

    return list(set(required))  # deduplicate

User Experience

Transparent Operation

• Inform user when MCPs are loaded/unloaded
• Show context savings
• Explain why specific MCPs are recommended
• Always ask before unloading (user may want to keep them)

Context Awareness

• Track token usage per MCP (estimated)
• Show total context consumed by loaded MCPs
• Recommend unloading when many MCPs are active
• Prioritize keeping frequently-used MCPs loaded

Restart Handling

MCPs require Claude Code restart to take effect. Options:

1. Defer task - "Please restart Claude Code, then ask me again"
2. Plan ahead - "After restart, I'll proceed with [task summary]"
3. Manual mode - User handles enabling and restarting themselves

Error Handling

• Invalid JSON: Restore from backup, notify user
• Missing credentials: Warn user, skip MCP
• File permission errors: Use sudo or notify user
• Parse errors: Detailed error message with line number

Proactive Use

This skill should be invoked automatically by Claude when:

1. User request contains MCP trigger keywords
2. Task clearly requires external service (documentation, scraping, etc.)
3. User asks "can you..." for tasks requiring MCPs
4. Current context is high and MCPs could be unloaded

When to Auto-Enable MCPs

Before starting a task:

1. Analyze user request for trigger keywords
2. Run: python3 ~/.claude/skills/mcp-manager/mcp_control.py detect "<user request>"
3. If MCPs detected:
   • Inform user: "Detected need for [MCP names]. Loading them now..."
   • Run: python3 ~/.claude/skills/mcp-manager/mcp_control.py enable <mcp_name> for each
   • Show restart notice
   • Ask user: "Please restart Claude Code to activate these MCPs, then re-submit your request."

After completing a task:

1. Check loaded MCPs: python3 ~/.claude/skills/mcp-manager/mcp_control.py status
2. If MCPs were loaded for this task only:
   • Inform user: "Task complete! Currently using ~X tokens for MCPs: [list]"
   • Ask: "Would you like me to unload these to free up context?"
   • If yes: Run disable commands

Quick Commands Reference

# Check what's loaded
python3 ~/.claude/skills/mcp-manager/mcp_control.py status

# Detect needed MCPs from user query
python3 ~/.claude/skills/mcp-manager/mcp_control.py detect "check what tech stack reddit.com uses"

# Enable specific MCP
python3 ~/.claude/skills/mcp-manager/mcp_control.py enable httpx

# Disable specific MCP
python3 ~/.claude/skills/mcp-manager/mcp_control.py disable httpx

# List all MCPs
python3 ~/.claude/skills/mcp-manager/mcp_control.py list

# Reset to minimal (unload all)
python3 ~/.claude/skills/mcp-manager/mcp_control.py reset

Notes

• Restart Requirement: MCP changes require Claude Code restart - always inform user
• Context Savings: Each unused MCP saves ~200-1000 tokens depending on complexity
• Credential Safety: Never modify or expose API keys/tokens
• Minimal Default: Start each session with minimal MCPs, load on-demand

---

Created: 2025-11-09 Updated: 2026-02-19 Version: 1.1.0