MCP Server Development Guide

This skill provides comprehensive guidance for building MCP servers that enable LLMs to effectively interact with external services through well-designed tools.

When to Use This Skill

• Building a new MCP server to integrate an external API
• Designing tools for an existing MCP server
• Reviewing MCP server implementation quality
• Creating evaluations to test MCP server effectiveness
• Learning MCP best practices

What This Skill Does

1. Guides Implementation: Step-by-step process for building MCP servers
2. Provides Best Practices: Naming conventions, response formats, pagination
3. Offers Language-Specific Guidance: Python (FastMCP) and TypeScript (MCP SDK)
4. Includes Quality Checklists: Verify implementation completeness
5. Supports Evaluation Creation: Test MCP servers with realistic questions

High-Level Workflow

Phase 1: Deep Research and Planning

1.1 Understand Agent-Centric Design Principles

Build for Workflows, Not Just API Endpoints:

• Don't simply wrap existing API endpoints - build thoughtful, high-impact workflow tools
• Consolidate related operations (e.g., schedule_event that both checks availability and creates event)
• Focus on tools that enable complete tasks, not just individual API calls

Optimize for Limited Context:

• Agents have constrained context windows - make every token count
• Return high-signal information, not exhaustive data dumps
• Provide "concise" vs "detailed" response format options
• Default to human-readable identifiers over technical codes (names over IDs)

Design Actionable Error Messages:

• Error messages should guide agents toward correct usage patterns
• Suggest specific next steps: "Try using filter='active_only' to reduce results"
• Make errors educational, not just diagnostic

1.2 Study Documentation

Load the reference files in docs/mcp-reference/:

• mcp_best_practices.md - Core guidelines for all MCP servers
• node_mcp_server.md - TypeScript/Node implementation guide
• python_mcp_server.md - Python/FastMCP implementation guide
• evaluation.md - Creating evaluations for testing

1.3 Create Implementation Plan

Based on research, create a detailed plan:

Tool Selection:

• List the most valuable endpoints/operations to implement
• Prioritize tools that enable common and important use cases
• Consider which tools work together for complex workflows

Input/Output Design:

• Define input validation models (Pydantic for Python, Zod for TypeScript)
• Design consistent response formats (JSON and Markdown)
• Plan for large-scale usage with pagination and character limits

Phase 2: Implementation

2.1 Set Up Project Structure

For Python:

service_mcp/
├── server.py           # Main entry point
├── models.py           # Pydantic models
├── tools/              # Tool implementations
└── utils.py            # Shared utilities

For TypeScript:

service-mcp-server/
├── src/
│   ├── index.ts        # Main entry point
│   ├── types.ts        # Type definitions
│   ├── schemas/        # Zod schemas
│   └── tools/          # Tool implementations
├── package.json
└── tsconfig.json

2.2 Implement Core Infrastructure First

Create shared utilities before implementing tools:

• API request helper functions
• Error handling utilities
• Response formatting functions (JSON and Markdown)
• Pagination helpers
• Authentication/token management

2.3 Implement Tools Systematically

For each tool:

1. Define Input Schema with proper constraints and descriptions
2. Write Comprehensive Descriptions with examples
3. Implement Tool Logic using shared utilities
4. Add Tool Annotations (readOnlyHint, destructiveHint, etc.)

Phase 3: Review and Refine

3.1 Code Quality Review

• DRY Principle: No duplicated code between tools
• Composability: Shared logic extracted into functions
• Consistency: Similar operations return similar formats
• Error Handling: All external calls have error handling
• Type Safety: Full type coverage

3.2 Quality Checklist

Strategic Design:

• Tools enable complete workflows, not just API wrappers
• Response formats optimize for agent context efficiency
• Error messages guide agents toward correct usage

Implementation Quality:

• All tools have comprehensive descriptions
• Input schemas have proper constraints
• Annotations correctly set
• Pagination implemented where applicable
• Character limits respected with truncation

Phase 4: Create Evaluations

Create 10 realistic questions to test the MCP server:

• Questions must be read-only and independent
• Each should require multiple tool calls
• Answers must be single, verifiable values
• Answers must be stable (won't change over time)

See docs/mcp-reference/evaluation.md for complete guidelines.

Reference Files

Load these resources as needed during development:

Tips

• Start with the most valuable 3-5 tools, not all possible endpoints
• Test tools with actual LLM agents during development
• Iterate based on agent feedback and evaluation results
• Focus on reducing context consumption in responses
• Document error scenarios with suggested remedies