SuperCharged-Claude-Code-Upgrade/skills/mcp-client/skill.md

MCP Client

Auto-invoke: When user needs to integrate external tools, APIs, or services via the Model Context Protocol.

Description: MCP (Model Context Protocol) client for dynamic tool discovery and integration. Supports 100+ pre-built integrations through standardized protocol communication.

Core Capabilities

1. MCP Server Connection

• Connect to MCP servers via stdio, HTTP, or WebSocket
• Handshake and protocol negotiation
• Tool discovery and listing
• Capability exchange

2. Dynamic Tool Invocation

• Call tools on connected MCP servers
• Pass structured arguments
• Receive structured results
• Handle streaming responses

3. Tool Management

• Register/unregister servers
• Cache tool definitions
• Monitor server health
• Auto-reconnect on failure

MCP Servers to Support

Official MCP Servers

@modelcontextprotocol/server-filesystem:
  description: "File system operations"
  tools: [read_file, write_file, list_directory, search_files]

@modelcontextprotocol/server-github:
  description: "GitHub integration"
  tools: [create_issue, list_prs, get_file, search_repos]

@modelcontextprotocol/server-slack:
  description: "Slack messaging"
  tools: [send_message, list_channels, get_history]

@modelcontextprotocol/server-postgres:
  description: "PostgreSQL database"
  tools: [query, list_tables, execute_sql]

@modelcontextprotocol/server-brave-search:
  description: "Web search"
  tools: [search, fetch_page]

Community Servers

@agent-protocol/server-memory:
  description: "Persistent memory storage"
  tools: [store, retrieve, search, clear]

@agent-protocol/server-code-analysis:
  description: "Static code analysis"
  tools: [analyze complexity, find patterns, detect smells]

When to Use

Activate when:

• User needs to integrate external services
• User requests API integrations
• User needs database access
• User wants web search/data fetching
• User needs file operations beyond current directory

Configuration

MCP Servers Config

# ~/.claude/mcp/servers.yaml
servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
    
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
      
  postgres:
    command: python
    args: ["-m", "mcp_server_postgres"]
    env:
      POSTGRES_CONNECTION_STRING: "${DATABASE_URL}"

Dynamic Server Discovery

# ~/.claude/mcp/registry.yaml
registry:
  - name: filesystem
    npm: "@modelcontextprotocol/server-filesystem"
    auto_install: true
    
  - name: github
    npm: "@modelcontextprotocol/server-github"
    env_required: ["GITHUB_TOKEN"]

Usage Patterns

Pattern 1: Direct Tool Call

# Call tool on MCP server
result = await mcp_client.call_tool(
    server_name="github",
    tool_name="create_issue",
    arguments={
        "repo": "owner/repo",
        "title": "Bug found",
        "body": "Description"
    }
)

Pattern 2: Tool Discovery

# List available tools
tools = await mcp_client.list_tools("github")
# Returns: [
#   {"name": "create_issue", "description": "..."},
#   {"name": "list_prs", "description": "..."}
# ]

Pattern 3: Server Management

# Connect to server
await mcp_client.connect("filesystem")

# Check health
health = await mcp_client.health_check("filesystem")

# Disconnect
await mcp_client.disconnect("filesystem")

Integration with Claude Code

Hook Integration

# ~/.claude/hooks/mcp-loader.sh
# Load MCP servers on session start

python3 << 'PYTHON'
import asyncio
from claude_mcp import Client

async def load_servers():
    client = Client()
    await client.load_from_config("~/.claude/mcp/servers.yaml")
    return client.list_tools()

tools = asyncio.run(load_servers())
print(f"Loaded {len(tools)} MCP tools")
PYTHON

Skill Integration

# Auto-inject MCP tools into available tools
mcp_tools = mcp_client.get_all_tools()
available_tools.extend(mcp_tools)

Commands to Create

# List MCP servers
~/.claude/mcp/list-servers.sh

# Connect to server
~/.claude/mcp/connect.sh <server-name>

# Call tool
~/.claude/mcp/call.sh <server> <tool> <args-json>

# Disconnect server
~/.claude/mcp/disconnect.sh <server-name>

# Show server logs
~/.claude/mcp/logs.sh <server-name>

Tool Schema

Each MCP tool provides:

{
  "name": "tool_name",
  "description": "What this tool does",
  "inputSchema": {
    "type": "object",
    "properties": {
      "param1": {"type": "string", "description": "..."}
    },
    "required": ["param1"]
  }
}

Error Handling

Connection Failures

• Retry with exponential backoff
• Fall back to cached tool definitions
• Notify user of unavailable tools

Tool Execution Errors

• Parse error messages from server
• Suggest fixes based on error type
• Offer retry with corrected arguments

Protocol Mismatches

• Log protocol version mismatches
• Attempt to negotiate compatible version
• Warn user of degraded functionality

Security

Sandboxing

• Run servers in separate processes
• Restrict file system access
• Isolate environment variables

Credential Management

• Load credentials from env vars
• Never log sensitive data
• Rotate tokens automatically

Permission Checks

• Verify tool permissions before call
• Require user approval for dangerous ops
• Audit all tool invocations

Performance

Connection Pooling

• Reuse server connections
• Keep idle connections alive
• Limit concurrent connections

Caching

• Cache tool definitions
• Cache server capabilities
• Invalidate on server restart

Monitoring

• Track tool call latency
• Monitor server health
• Alert on degradation

Example Interactions

Example 1: GitHub Integration

User: "Create a GitHub issue for this bug"

[Connect to github MCP server]
[Tool: create_issue]
Arguments: {
  repo: "owner/repo",
  title: "Bug in authentication",
  body: "Steps to reproduce..."
}

Result: Issue #123 created
URL: https://github.com/owner/repo/issues/123

Example 2: Database Query

User: "Show me all users created today"

[Connect to postgres MCP server]
[Tool: execute_sql]
Arguments: {
  query: "SELECT * FROM users WHERE created_at > CURRENT_DATE"
}

Result: [
  {id: 1, name: "Alice", email: "alice@example.com"},
  {id: 2, name: "Bob", email: "bob@example.com"}
]

Example 3: Web Search

User: "Search for recent Claude Code updates"

[Connect to brave-search MCP server]
[Tool: search]
Arguments: {
  query: "Claude Code CLI latest features"
}

Result: [
  {
    title: "Claude Code 2.0 Released",
    url: "https://...",
    snippet: "..."
  }
]

Troubleshooting

Server Won't Start

# Check server logs
~/.claude/mcp/logs.sh <server-name>

# Verify installation
which <server-command>

# Test manually
<server-command> --version

Tool Not Found

# List available tools
~/.claude/mcp/list-tools.sh <server-name>

# Refresh tool cache
~/.claude/mcp/refresh.sh

Connection Timeout

# Increase timeout
export MCP_TIMEOUT=30

# Check network
ping <server-host>

# Verify credentials
echo $GITHUB_TOKEN

Dependencies

# Core MCP client
pip install mcp

# Common servers
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-github
npm install -g @modelcontextprotocol/server-postgres

---

Remember: MCP unlocks a universe of external tools and integrations while maintaining a clean, standardized interface.