mcp-builder

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

Type	Transport	Use Case
stdio	Process pipes	Local custom servers
HTTP	REST	Cloud-hosted servers
SSE	Server-Sent Events	Real-time updates
WebSocket	Bidirectional	Real-time communication

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