mcp-builder

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).

⭐327stars🔀27forks📁View on GitHub🕐Updated Dec 26, 2025⬇️1downloads

When & Why to Use This Skill

The MCP Builder skill is a comprehensive development framework and guide designed to help engineers create high-quality Model Context Protocol (MCP) servers. It enables Large Language Models (LLMs) to interact seamlessly with external services and APIs through standardized tool definitions. By providing structured workflows for both TypeScript and Python, it ensures that developers can build robust, scalable, and well-documented integrations that enhance the functional capabilities of AI agents.

Use Cases

  • 1. Custom API Integration: Rapidly develop MCP servers to connect LLMs with internal proprietary databases or third-party SaaS platforms like GitHub, Slack, and Jira using standardized protocols.
  • 2. Standardizing Agentic Workflows: Implement consistent tool naming conventions and rigorous schema validation (Zod/Pydantic) to improve the reliability and accuracy of LLM tool-calling.
  • 3. Cross-Platform Development: Leverage specialized implementation patterns for both Node.js/TypeScript (MCP SDK) and Python (FastMCP) to integrate AI capabilities into existing tech stacks.
  • 4. Automated Testing and Evaluation: Use the built-in evaluation framework to create complex QA pairs and utilize the MCP Inspector for debugging, ensuring high-performance tool outputs before production deployment.
namemcp-builder
descriptionGuide 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).
sourceanthropics/skills
licenseApache-2.0

MCP Server Development Guide

Create MCP servers that enable LLMs to interact with external services through well-designed tools.

High-Level Workflow

Phase 1: Research and Planning

Understand Modern MCP Design:

  • Balance comprehensive API coverage with specialized workflow tools
  • Use clear, descriptive tool names with consistent prefixes (e.g., github_create_issue)
  • Design tools that return focused, relevant data
  • Provide actionable error messages

Study MCP Protocol:

  • Start with sitemap: https://modelcontextprotocol.io/sitemap.xml
  • Key pages: specification, transport mechanisms, tool definitions

Phase 2: Implementation

Recommended Stack:

  • Language: TypeScript (best SDK support)
  • Transport: Streamable HTTP for remote, stdio for local

Project Structure:

my-mcp-server/
├── src/
│   ├── index.ts      # Server entry point
│   ├── tools/        # Tool implementations
│   └── utils/        # Shared utilities
├── package.json
└── tsconfig.json

Tool Implementation Pattern:

server.registerTool({
  name: "github_create_issue",
  description: "Create a new GitHub issue",
  inputSchema: z.object({
    repo: z.string().describe("Repository name (owner/repo)"),
    title: z.string().describe("Issue title"),
    body: z.string().optional().describe("Issue body")
  }),
  outputSchema: z.object({
    id: z.number(),
    url: z.string()
  }),
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false
  },
  handler: async (input) => {
    // Implementation
    return { id: 123, url: "https://..." };
  }
});

Phase 3: Test

# TypeScript
npm run build
npx @modelcontextprotocol/inspector

# Python
python -m py_compile your_server.py

Phase 4: Create Evaluations

Create 10 complex, realistic questions to test your MCP server:

<evaluation>
  <qa_pair>
    <question>Find all open issues labeled 'bug' in the repo</question>
    <answer>5</answer>
  </qa_pair>
</evaluation>

Tool Design Best Practices

  • Use Zod (TS) or Pydantic (Python) for schemas
  • Include constraints and examples in field descriptions
  • Define outputSchema for structured data
  • Support pagination where applicable
  • Add tool annotations (readOnly, destructive, idempotent)