# MCP Builder

> MCP Builder

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

---

# MCP Builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools.

## Prerequisites

- TypeScript (recommended) or Python
- Node.js 18+ for TypeScript, Python 3.10+ for Python
- Understanding of async/await patterns
- Familiarity with API integration

## Instructions

1. **Phase 1: Research and Planning**
   - Study MCP Protocol: Start with `https://modelcontextprotocol.io/sitemap.xml`
   - Understand the API you're integrating
   - Plan tool selection prioritizing comprehensive API coverage

2. **Phase 2: Set Up Project**

   For TypeScript (recommended):
   ```bash
   npm init -y
   npm install @modelcontextprotocol/sdk zod
   ```

   For Python:
   ```bash
   pip install mcp pydantic
   ```

3. **Implement Core Infrastructure**
   - API client with authentication
   - Error handling helpers with actionable messages
   - Response formatting (JSON/Markdown)
   - Pagination support

4. **Implement Tools**

   Each tool needs:
   - **Input Schema**: Use Zod (TypeScript) or Pydantic (Python)
   - **Output Schema**: Define `outputSchema` for structured data
   - **Clear Description**: Concise summary with parameter descriptions
   - **Annotations**: readOnlyHint, destructiveHint, idempotentHint

   ```typescript
   server.registerTool({
     name: "github_create_issue",
     description: "Create a new issue in a GitHub repository",
     inputSchema: z.object({
       repo: z.string().describe("Repository in owner/name format"),
       title: z.string().describe("Issue title"),
       body: z.string().optional()
     }),
     annotations: { destructiveHint: false, idempotentHint: false }
   });
   ```

5. **Phase 3: Test**
   ```bash
   # TypeScript
   npm run build
   npx @modelcontextprotocol/inspector

   # Python
   python -m py_compile your_server.py
   ```

6. **Phase 4: Create Evaluations**
   - Create 10 complex, realistic test questions
   - Each question should require multiple tool calls
   - Verify answers are stable and verifiable

## Error Handling

- Return actionable error messages that guide toward solutions
- Include specific suggestions and next steps
- Handle rate limiting gracefully

## Notes

- Use consistent tool naming prefixes (e.g., `github_create_issue`)
- Balance API coverage with workflow convenience tools
- Transport: Streamable HTTP for remote, stdio for local
- Return both text content and structured data

Source: anthropics/skills