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

- Skill: `edorabma9304/mcp-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add edorabma9304/mcp-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/edorabma9304/mcp-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: edorabma9304 (https://skillmd.com/u/edorabma9304)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/edorabma9304/mcp-builder

---


# MCP Server Development Guide

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

## Four-Phase Workflow

### Phase 1: Deep Research and Planning

#### MCP Design Principles
- Balance API coverage with workflow tools
- Clear, descriptive tool names with consistent prefixes (`github_create_issue`, `github_list_repos`)
- Concise tool descriptions with pagination support
- Actionable error messages with specific suggestions

#### Study MCP Protocol
Start with: `https://modelcontextprotocol.io/sitemap.xml`
Key pages: specification overview, transport mechanisms, tool/resource/prompt definitions.

#### Recommended Stack
- **Language**: TypeScript (best SDK support)
- **Transport**: Streamable HTTP for remote servers, stdio for local

#### Plan Implementation
- Review service's API documentation
- List endpoints to implement, starting with most common operations

### Phase 2: Implementation

#### Project Structure
See language-specific guides:
- TypeScript: project structure, package.json, tsconfig.json
- Python: module organization, dependencies

#### Core Infrastructure
- API client with authentication
- Error handling helpers
- Response formatting (JSON/Markdown)
- Pagination support

#### Tool Implementation

For each tool define:
- **Input Schema**: Zod (TS) or Pydantic (Python) with constraints and descriptions
- **Output Schema**: `outputSchema` for structured data
- **Tool Description**: Concise summary + parameter descriptions
- **Implementation**: Async/await, proper error handling, pagination
- **Annotations**: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`

### Phase 3: Review and Test

#### Code Quality
- No duplicated code (DRY)
- Consistent error handling
- Full type coverage
- Clear tool descriptions

#### Build and Test
- TypeScript: `npm run build` + MCP Inspector (`npx @modelcontextprotocol/inspector`)
- Python: `python -m py_compile` + MCP Inspector

### Phase 4: Create Evaluations

Create 10 complex, realistic questions testing LLM usage of your server.

Requirements:
- **Independent**: Not dependent on other questions
- **Read-only**: Only non-destructive operations
- **Complex**: Requiring multiple tool calls
- **Realistic**: Based on real use cases
- **Verifiable**: Single, clear answer
- **Stable**: Answer won't change over time

Output format:
```xml
<evaluation>
  <qa_pair>
    <question>Your question here</question>
    <answer>Expected answer</answer>
  </qa_pair>
</evaluation>
```