Skip to content

mcp-management

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

mcp-management

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
assets
assets
 
 
references
references
 
 
scripts
scripts
 
 
README.md
README.md
 
 
SKILL.md
SKILL.md
 
 

README.md

MCP Management Skill

Intelligent management and execution of Model Context Protocol (MCP) servers.

Overview

This skill enables Claude to discover, analyze, and execute MCP server capabilities without polluting the main context window. Perfect for context-efficient MCP integration using subagent-based architecture.

Features

  • Multi-Server Management: Connect to multiple MCP servers from single config
  • Intelligent Tool Discovery: Analyze which tools are relevant for specific tasks
  • Progressive Disclosure: Load only necessary tool definitions
  • Execution Engine: Call MCP tools with proper parameter handling
  • Context Efficiency: Delegate MCP operations to mcp-manager subagent

Quick Start

1. Install Dependencies

cd .claude/skills/mcp-management/scripts
npm install

2. Configure MCP Servers

Create .claude/.mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
    }
  }
}

See .claude/.mcp.json.example for more examples.

3. Test Connection

cd .claude/skills/mcp-management/scripts
npm run list-tools
# Or directly:
npx tsx cli.ts list-tools

Note: The CLI automatically looks for config at ~/.claude/.mcp.json. You can run it from any directory.

Usage Patterns

Pattern 1: Discover Available Tools

cd .claude/skills/mcp-management/scripts
npm run list-tools
npm run list-prompts
npm run list-resources
# Or directly:
npx tsx cli.ts list-tools
npx tsx cli.ts list-prompts
npx tsx cli.ts list-resources

Pattern 2: LLM-Driven Tool Selection

The LLM reads assets/tools.json and intelligently selects tools. No separate analysis command needed - the LLM's understanding of context and intent is superior to keyword matching.

Pattern 3: Execute MCP Tools

npx tsx cli.ts call-tool memory add '{"key":"name","value":"Alice"}'

Pattern 4: Use with Subagent

In main Claude conversation:

User: "I need to search the web and save results"
Main Agent: [Spawns mcp-manager subagent]
mcp-manager: Discovers brave-search + memory tools, reports back
Main Agent: Uses recommended tools for implementation

Architecture

Main Agent (Claude)
    ↓ (delegates MCP tasks)
mcp-manager Subagent
    ↓ (uses skill)
mcp-management Skill
    ↓ (connects via)
MCP Servers (memory, filesystem, etc.)

Benefits:

  • Main agent context stays clean
  • MCP discovery happens in isolated subagent context
  • Only relevant tool definitions loaded when needed
  • Reduced token usage

File Structure

mcp-management/
├── SKILL.md                    # Skill definition
├── README.md                   # This file
├── scripts/
│   ├── mcp-client.ts          # Core MCP client manager
│   ├── analyze-tools.ts       # Intelligent tool selection
│   ├── cli.ts                 # Command-line interface
│   ├── package.json           # Dependencies
│   ├── tsconfig.json          # TypeScript config
│   └── .env.example           # Environment template
└── references/
    ├── mcp-protocol.md        # MCP protocol reference
    └── configuration.md       # Config guide

Scripts Reference

mcp-client.ts

Core client manager class:

  • Load config from .claude/.mcp.json
  • Connect to multiple MCP servers
  • List/execute tools, prompts, resources
  • Lifecycle management

cli.ts

Command-line interface:

  • list-tools - Show all tools and save to assets/tools.json
  • list-prompts - Show all prompts
  • list-resources - Show all resources
  • call-tool <server> <tool> <json> - Execute tool

Note: Tool analysis is performed by the LLM reading assets/tools.json, which provides better context understanding than algorithmic matching.

Configuration

Environment Variables

Scripts check for variables in this order:

  1. process.env (runtime)
  2. .claude/skills/mcp-management/.env
  3. .claude/skills/.env
  4. .claude/.env

MCP Config Format

{
  "mcpServers": {
    "server-name": {
      "command": "executable",          // Required
      "args": ["arg1", "arg2"],        // Required
      "env": {                          // Optional
        "VAR": "value",
        "API_KEY": "${ENV_VAR}"        // Reference env vars
      }
    }
  }
}

Common MCP Servers

Install with npx:

  • @modelcontextprotocol/server-memory - Key-value storage
  • @modelcontextprotocol/server-filesystem - File operations
  • @modelcontextprotocol/server-brave-search - Web search
  • @modelcontextprotocol/server-puppeteer - Browser automation
  • @modelcontextprotocol/server-fetch - HTTP requests

Integration with mcp-manager Agent

The mcp-manager agent (.claude/agents/mcp-manager.md) uses this skill to:

  1. Discover: Connect to MCP servers, list capabilities
  2. Analyze: Filter relevant tools for tasks
  3. Execute: Call MCP tools on behalf of main agent
  4. Report: Send concise results back to main agent

This architecture keeps main context clean and enables efficient MCP integration.

Troubleshooting

"Config not found"

Ensure .claude/.mcp.json exists and is valid JSON.

"Server connection failed"

Check:

  • Server command is installed (npx packages installed?)
  • Server args are correct
  • Environment variables are set

"Tool not found"

List available tools first:

cd .claude/skills/mcp-management/scripts
npm run list-tools

Resources

License

MIT