Mcp Management

MCP Management

Skill for managing and interacting with Model Context Protocol (MCP) servers.

Overview

MCP is an open protocol enabling AI agents to connect to external tools and data sources. This skill provides scripts and utilities to discover, analyze, and execute MCP capabilities from configured servers without polluting the main context window.

Key Benefits:

• Progressive disclosure of MCP capabilities (load only what's needed)
• Intelligent tool/prompt/resource selection based on task requirements
• Multi-server management from single config file
• Context-efficient: subagents handle MCP discovery and execution
• Persistent tool catalog: automatically saves discovered tools to JSON for fast reference

When to Use This Skill

Use this skill when: 1. Discovering MCP Capabilities: Need to list available tools/prompts/resources from configured servers 2. Task-Based Tool Selection: Analyzing which MCP tools are relevant for a specific task 3. Executing MCP Tools: Calling MCP tools programmatically with proper parameter handling 4. MCP Integration: Building or debugging MCP client implementations 5. Context Management: Avoiding context pollution by delegating MCP operations to subagents

Core Capabilities

1. Configuration Management

MCP servers configured in .claude/.mcp.json.

Gemini CLI Integration (recommended): Create symlink to .gemini/settings.json:

mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json

See references/configuration.md and references/gemini-cli-integration.md.

2. Capability Discovery

npx tsx scripts/cli.ts list-tools  # Saves to assets/tools.json
npx tsx scripts/cli.ts list-prompts
npx tsx scripts/cli.ts list-resources

Aggregates capabilities from multiple servers with server identification.

3. Intelligent Tool Analysis

LLM analyzes assets/tools.json directly - better than keyword matching algorithms.

4. Tool Execution

Primary: Gemini CLI (if available)

gemini -y -m gemini-2.5-flash -p "Take a screenshot of https://example.com"

Secondary: Direct Scripts

npx tsx scripts/cli.ts call-tool memory create_entities '{"entities":[...]}'

Fallback: mcp-manager Subagent

See references/gemini-cli-integration.md for complete examples.

Implementation Patterns

Pattern 1: Gemini CLI Auto-Execution (Primary)

Use Gemini CLI for automatic tool discovery and execution. See references/gemini-cli-integration.md for complete guide.

Quick Example:

gemini -y -m gemini-2.5-flash -p "Take a screenshot of https://example.com"

Benefits: Automatic tool discovery, natural language execution, faster than subagent orchestration.

Pattern 2: Subagent-Based Execution (Fallback)

Use mcp-manager agent when Gemini CLI unavailable. Subagent discovers tools, selects relevant ones, executes tasks, reports back.

Benefit: Main context stays clean, only relevant tool definitions loaded when needed.

Pattern 3: LLM-Driven Tool Selection

LLM reads assets/tools.json, intelligently selects relevant tools using context understanding, synonyms, and intent recognition.

Pattern 4: Multi-Server Orchestration

Coordinate tools across multiple servers. Each tool knows its source server for proper routing.

Scripts Reference

scripts/mcp-client.ts

Core MCP client manager class. Handles:

• Config loading from .claude/.mcp.json
• Connecting to multiple MCP servers
• Listing tools/prompts/resources across all servers
• Executing tools with proper error handling
• Connection lifecycle management

scripts/cli.ts

Command-line interface for MCP operations. Commands:

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

Note: list-tools persists complete tool catalog to assets/tools.json with full schemas for fast reference, offline browsing, and version control.

Quick Start

Method 1: Gemini CLI (recommended)

npm install -g gemini-cli
mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json
gemini -y -m gemini-2.5-flash -p "Take a screenshot of https://example.com"

Method 2: Scripts

cd .claude/skills/mcp-management/scripts && npm install
npx tsx cli.ts list-tools  # Saves to assets/tools.json
npx tsx cli.ts call-tool memory create_entities '{"entities":[...]}'

Method 3: mcp-manager Subagent

See references/gemini-cli-integration.md for complete guide.

Technical Details

See references/mcp-protocol.md for:

• JSON-RPC protocol details
• Message types and formats
• Error codes and handling
• Transport mechanisms (stdio, HTTP+SSE)
• Best practices

Integration Strategy

Execution Priority

1. Gemini CLI (Primary): Fast, automatic, intelligent tool selection

• Check: command -v gemini
• Execute: gemini -y -m gemini-2.5-flash -p "<task>"
• Best for: All tasks when available

2. Direct CLI Scripts (Secondary): Manual tool specification

• Use when: Need specific tool/server control
• Execute: npx tsx scripts/cli.ts call-tool <server> <tool> <args>

3. mcp-manager Subagent (Fallback): Context-efficient delegation

• Use when: Gemini unavailable or failed
• Keeps main context clean

Integration with Agents

The mcp-manager agent uses this skill to:

• Check Gemini CLI availability first
• Execute via gemini command if available
• Fallback to direct script execution
• Discover MCP capabilities without loading into main context
• Report results back to main agent

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

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

• MCP Specification
• MCP TypeScript SDK
• Official MCP Servers
• Skill References

License

MIT

MCP Configuration Guide

Configuration File Structure

MCP servers are configured in .claude/.mcp.json:

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

Common Server Configurations

Memory Server

Store and retrieve key-value data:

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

Filesystem Server

File operations with restricted access:

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

Brave Search Server

Web search capabilities:

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
    }
  }
}

Puppeteer Server

Browser automation:

{
  "puppeteer": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
  }
}

Environment Variables

Reference env vars with ${VAR_NAME} syntax:

