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:

<evaluation>
  <qa_pair>
    <question>Your question here</question>
    <answer>Expected answer</answer>
  </qa_pair>
</evaluation>