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

---
name: mcp-manager
description: 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
```json
{
  "cognitive-memory": {
    "type": "stdio",
    "category": "memory",
    "description": "Cognitive memory system with decay scoring, episodic logging, and graph relationships",
    "triggers": ["memory", "recall", "remember", "cognitive"],
    "command": "/home/cal/.claude/skills/cognitive-memory/mcp-server/cognitive-memory-mcp",
    "alwaysLoaded": true
  },
  "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 `cognitive-memory`, `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 (cognitive-memory)
- **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
```python
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

```bash
# 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
- **Smart Defaults**: `cognitive-memory` stays loaded by default; all others are on-demand

---

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