mcp-builder

s-hiraoku's avatarfrom s-hiraoku

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 31, 2025
[Developer Tools]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for developing high-quality Model Context Protocol (MCP) servers, enabling seamless integration between LLMs and external services. It guides developers through a structured four-phase lifecycle—Research, Implementation, Review, and Evaluation—to move beyond simple API wrapping toward building high-impact, workflow-oriented agentic tools. By emphasizing JSON Schema validation, security-first design, and standardized transport protocols (stdio, HTTP, SSE, WebSocket), it ensures the creation of robust, production-ready infrastructure for AI agents.

Use Cases

  • Case 1: Developing custom MCP servers to securely connect proprietary enterprise databases or internal APIs to Claude for enhanced data retrieval.
  • Case 2: Designing sophisticated, workflow-oriented tools that combine multiple API calls into single, high-impact actions for more efficient agentic reasoning.
  • Case 3: Implementing standardized protocol handlers in TypeScript or Python (FastMCP) to ensure cross-platform compatibility and reliable tool execution.
  • Case 4: Creating rigorous automated evaluation suites with XML-formatted test cases to verify the accuracy and safety of tool-use interactions before deployment.
namemcp-builder
descriptionThis 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