# MCP Master

> Use when user asks about MCP, needs to create/configure/debug MCP servers, or explore the MCP ecosystem. Comprehensive MCP knowledge including protocol, development, deployment, and troubleshooting.

- Skill: `kylin-feng/mcp-master` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kylin-feng/mcp-master`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kylin-feng/mcp-master/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: kylin-feng (https://skillmd.com/u/kylin-feng)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kylin-feng/mcp-master

---


# MCP Master Skill

## Overview

Complete MCP (Model Context Protocol) knowledge base covering protocol principles, server development, Hermes integration, and troubleshooting. Companion project at `C:/Users/FengQ/mcp-skill/`.

## When to Use

- User asks "what is MCP" or "how to use MCP"
- Need to create a new MCP server
- Configure Hermes to connect MCP servers
- MCP connection issues
- Evaluate MCP ecosystem and tools

## MCP Core Reference

### Protocol

```
MCP = JSON-RPC 2.0 over stdio/HTTP

4 Primitives:
- Tools:     AI calls external capabilities (actions)
- Resources: AI reads context data (read-only)
- Prompts:   Get preset prompt templates
- Sampling:  Server requests AI generation (reverse call)
```

### Connection Lifecycle

```
1. Client sends initialize → Server returns capabilities
2. Client sends initialized notification
3. Client calls tools/list → Server returns tool list
4. Client calls tools/call repeatedly → Server returns results
5. Disconnect
```

### Hermes Naming Convention

```
mcp_{server_name}_{tool_name}

Examples:
  mcp_filesystem_read_file
  mcp_content_writer_generate_article
  mcp_knowledge_base_kb_search
```

## Hermes Configuration

### Location: `~/.hermes/config.yaml`

### Stdio Server (most common)

```yaml
mcp_servers:
  my_server:
    command: "python"
    args: ["path/to/server.py"]
    env:
      API_KEY: "sk-xxx"
    timeout: 120
    connect_timeout: 60
```

### HTTP Server

```yaml
mcp_servers:
  remote_server:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer token"
```

### Recommended Full Config

```yaml
mcp_servers:
  # From this project
  content_writer:
    command: "python"
    args: ["C:/Users/FengQ/mcp-skill/servers/mcp-content-writer/server.py"]

  knowledge_base:
    command: "python"
    args: ["C:/Users/FengQ/mcp-skill/servers/mcp-knowledge-base/server.py"]
    env:
      MCP_KB_PATH: "C:/Users/FengQ/.hermes/knowledge_base.json"

  research:
    command: "python"
    args: ["C:/Users/FengQ/mcp-skill/servers/mcp-research/server.py"]
```

## MCP Server Development Quickstart

### Minimal Server Structure

```python
# 1. Define tools (name + description + schema + handler)
TOOLS = [{
    "name": "my_tool",
    "description": "What this tool does - AI uses this to decide when to call",
    "inputSchema": {
        "type": "object",
        "properties": {
            "param": {"type": "string", "description": "Parameter description"}
        },
        "required": ["param"]
    }
}]

# 2. Implement handler
def handle_my_tool(args):
    result = do_something(args["param"])
    return {"content": [{"type": "text", "text": result}]}

# 3. MCP protocol handler (see templates/mcp-server-template.py)
```

### Design Principles

1. **One tool, one job** - Fine-grained over monolithic
2. **Description is documentation** - AI uses it to decide when to call
3. **Schema is constraints** - Types, required params, defaults all in schema
4. **Error-friendly** - Return "why failed + how to fix", not raw error codes

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| "MCP SDK not available" | mcp package missing | `pip install mcp` |
| "No MCP servers configured" | No mcp_servers in config | Add config |
| "Failed to connect" | Command not found / path wrong | Check command and args |
| Tools not appearing | Server not started | Check startup logs |
| Timeout | Network/processing slow | Increase timeout config |

### Manual Testing

```bash
# Test MCP server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | python server.py

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | python server.py
```

## Project Resources

| Resource | Path |
|----------|------|
| Research docs | `C:/Users/FengQ/mcp-skill/research/` |
| Content Writer server | `C:/Users/FengQ/mcp-skill/servers/mcp-content-writer/` |
| Knowledge Base server | `C:/Users/FengQ/mcp-skill/servers/mcp-knowledge-base/` |
| Research server | `C:/Users/FengQ/mcp-skill/servers/mcp-research/` |
| Templates | `C:/Users/FengQ/mcp-skill/templates/` |
| User Guide | `C:/Users/FengQ/mcp-skill/docs/guide.md` |

## Checklist

- [ ] Understand 4 MCP primitives (Tools/Resources/Prompts/Sampling)
- [ ] Can configure MCP servers in Hermes
- [ ] Can create a simple MCP server
- [ ] Can troubleshoot basic connection issues
- [ ] Know the MCP ecosystem landscape