This Claude skill provides a comprehensive framework and best practices for developing high-quality Model Context Protocol (MCP) servers. It guides developers through the full lifecycle of creating robust interfaces that enable Large Language Models to interact seamlessly and securely with external APIs, databases, and local services.

When should I use mcp-builder?

mcp-builder is useful in the following scenarios: • Case 1: Building custom MCP servers to bridge the gap between AI agents and internal enterprise tools or proprietary data sources. • Case 2: Implementing type-safe tool definitions using TypeScript and Zod to ensure reliable, error-free communication between LLMs and external systems. • Case 3: Setting up standardized testing and evaluation pipelines using the MCP Inspector to validate tool performance and response accuracy. • Case 4: Optimizing agentic workflows by applying best practices for tool naming, pagination, and descriptive error handling within the MCP ecosystem.

name	mcp-builder
description	Guide for creating high-quality MCP (Model Context Protocol) servers
version	1.0.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)

Scientific Skill Interleaving

This skill connects to the K-Dense-AI/claude-scientific-skills ecosystem:

Graph Theory

networkx [○] via bicomodule
- Universal graph hub

Bibliography References

general: 734 citations in bib.duckdb

Cat# Integration

This skill maps to Cat# = Comod(P) as a bicomodule in the equipment structure:

Trit: 1 (PLUS)
Home: Prof
Poly Op: ⊗
Kan Role: Adj
Color: #4ECDC4

GF(3) Naturality

The skill participates in triads satisfying:

(-1) + (0) + (+1) ≡ 0 (mod 3)

This ensures compositional coherence in the Cat# equipment structure.

mcp-builder

When & Why to Use This Skill

Use Cases