{
  "api-server": {
    "command": "node",
    "args": ["server.js"],
    "env": {
      "API_KEY": "${MY_API_KEY}",
      "BASE_URL": "${API_BASE_URL}"
    }
  }
}

Configuration Loading Order

Scripts check for config in this order:

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

Validation

Config must:

• Be valid JSON
• Include mcpServers object
• Each server must have command and args
• env is optional but must be object if present

Gemini CLI Integration Guide

Overview

Gemini CLI provides automatic MCP tool discovery and execution via natural language prompts. This is the recommended primary method for executing MCP tools.

Installation

npm install -g gemini-cli

Verify installation:

gemini --version

Configuration

Symlink Setup

Gemini CLI reads MCP servers from .gemini/settings.json. Create a symlink to .claude/.mcp.json:

# Create .gemini directory
mkdir -p .gemini

# Create symlink (Unix/Linux/macOS)
ln -sf .claude/.mcp.json .gemini/settings.json

# Create symlink (Windows - requires admin or developer mode)
mklink .gemini\settings.json .claude\.mcp.json

Security

Add to .gitignore:

.gemini/settings.json

This prevents committing sensitive API keys and server configurations.

Usage

Basic Syntax

gemini [flags] -p "<prompt>"

Essential Flags

• -y: Skip confirmation prompts (auto-approve tool execution)
• -m <model>: Model selection
• gemini-2.5-flash (fast, recommended for MCP)
• gemini-2.5-flash (balanced)
• gemini-pro (high quality)
• -p "<prompt>": Task description

Examples

Screenshot Capture:

gemini -y -m gemini-2.5-flash -p "Take a screenshot of https://www.google.com.vn"

Memory Operations:

gemini -y -m gemini-2.5-flash -p "Remember that Alice is a React developer working on e-commerce projects"

Web Research:

gemini -y -m gemini-2.5-flash -p "Search for latest Next.js 15 features and summarize the top 3"

Multi-Tool Orchestration:

gemini -y -m gemini-2.5-flash -p "Search for Claude AI documentation, take a screenshot of the homepage, and save both to memory"

Browser Automation:

gemini -y -m gemini-2.5-flash -p "Navigate to https://example.com, click the signup button, and take a screenshot"

How It Works

1. Configuration Loading: Reads .gemini/settings.json (symlinked to .claude/.mcp.json) 2. Server Connection: Connects to all configured MCP servers 3. Tool Discovery: Lists all available tools from servers 4. Prompt Analysis: Gemini model analyzes the prompt 5. Tool Selection: Automatically selects relevant tools 6. Execution: Calls tools with appropriate parameters 7. Result Synthesis: Combines tool outputs into coherent response

Advanced Configuration

Trusted Servers (Skip Confirmations)

Edit .claude/.mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "trust": true
    }
  }
}

With trust: true, the -y flag is unnecessary.

Tool Filtering

Limit tool exposure:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "includeTools": ["navigate_page", "screenshot"],
      "excludeTools": ["evaluate_js"]
    }
  }
}

Environment Variables

Use $VAR_NAME syntax for sensitive data:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "$BRAVE_API_KEY"
      }
    }
  }
}

Troubleshooting

Check MCP Status

gemini
> /mcp

Shows:

• Connected servers
• Available tools
• Configuration errors

Verify Symlink

# Unix/Linux/macOS
ls -la .gemini/settings.json

# Windows
dir .gemini\settings.json

Should show symlink pointing to .claude/.mcp.json.

Debug Mode

gemini --debug -p "Take a screenshot"

Shows detailed MCP communication logs.

Comparison with Alternatives

Recommendation: Use Gemini CLI as primary method, fallback to scripts/subagent when unavailable.

Resources

• Gemini CLI Documentation
• MCP Server Configuration
• Tool Reference

Model Context Protocol (MCP) Reference

Protocol Overview

MCP is JSON-RPC 2.0 based protocol for AI-tool integration.

Version: 2025-03-26 Foundation: JSON-RPC 2.0 Architecture: Client-Host-Server

Connection Lifecycle

1. Initialize: Client sends initialize request with capabilities 2. Response: Server responds with its capabilities 3. Handshake: Client sends notifications/initialized 4. Active: Bidirectional messaging 5. Shutdown: Close connections, cleanup

Core Capabilities

Tools (Executable Functions)

Tools are functions that servers expose for execution.

List Tools:

{"method": "tools/list"}

Call Tool:

{
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {}
  }
}

Prompts (Interaction Templates)

Prompts are reusable templates for LLM interactions.

List Prompts:

{"method": "prompts/list"}

Get Prompt:

{
  "method": "prompts/get",
  "params": {
    "name": "prompt_name",
    "arguments": {}
  }
}

Resources (Data Sources)

Resources expose read-only data to clients.

List Resources:

{"method": "resources/list"}

Read Resource:

{
  "method": "resources/read",
  "params": {"uri": "resource://path"}
}

Transport Types

stdio (Local)

Server runs as subprocess. Messages via stdin/stdout.

const transport = new StdioClientTransport({
  command: 'node',
  args: ['server.js']
});

HTTP+SSE (Remote)

POST for requests, GET for server events.

const transport = new StreamableHTTPClientTransport({
  url: 'http://localhost:3000/mcp'
});

Error Codes

• -32700: Parse error
• -32600: Invalid request
• -32601: Method not found
• -32602: Invalid params
• -32603: Internal error
• -32002: Resource not found (MCP-specific)

Best Practices

1. Progressive Disclosure: Load tool definitions on-demand 2. Context Efficiency: Filter data before returning 3. Security: Validate inputs, sanitize outputs 4. Resource Management: Cleanup connections properly 5. Error Handling: Handle all error cases gracefully