SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsmcp-builder

mcp-builder

Agents & models

View repository

Updated 10-15 20:09

About this 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 determined by how well it enables LLMs to actually perform real tasks.

Process

🚀 High-Level Workflow

The process of building a high-quality MCP server is broadly divided into four phases:

Phase 1: Deep Research and Planning

1.1 Understanding Modern MCP Design

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools can be more convenient for specific tasks, while comprehensive coverage gives agents the flexibility to compose tasks freely. Performance varies by client—some clients are efficient with code execution approaches that combine primitive tools, while other clients work better with higher-level workflow tools. When in doubt, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Clear and descriptive tool names help agents quickly find the appropriate tool. Use consistent prefixes (e.g., github_create_issue, github_list_repos) and choose action-oriented names.

Context Management: Agents work more efficiently when there are concise tool descriptions and result filtering/pagination capabilities. Design tools to return focused and highly relevant data. Some clients support code execution, which helps agents efficiently filter and process data.

Actionable Error Messages: Error messages should provide specific suggestions and next steps to guide agents toward finding a solution.

1.2 Learning the MCP Protocol Documentation

Exploring the MCP Specification:

First, find the relevant pages in the sitemap: https://modelcontextprotocol.io/sitemap.xml

Then, fetch the specific pages with the .md suffix for markdown format (e.g., https://modelcontextprotocol.io/specification/draft.md).

Key pages to review:

  • Specification overview and architecture
  • Transport mechanisms (streamable HTTP, stdio)
  • Tool, Resource, and Prompt definitions

1.3 Learning the Framework Documentation

Recommended stack:

  • Language: TypeScript (supports high-quality SDKs and provides good compatibility across various execution environments such as MCPB. Also, AI models are proficient at generating TypeScript code thanks to its widespread usage, static typing, and excellent linting tools)
  • Transport: For remote servers, use Streamable HTTP with stateless JSON (simpler to scale and maintain compared to stateful sessions and streaming responses). For local servers, use stdio.

Load framework documentation:

For TypeScript (recommended):

  • TypeScript SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md load
  • ⚡ TypeScript Guide - TypeScript patterns and examples

Python용:

  • Python SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md load
  • 🐍 Python Guide - Python patterns and examples

1.4 Establish Implementation Plan

Understanding the API: Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.

Choosing Tools: Prioritize comprehensive API coverage. Create a list of endpoints to implement, starting with the most common operations.

Phase 2: Implementation

2.1 Set Up Project Structure

For project setup, refer to the language-specific guides:

2.2 Implement Core Infrastructure

Create shared utilities:

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

2.3 Implement Tools

For each tool, do the following:

Input Schema:

  • Use Zod (TypeScript) or Pydantic (Python)
  • Include constraints and clear descriptions
  • Add examples to field descriptions

Output Schema:

  • For structured data, define outputSchema definition
  • In tool responses, use structuredContent (TypeScript SDK feature)
  • Help clients understand and process tool output

Tool Description:

  • Concise summary of functionality
  • Parameter descriptions
  • Return type schema

Implementation:

  • Use Async/await for I/O operations
  • Proper error handling with actionable messages
  • Pagination support where applicable
  • Return both text content and structured data when using the latest SDK

Annotations:

  • readOnlyHint: true/false
  • destructiveHint: true/false
  • idempotentHint: true/false
  • openWorldHint: true/false

Phase 3: Review and Test

3.1 Code Quality

Review the following:

  • No duplicate code (DRY principle)
  • Consistent error handling
  • Complete type coverage
  • Clear tool descriptions

3.2 Build and Test

TypeScript:

  • To verify compilation, npm run build run
  • Test with MCP Inspector: npx @modelcontextprotocol/inspector

Python:

  • Syntax check: python -m py_compile your_server.py
  • Test with MCP Inspector

For detailed testing approaches and quality checklists, refer to the language-specific guides.

Phase 4: Create Evaluations

After implementing the MCP server, create comprehensive evaluations to test its effectiveness.

For complete evaluation guidelines, ✅ Evaluation Guideload.

4.1 Understanding the Purpose of Evaluations

Evaluations test whether an LLM can effectively use your MCP server to answer realistic and complex questions.

4.2 Write 10 Evaluation Questions

For effective evaluations, follow the process described in the guide:

  1. Tool Inspection: List available tools and understand their capabilities.
  2. Content Exploration: Explore available data using READ-ONLY operations
  3. Question Generation: Generate 10 complex and realistic questions
  4. Answer Verification: Verify answers by solving the questions directly

4.3 Evaluation Requirements

Ensure each question meets the following:

  • Independent: Does not depend on other questions
  • Read-only: Requires only non-destructive operations
  • Complex: Requires multiple tool calls and in-depth exploration
  • Realistic: Based on real use cases that humans would care about
  • Verifiable: Clear single answer verifiable by string comparison
  • Stable: Answers do not change over time

4.4 Output Format

Create an XML file with the following structure:

<evaluation>
  <qa_pair>
    <question>동물 코드명을 가진 AI 모델 출시에 관한 토론을 찾으세요. 한 모델은 ASL-X 형식을 사용하는 특정 안전 지정이 필요했습니다. 점박이 야생 고양이의 이름을 딴 모델에 대해 결정된 숫자 X는 무엇입니까?</question>
    <answer>3</answer>
  </qa_pair>
<!-- 더 많은 qa_pair... -->
</evaluation>
Reference Files

📚 Documentation Library

Load the following resources as needed during development:

Core MCP Documentation (load first)

  • MCP Protocol: https://modelcontextprotocol.io/sitemap.xmlStart with the sitemap at .md fetch the specific pages with the suffix.
  • 📋 MCP Best Practices - General MCP guidelines including:
    • Server and tool naming conventions
    • Response format guidelines (JSON vs Markdown)
    • Pagination best practices
    • Select transport method (streamable HTTP vs stdio)
    • Security and error handling standards

SDK documentation (loaded during Phase 1/2)

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

Language-specific implementation guide (loaded during Phase 2)

  • 🐍 Python Implementation Guide - Full Python/FastMCP guide including:

    • Server initialization patterns
    • Pydantic model examples
    • @mcp.toolTool registration using
    • Full working example code
    • Quality checklist

  • ⚡ TypeScript Implementation Guide - Full TypeScript guide including:

    • Project structure
    • Zod schema patterns
    • server.registerToolTool registration using
    • Full working example code
    • Quality checklist

Evaluation guide (loaded during Phase 4)

  • ✅ Evaluation Guide - Full evaluation generation guide including:
    • Question writing guidelines
    • Answer validation strategies
    • XML format specification
    • Question and answer examples
    • How to run evaluations using the provided script