name: mcp-builder description: This skill guides building high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services. Use when creating MCP servers, designing tool interfaces, or implementing protocol handlers.

MCP Server Builder

Overview

Build MCP servers that enable LLMs to interact with external services through thoughtfully designed tools.

Key Principle: Don't simply wrap API endpoints—build thoughtful, high-impact workflow tools.

Four-Phase Development

Phase 1: Research & Planning

• Study agent-centric design principles
• Review MCP protocol documentation
• Study target API documentation exhaustively
• Create detailed implementation plan

Phase 2: Implementation

• Set up project structure
• Build core infrastructure (auth, request helpers, formatters)
• Implement tools with JSON Schema validation
• Follow language-specific best practices

Phase 3: Review & Refine

• Code quality review (DRY, consistency, error handling)
• Test safely using evaluation harness
• Verify against quality checklist

Phase 4: Create Evaluations

• Design 10 complex, realistic test questions
• Create XML-formatted evaluation files
• Verify answers independently

Server Types

Tool Design

// Good: Workflow-oriented
async function analyzeAndSummarize(url: string) {
  // Fetches, parses, and summarizes in one call
}

// Avoid: Simple API wrapper
async function fetchPage(url: string) {
  // Just wraps fetch()
}

Implementation Standards

TypeScript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server({
  name: "my-server",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

Python (FastMCP)

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    """Tool description."""
    return result

Best Practices

1. JSON Schema validation on all inputs/outputs
2. Comprehensive error handling with meaningful messages
3. Logging to stderr (stdout reserved for protocol)
4. Security-first - validate inputs, manage sessions
5. Configurable detail levels for context efficiency
6. Tool annotations - mark read-only, destructive, idempotent