MCP Server Development Guide
Overview
Build high-quality MCP (Model Context Protocol) servers that enable LLMs to accomplish real-world tasks through well-designed tools. Quality is measured not by API coverage, but by how effectively agents can use your tools to complete realistic workflows.
Core insight: MCP servers expose tools for AI agents, not human users. Design for agent constraints (limited context, no visual UI, workflow-oriented) rather than human convenience.
When to Use This Skill
Activate when:
- Building MCP servers for external API integration
- Adding tools to existing MCP servers
- Improving MCP server tool design for better agent usability
- Creating evaluations to test MCP server effectiveness
- Debugging why agents struggle with your MCP tools
Language Support:
- Python: FastMCP framework (recommended for rapid development)
- Node/TypeScript: MCP SDK (recommended for production services)
The Iron Law
DESIGN FOR AGENTS, NOT HUMANS
Every tool must optimize for:
- Context efficiency (agents have limited tokens)
- Workflow completion (not just API calls)
- Actionable errors (guide agents to success)
- Natural task subdivision (how agents think)
If your tools are just thin API wrappers, you're violating the Iron Law.
Core Principles
Agent-Centric Design First: Study design principles before coding. Tools should enable workflows, not mirror APIs.
Research-Driven Planning: Load MCP docs, SDK docs, and exhaustive API documentation before writing code.
Evaluation-Based Iteration: Create realistic evaluations early. Let agent feedback drive improvements.
Context Optimization: Every response token matters. Default to concise, offer detailed when needed.
Actionable Errors: Error messages should teach agents correct usage patterns.
Quick Start
Phase 1: Research and Planning (40% of effort)
- Study Design Principles: Load design_principles.md to understand agent-centric design
- Load Protocol Docs: Fetch
https://modelcontextprotocol.io/llms-full.txt for MCP specification
- Study SDK Docs: Load Python or TypeScript SDK documentation from GitHub
- Study API Exhaustively: Read ALL API documentation, endpoints, authentication, rate limits
- Create Implementation Plan: Define tools, shared utilities, pagination strategy, error handling
See workflow.md for complete Phase 1 steps.
Phase 2: Implementation (30% of effort)
- Setup Project: Create structure following language-specific guide
- Build Shared Utilities: API helpers, error handlers, formatters BEFORE tools
- Implement Tools: Use Pydantic (Python) or Zod (TypeScript) for validation
- Follow Best Practices: Load language-specific guide for patterns
See workflow.md for complete Phase 2 steps and language guides.
Phase 3: Review and Refine (15% of effort)
- Code Quality Review: Check DRY, composability, consistency, type safety
- Test Build: Verify syntax, imports, build process
- Quality Checklist: Use language-specific checklist
See workflow.md for complete Phase 3 steps.
Phase 4: Create Evaluations (15% of effort)
- Understand Purpose: Evaluations test if agents can answer realistic questions using your tools
- Create 10 Questions: Complex, read-only, independent, verifiable questions
- Verify Answers: Solve yourself to ensure stability and correctness
- Run Evaluation: Use provided scripts to test agent effectiveness
See evaluation.md for complete evaluation guidelines.
Navigation
Core Design and Workflow
🎯 Design Principles - Agent-centric design philosophy: workflows over APIs, context optimization, actionable errors, natural task subdivision. Read FIRST before implementation.
🔄 Complete Workflow - Detailed 4-phase development process with step-by-step instructions, decision trees, and when to load each reference file.
Universal MCP Guidelines
- 📋 MCP Best Practices - Naming conventions, response formats, pagination, character limits, security, tool annotations, error handling. Applies to all MCP servers.
Language-Specific Implementation
🐍 Python Implementation - FastMCP patterns, Pydantic validation, async/await, complete examples, quality checklist. Load during Phase 2 for Python servers.
⚡ TypeScript Implementation - MCP SDK patterns, Zod validation, project structure, complete examples, quality checklist. Load during Phase 2 for TypeScript servers.
Evaluation and Testing
- ✅ Evaluation Guide - Creating realistic questions, answer verification, XML format, running evaluations, interpreting results. Load during Phase 4.
Key Reminders
- Research First: Spend 40% of time researching before coding
- Agent-Centric: Design for AI workflows, not API completeness
- Context Efficient: Every token counts - default concise, offer detailed
- Actionable Errors: Guide agents to correct usage
- Shared Utilities: Extract common code - avoid duplication
- Evaluation-Driven: Create evals early, iterate based on feedback
- MCP Servers Block: Never run servers directly - use evaluation harness or tmux
Red Flags - STOP
If you catch yourself:
- "Just wrapping these API endpoints directly"
- "Returning all available data fields"
- "Error message just says what failed" (not how to fix)
- Starting implementation without reading design principles
- Coding before loading MCP protocol documentation
- Creating tools without knowing agent use cases
- Skipping evaluation creation
- Running
python server.py directly (will hang forever)
ALL of these mean: STOP. Return to design principles and workflow.
Integration with Other Skills
- systematic-debugging: Debug MCP server issues methodically
- test-driven-development: Create failing tests before implementation
- verification-before-completion: Verify build succeeds before claiming completion
- defense-in-depth: Add input validation at multiple layers
Real-World Impact
From MCP server development experience:
- Well-designed servers: 80-90% task completion rate by agents
- API wrapper approach: 30-40% task completion rate
- Context-optimized responses: 3x more information in same token budget
- Actionable errors: 60% reduction in agent retry attempts
- Evaluation-driven iteration: 2-3x improvement in agent success rate
Remember: The quality of an MCP server is measured by how well it enables LLMs to accomplish realistic tasks, not by how comprehensively it wraps an API.
1---2name: build-mcp-server-23description: Create high-quality MCP servers that enable LLMs to effectively interact with external services. Use when building MCP integrations for APIs or services in Python (FastMCP) or Node/TypeScript (MCP SDK).4license: Complete terms in LICENSE.txt5progressive_disclosure:6 entry_point:7 summary: "Build agent-friendly MCP servers through research-driven design, thoughtful implementation, and evaluation-based iteration"8 when_to_use: "When integrating external APIs/services via MCP protocol. Prioritize agent workflows over API wrappers, optimize for context efficiency, design actionable errors."9 quick_start: "1. Research protocol & API docs 2. Plan agent-centric tools 3. Implement with validation 4. Create evaluations 5. Iterate based on agent feedback"10 references:11 - design_principles.md12 - workflow.md13 - mcp_best_practices.md14 - python_mcp_server.md15 - node_mcp_server.md16 - evaluation.md17effort: high18metadata:19 source: https://skillmd.com/skills/bobmatnyc/build-mcp-server-220---2122# MCP Server Development Guide2324## Overview2526Build high-quality MCP (Model Context Protocol) servers that enable LLMs to accomplish real-world tasks through well-designed tools. Quality is measured not by API coverage, but by how effectively agents can use your tools to complete realistic workflows.2728**Core insight:** MCP servers expose tools for AI agents, not human users. Design for agent constraints (limited context, no visual UI, workflow-oriented) rather than human convenience.2930## When to Use This Skill3132Activate when:33- Building MCP servers for external API integration34- Adding tools to existing MCP servers35- Improving MCP server tool design for better agent usability36- Creating evaluations to test MCP server effectiveness37- Debugging why agents struggle with your MCP tools3839**Language Support:**40- Python: FastMCP framework (recommended for rapid development)41- Node/TypeScript: MCP SDK (recommended for production services)4243## The Iron Law4445```46DESIGN FOR AGENTS, NOT HUMANS4748Every tool must optimize for:49- Context efficiency (agents have limited tokens)50- Workflow completion (not just API calls)51- Actionable errors (guide agents to success)52- Natural task subdivision (how agents think)53```5455If your tools are just thin API wrappers, you're violating the Iron Law.5657## Core Principles58591. **Agent-Centric Design First**: Study design principles before coding. Tools should enable workflows, not mirror APIs.60612. **Research-Driven Planning**: Load MCP docs, SDK docs, and exhaustive API documentation before writing code.62633. **Evaluation-Based Iteration**: Create realistic evaluations early. Let agent feedback drive improvements.64654. **Context Optimization**: Every response token matters. Default to concise, offer detailed when needed.66675. **Actionable Errors**: Error messages should teach agents correct usage patterns.6869## Quick Start7071### Phase 1: Research and Planning (40% of effort)721. **Study Design Principles**: Load [design_principles.md](./reference/design_principles.md) to understand agent-centric design732. **Load Protocol Docs**: Fetch `https://modelcontextprotocol.io/llms-full.txt` for MCP specification743. **Study SDK Docs**: Load Python or TypeScript SDK documentation from GitHub754. **Study API Exhaustively**: Read ALL API documentation, endpoints, authentication, rate limits765. **Create Implementation Plan**: Define tools, shared utilities, pagination strategy, error handling7778See [workflow.md](./reference/workflow.md) for complete Phase 1 steps.7980### Phase 2: Implementation (30% of effort)811. **Setup Project**: Create structure following language-specific guide822. **Build Shared Utilities**: API helpers, error handlers, formatters BEFORE tools833. **Implement Tools**: Use Pydantic (Python) or Zod (TypeScript) for validation844. **Follow Best Practices**: Load language-specific guide for patterns8586See [workflow.md](./reference/workflow.md) for complete Phase 2 steps and language guides.8788### Phase 3: Review and Refine (15% of effort)891. **Code Quality Review**: Check DRY, composability, consistency, type safety902. **Test Build**: Verify syntax, imports, build process913. **Quality Checklist**: Use language-specific checklist9293See [workflow.md](./reference/workflow.md) for complete Phase 3 steps.9495### Phase 4: Create Evaluations (15% of effort)961. **Understand Purpose**: Evaluations test if agents can answer realistic questions using your tools972. **Create 10 Questions**: Complex, read-only, independent, verifiable questions983. **Verify Answers**: Solve yourself to ensure stability and correctness994. **Run Evaluation**: Use provided scripts to test agent effectiveness100101See [evaluation.md](./reference/evaluation.md) for complete evaluation guidelines.102103## Navigation104105### Core Design and Workflow106- **[🎯 Design Principles](./reference/design_principles.md)** - Agent-centric design philosophy: workflows over APIs, context optimization, actionable errors, natural task subdivision. Read FIRST before implementation.107108- **[🔄 Complete Workflow](./reference/workflow.md)** - Detailed 4-phase development process with step-by-step instructions, decision trees, and when to load each reference file.109110### Universal MCP Guidelines111- **[📋 MCP Best Practices](./reference/mcp_best_practices.md)** - Naming conventions, response formats, pagination, character limits, security, tool annotations, error handling. Applies to all MCP servers.112113### Language-Specific Implementation114- **[🐍 Python Implementation](./reference/python_mcp_server.md)** - FastMCP patterns, Pydantic validation, async/await, complete examples, quality checklist. Load during Phase 2 for Python servers.115116- **[⚡ TypeScript Implementation](./reference/node_mcp_server.md)** - MCP SDK patterns, Zod validation, project structure, complete examples, quality checklist. Load during Phase 2 for TypeScript servers.117118### Evaluation and Testing119- **[✅ Evaluation Guide](./reference/evaluation.md)** - Creating realistic questions, answer verification, XML format, running evaluations, interpreting results. Load during Phase 4.120121## Key Reminders122123- **Research First**: Spend 40% of time researching before coding124- **Agent-Centric**: Design for AI workflows, not API completeness125- **Context Efficient**: Every token counts - default concise, offer detailed126- **Actionable Errors**: Guide agents to correct usage127- **Shared Utilities**: Extract common code - avoid duplication128- **Evaluation-Driven**: Create evals early, iterate based on feedback129- **MCP Servers Block**: Never run servers directly - use evaluation harness or tmux130131## Red Flags - STOP132133If you catch yourself:134- "Just wrapping these API endpoints directly"135- "Returning all available data fields"136- "Error message just says what failed" (not how to fix)137- Starting implementation without reading design principles138- Coding before loading MCP protocol documentation139- Creating tools without knowing agent use cases140- Skipping evaluation creation141- Running `python server.py` directly (will hang forever)142143**ALL of these mean: STOP. Return to design principles and workflow.**144145## Integration with Other Skills146147- **systematic-debugging**: Debug MCP server issues methodically148- **test-driven-development**: Create failing tests before implementation149- **verification-before-completion**: Verify build succeeds before claiming completion150- **defense-in-depth**: Add input validation at multiple layers151152## Real-World Impact153154From MCP server development experience:155- Well-designed servers: 80-90% task completion rate by agents156- API wrapper approach: 30-40% task completion rate157- Context-optimized responses: 3x more information in same token budget158- Actionable errors: 60% reduction in agent retry attempts159- Evaluation-driven iteration: 2-3x improvement in agent success rate160161---162163**Remember:** The quality of an MCP server is measured by how well it enables LLMs to accomplish realistic tasks, not by how comprehensively it wraps an API.