create-mcp-servers

What this skill does

<objective>
MCP servers extend Claude's capabilities by exposing tools, resources, and prompts. This skill guides creation of production-ready MCP servers with API integrations, OAuth authentication, response optimization, and proper installation in Claude Code and Claude Desktop.
</objective>

<essential_principles>

<the_5_rules>
Every MCP server must follow these:

1. **Never Hardcode Secrets** - Use `${VAR}` expansion in configs, environment variables in code
2. **Use `cwd` Property** - Isolates dependencies (not `--cwd` in args)
3. **Always Absolute Paths** - `which uv` to find paths, never relative
4. **One Server Per Directory** - `~/Developer/mcp/{server-name}/`
5. **Use `uv` for Python** - Better than pip, handles venvs automatically
</the_5_rules>

<security_checklist>
- Never ask user to paste secrets into chat
- Always use environment variables for credentials
- Use ${VAR} expansion in configs
- Provide exact commands for user to run in terminal
- Verify environment variable existence without showing values
- Never hardcode API keys in code or configs
</security_checklist>

<architecture_decision>
Operation count determines architecture:

- **1-2 operations** → Traditional pattern (flat tools)
- **3+ operations** → On-demand discovery pattern (meta-tools)

Traditional: Each operation is a separate tool
On-demand: 4 meta-tools (discover, get_schema, execute, continue) + operations.json
</architecture_decision>

<context>
MCP servers expose:
- **Tools**: Functions Claude can call (API requests, file operations, calculations)
- **Resources**: Data Claude can read (files, database records, API responses)
- **Prompts**: Reusable prompt templates with arguments

Standard location: `~/Developer/mcp/{server-name}/`
</context>

</essential_principles>

<routing>
Based on user intent, route to appropriate workflow:

**No context provided** (skill invoked without description):
Use AskUserQuestion:
- header: "Mode"
- question: "What would you like to do?"
- options:
  - "Create a new MCP server" → workflows/create-new-server.md
  - "Update an existing MCP server" → workflows/update-existing-server.md
  - "Troubleshoot a server" → workflows/troubleshoot-server.md

**Context provided** (user described what they want):
Route directly to workflows/create-new-server.md
</routing>

<workflows_index>
| Workflow | Purpose |
|----------|---------|
| create-new-server.md | Full 8-step workflow from intake to verification |
| update-existing-server.md | Modify or extend an existing server |
| troubleshoot-server.md | Diagnose and fix connection/runtime issues |
</workflows_index>

<templates_index>
| Template | Purpose |
|----------|---------|
| python-server.py | Traditional pattern starter for Python |
| typescript-server.ts | Traditional pattern starter for TypeScript |
| operations.json | On-demand discovery operations definition |
</templates_index>

<scripts_index>
| Script | Purpose |
|--------|---------|
| setup-python-project.sh | Initialize Python MCP project with uv |
| setup-typescript-project.sh | Initialize TypeScript MCP project with npm |
</scripts_index>

<references_index>
**Core workflow:**
- creation-workflow.md - Complete step-by-step with exact commands

**Architecture patterns:**
- traditional-pattern.md - For 1-2 operations (flat tools)
- large-api-pattern.md - For 3+ operations (on-demand discovery)

**Language-specific:**
- python-implementation.md - Async patterns, type hints
- typescript-implementation.md - Type safety, SDK features

**Advanced topics:**
- oauth-implementation.md - OAuth with stdio isolation
- response-optimization.md - Field truncation, pagination
- tools-and-resources.md - Resources API, prompts, streaming
- testing-and-deployment.md - Unit tests, packaging, publishing
- validation-checkpoints.md - All validation checks
- adaptive-questioning-guide.md - Question templates for intake
- api-research-template.md - API research document format
</references_index>

<quick_reference>
```bash
# List servers
claude mcp list

# Add server (Python)
claude mcp add --transport stdio <name> \
  --env API_KEY='${API_KEY}' \
  -- uv --directory ~/Developer/mcp/<name> run python -m src.server

# Add server (TypeScript)
claude mcp add --transport stdio <name> \
  --env API_KEY='${API_KEY}' \
  -- node ~/Developer/mcp/<name>/build/index.js

# Remove server
claude mcp remove <name>

# Check logs
tail -f ~/Library/Logs/Claude/mcp-server-<name>.log

# Find paths
which uv && which node && which python
```
</quick_reference>

<troubleshooting_quick>
**Server not appearing:** Check `claude mcp list`, verify config in `~/.claude/settings.json`

**"command not found":** Use absolute paths from `which uv` / `which node`

**Environment variable not found:**
```bash
echo $MY_API_KEY  # Check if set
echo 'export MY_API_KEY="value"' >> ~/.zshrc && source ~/.zshrc
```

**Secrets visible in conversation:** STOP. Delete conversation. Rotate credentials. Never paste secrets in chat.

Full troubleshooting: workflows/troubleshoot-server.md
</troubleshooting_quick>

<success_criteria>
A production-ready MCP server has:
- Valid configuration in Claude Code (`claude mcp list` shows ✓ Connected)
- Valid configuration in Claude Desktop config
- Environment variables set securely in ~/.zshrc
- Architecture matches operation count
- OAuth stdio isolation if applicable
- Response optimization for list/search operations
- All validation checkpoints passed
- No errors in logs
</success_criteria>