/mcp-builder

name: mcp-builder
description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
license: Complete terms in LICENSE.txt

MCP Server Development Guide

Overview

To create high-quality MCP (Model Context Protocol) servers that enable LLMs to effectively interact with external services, use this skill. An MCP server provides tools that allow LLMs to access external services and APIs. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks using the tools provided.

---

Process

🚀 High-Level Workflow

Creating a high-quality MCP server involves four main phases:

Phase 1: Deep Research and Planning

1.1 Understand Agent-Centric Design Principles

Before diving into implementation, understand how to design tools for AI agents by reviewing these principles:

**Build for Workflows, Not Just API Endpoints:**

• Don't simply wrap existing API endpoints - build thoughtful, high-impact workflow tools
• Consolidate related operations (e.g., `schedule_event` that both checks availability and creates event)
• Focus on tools that enable complete tasks, not just individual API calls
• Consider what workflows agents actually need to accomplish

**Optimize for Limited Context:**

• Agents have constrained context windows - make every token count
• Return high-signal information, not exhaustive data dumps
• Provide "concise" vs "detailed" response format options
• Default to human-readable identifiers over technical codes (names over IDs)
• Consider the agent's context budget as a scarce resource

**Design Actionable Error Messages:**

• Error messages should guide agents toward correct usage patterns
• Suggest specific next steps: "Try using filter='active_only' to reduce results"
• Make errors educational, not just diagnostic
• Help agents learn proper tool usage through clear feedback

**Follow Natural Task Subdivisions:**

• Tool names should reflect how humans think about tasks
• Group related tools with consistent prefixes for discoverability
• Design tools around natural workflows, not just API structure

**Use Evaluation-Driven Development:**

• Create realistic evaluation scenarios early
• Let agent feedback drive tool improvements
• Prototype quickly and iterate based on actual agent performance

1.3 Study MCP Protocol Documentation

**Fetch the latest MCP protocol documentation:**

Use WebFetch to load: `https://modelcontextprotocol.io/llms-full.txt`

This comprehensive document contains the complete MCP specification and guidelines.

1.4 Study Framework Documentation

**Load and read the following reference files:**

• **MCP Best Practices**: [📋 View Best Practices](./reference/mcp_best_practices.md) - Core guidelines for all MCP servers

**For Python implementations, also load:**

• **Python SDK Documentation**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
• [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Python-specific best practices and examples

**For Node/TypeScript implementations, also load:**

• **TypeScript SDK Documentation**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
• [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Node/TypeScript-specific best practices and examples

1.5 Exhaustively Study API Documentation

To integrate a service, read through **ALL** available API documentation:

• Official API reference documentation
• Authentication and authorization requirements
• Rate limiting and pagination patterns
• Error responses and status codes
• Available endpoints and their parameters
• Data models and schemas

**To gather comprehensive information, use web search and the WebFetch tool as needed.**

1.6 Create a Comprehensive Implementation Plan

Based on your research, create a detailed plan that includes:

**Tool Selection:**

• List the most valuable endpoints/operations to implement
• Prioritize tools that enable the most common and important use cases
• Consider which tools work together to enable complex workflows

**Shared Utilities and Helpers:**

• Identify common API request patterns
• Plan pagination helpers
• Design filtering and formatting utilities
• Plan error handling strategies

**Input/Output Design:**

• Define input validation models (Pydantic for Python, Zod for TypeScript)
• Design consistent response formats (e.g., JSON or Markdown), and configurable levels of detail (e.g., Detailed or Concise)
• Plan for large-scale usage (thousands of users/resources)
• Implement character limits and truncation strategies (e.g., 25,000 tokens)

**Error Handling Strategy:**

• Plan graceful failure modes
• Design clear, actionable, LLM-friendly, natural language error messages which prompt further action
• Consider rate limiting and timeout scenarios
• Handle authentication and authorization errors

---

Phase 2: Implementation

Now that you have a comprehensive plan, begin implementation following language-specific best practices.

2.1 Set Up Project Structure

**For Python:**

• Create a single `.py` file or organize into modules if complex (see [🐍 Python Guide](./reference/python_mcp_server.md))
• Use the MCP Python SDK for tool registration
• Define Pydantic models for input validation

**For Node/TypeScript:**

• Create proper project structure (see [⚡ TypeScript Guide](./reference/node_mcp_server.md))
• Set up `package.json` and `tsconfig.json`
• Use MCP TypeScript SDK
• Define Zod schemas for input validation

2.2 Implement Core Infrastructure First

**To begin implementation, create shared utilities before implementing tools:**

• API request helper functions
• Error handling utilities