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. 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>

- 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> 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>

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}/

</essential_principles> 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

| 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> | 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>

Script	Purpose
setup-python-project.sh	Initialize Python MCP project with uv
setup-typescript-project.sh	Initialize TypeScript MCP project with npm
</scripts_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>

```bash # List servers claude mcp list

Add server (Python)

claude mcp add --transport stdio
--env API_KEY='${API_KEY}'
-- uv --directory ~/Developer/mcp/ run python -m src.server

Add server (TypeScript)

claude mcp add --transport stdio
--env API_KEY='${API_KEY}'
-- node ~/Developer/mcp//build/index.js

Remove server

claude mcp remove

Check logs

tail -f ~/Library/Logs/Claude/mcp-server-.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>

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>