Building mcp servers

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.

---

High-Level Workflow

Creating a high-quality MCP server involves four main phases:

Phase 1: Deep Research and Planning

1.1 Understand Modern MCP Design

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Use consistent prefixes (e.g., github_create_issue, github_list_repos) and action-oriented naming.

Context Management: Design tools that return focused, relevant data. Support filtering/pagination.

Actionable Error Messages: Error messages should guide agents toward solutions with specific suggestions.

1.2 Study MCP Protocol Documentation

Start with the sitemap: https://modelcontextprotocol.io/sitemap.xml

Fetch pages with .md suffix (e.g., https://modelcontextprotocol.io/specification/draft.md).

Key pages: Specification overview, transport mechanisms, tool/resource/prompt definitions.

1.3 Study Framework Documentation

Recommended stack:

• Language: TypeScript (high-quality SDK, good AI code generation)
• Transport: Streamable HTTP for remote servers, stdio for local servers

Load framework documentation:

• MCP Best Practices - Core guidelines
• TypeScript Guide - TypeScript patterns
• Python Guide - Python/FastMCP patterns

SDK Documentation:

• TypeScript: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• Python: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

1.4 Plan Your Implementation

Review the service's API documentation. List endpoints to implement, starting with most common operations.

---

Phase 2: Implementation

2.1 Set Up Project Structure

See language-specific guides:

• TypeScript Guide - Project structure, package.json, tsconfig.json
• Python Guide - Module organization, dependencies

2.2 Implement Core Infrastructure

Create shared utilities:

• API client with authentication
• Error handling helpers
• Response formatting (JSON/Markdown)
• Pagination support

2.3 Implement Tools

For each tool:

Input Schema:

• Use Zod (TypeScript) or Pydantic (Python)
• Include constraints and clear descriptions

Output Schema:

• Define outputSchema where possible
• Use structuredContent in responses

Tool Description:

• Concise summary, parameter descriptions, return type

Annotations:

• readOnlyHint, destructiveHint, idempotentHint, openWorldHint

---

Phase 3: Review and Test

3.1 Code Quality

Review for: DRY principle, consistent error handling, full type coverage, clear descriptions.

3.2 Build and Test

TypeScript:

npm run build
npx @modelcontextprotocol/inspector

Python:

python -m py_compile your_server.py
# Test with MCP Inspector

---

Phase 4: Create Evaluations

Create 10 evaluation questions to test LLM effectiveness with your server.

Requirements for each question:

• Independent, read-only, complex, realistic, verifiable, stable

Output Format:

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

See Evaluation Guide for complete guidelines.

---

Docker/Containerization

Transport Security (allowed_hosts)

FastMCP validates Host headers. For Docker, configure:

from mcp.server.fastmcp import FastMCP
from mcp.server.transport_security import TransportSecuritySettings

transport_security = TransportSecuritySettings(
    allowed_hosts=[
        "127.0.0.1:*", "localhost:*", "[::1]:*",
        "mcp-server:*",  # Docker container name
        "0.0.0.0:*",
    ],
)
mcp = FastMCP("my_server", transport_security=transport_security)

Health Check Endpoint

Add /health endpoint via middleware (see references for full example).

---

Verification

Run: python3 scripts/verify.py

Expected: ✓ building-mcp-servers skill ready

If Verification Fails

1. Run diagnostic: Check references/ folder exists
2. Check: All reference files present
3. Stop and report if still failing

References

• MCP Best Practices - Universal guidelines
• Python Guide - Python/FastMCP patterns
• TypeScript Guide - TypeScript patterns
• TaskFlow Patterns - Internal server patterns
• Evaluation Guide - Creating evaluations