Build MCP Server

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

1. Agent-Centric Design First: Study design principles before coding. Tools should enable workflows, not mirror APIs.

2. Research-Driven Planning: Load MCP docs, SDK docs, and exhaustive API documentation before writing code.

3. Evaluation-Based Iteration: Create realistic evaluations early. Let agent feedback drive improvements.

4. Context Optimization: Every response token matters. Default to concise, offer detailed when needed.

5. Actionable Errors: Error messages should teach agents correct usage patterns.

Quick Start

Phase 1: Research and Planning (40% of effort)

1. Study Design Principles: Load design_principles.md to understand agent-centric design
2. Load Protocol Docs: Fetch https://modelcontextprotocol.io/llms-full.txt for MCP specification
3. Study SDK Docs: Load Python or TypeScript SDK documentation from GitHub
4. Study API Exhaustively: Read ALL API documentation, endpoints, authentication, rate limits
5. 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)

1. Setup Project: Create structure following language-specific guide
2. Build Shared Utilities: API helpers, error handlers, formatters BEFORE tools
3. Implement Tools: Use Pydantic (Python) or Zod (TypeScript) for validation
4. 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)

1. Code Quality Review: Check DRY, composability, consistency, type safety
2. Test Build: Verify syntax, imports, build process
3. Quality Checklist: Use language-specific checklist

See workflow.md for complete Phase 3 steps.

Phase 4: Create Evaluations (15% of effort)

1. Understand Purpose: Evaluations test if agents can answer realistic questions using your tools
2. Create 10 Questions: Complex, read-only, independent, verifiable questions
3. Verify Answers: Solve yourself to ensure stability and correctness
4. 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.