domains / agent-tooling / mcp-server-development / mcp-builder

mcp-builder

Skill card

combined

The four copies overlap on the goal of building MCP servers but diverge on the recommended stack, workflow, and deployment targets. The anthropics and davepoon copies are near-duplicates of a high-level, language-agnostic guide that emphasizes research, planning, and evaluation. The jezweb copy is a Python/FastMCP-specific guide with a concrete deployment checklist for FastMCP Cloud and Docker. The Leanmcp copy is a TypeScript-specific guide using the official SDK with Streamable HTTP and Express. Because each copy contains material steps or constraints the others lack (e.g., FastMCP Cloud deployment vs. official SDK session management vs. evaluation-driven design), crowning one would hide real alternatives.

Repositories

Other copies

Combined skill

# MCP Server Development Guide

## Overview
Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.

## Phase 1: Research and Planning

### 1.1 Understand Design Principles
- **API Coverage vs. Workflow Tools:** Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage.
- **Tool Naming:** Use consistent prefixes and action-oriented naming for discoverability.
- **Context Management:** Design tools that return focused, relevant data. Consider concise vs. detailed response formats.
- **Actionable Error Messages:** Guide agents toward solutions with specific suggestions and next steps.

### 1.2 Study Documentation
- **MCP Specification:** Fetch `https://modelcontextprotocol.io/llms-full.txt` or navigate the sitemap.
- **Framework Documentation:**
  - **TypeScript (Recommended):** Load the TypeScript SDK README and the TypeScript Guide.
  - **Python:** Load the Python SDK README and the Python Guide.
- **API Documentation:** Review the service's API documentation for endpoints, authentication, and data models.

### 1.3 Plan Implementation
- **Tool Selection:** Prioritize comprehensive API coverage. List endpoints to implement.
- **Shared Utilities:** Plan for API clients, error handling, pagination, and response formatting.
- **Input/Output Design:** Define input validation models (Zod/Pydantic) and consistent response formats.

## Phase 2: Implementation

### 2.1 Set Up Project Structure
- **TypeScript:** Use the official `@modelcontextprotocol/sdk` with Express for Streamable HTTP transport, or use a framework like FastMCP if preferred.
- **Python:** Use FastMCP. Ensure the server instance is at module level for cloud deployment.

### 2.2 Implement Core Infrastructure
- Create shared utilities for API clients, error handling, and pagination.

### 2.3 Implement Tools
- **Input Schema:** Use Zod (TypeScript) or Pydantic (Python) with clear descriptions.
- **Output Schema:** Define `outputSchema` where possible for structured data.
- **Tool Description:** Concise summary, parameter descriptions, and return type schema.
- **Implementation:** Async/await for I/O, proper error handling, and pagination support.
- **Annotations:** Use `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`.

## Phase 3: Review and Test

### 3.1 Code Quality
- Review for DRY principle, consistent error handling, and full type coverage.

### 3.2 Build and Test
- **TypeScript:** Run `npm run build` and test with MCP Inspector.
- **Python:** Verify syntax with `python -m py_compile` and test with `fastmcp dev` or MCP Inspector.

## Phase 4: Deployment

### 4.1 Pre-Deploy Checklist
- Server file exists and syntax is valid.
- Module-level server object (for FastMCP Cloud).
- `requirements.txt` or `package.json` contains only valid dependencies.
- No hardcoded secrets.

### 4.2 Deploy
- **FastMCP Cloud:** Push to a public GitHub repository and connect to FastMCP Cloud.
- **Docker:** Use a Dockerfile with Python 3.12-slim and expose the HTTP port.
- **Cloudflare Workers:** Use the Cloudflare `agents` SDK for edge deployment.

## Phase 5: Evaluations
- Create comprehensive evaluations to test whether LLMs can effectively use the MCP server to answer realistic questions.
- Use agent feedback to drive tool improvements.