MCP Server Builder

Overview

Build MCP servers that enable LLMs to interact with external services through thoughtfully designed tools.

Key Principle: Don't simply wrap API endpoints—build thoughtful, high-impact workflow tools.

Four-Phase Development

Phase 1: Research & Planning

• Study agent-centric design principles
• Review MCP protocol documentation
• Study target API documentation exhaustively
• Create detailed implementation plan

Phase 2: Implementation

• Set up project structure
• Build core infrastructure (auth, request helpers, formatters)
• Implement tools with JSON Schema validation
• Follow language-specific best practices

Phase 3: Review & Refine

• Code quality review (DRY, consistency, error handling)
• Test safely using evaluation harness
• Verify against quality checklist

Phase 4: Create Evaluations

• Design 10 complex, realistic test questions
• Create XML-formatted evaluation files
• Verify answers independently

Server Types

Type	Transport	Use Case
stdio	Process pipes	Local custom servers
HTTP	REST	Cloud-hosted servers
SSE	Server-Sent Events	Real-time updates
WebSocket	Bidirectional	Real-time communication

Tool Design

// Good: Workflow-oriented
async function analyzeAndSummarize(url: string) {
  // Fetches, parses, and summarizes in one call
}

// Avoid: Simple API wrapper
async function fetchPage(url: string) {
  // Just wraps fetch()
}

Implementation Standards

TypeScript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server({
  name: "my-server",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

Python (FastMCP)

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    """Tool description."""
    return result

Best Practices

1. JSON Schema validation on all inputs/outputs
2. Comprehensive error handling with meaningful messages
3. Logging to stderr (stdout reserved for protocol)
4. Security-first - validate inputs, manage sessions
5. Configurable detail levels for context efficiency
6. Tool annotations - mark read-only, destructive, idempotent