SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmcp-builder

mcp-builder

Agents & models

View repository

Updated 10-15 23:58

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 depends on how well it enables LLMs to complete real tasks.

Process

🚀 High-Level Workflow

Creating a high-quality MCP server consists of four main phases:

Phase 1: In-Depth Research and Planning

1.1 Understand Modern MCP Design

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools may be more convenient for specific tasks, while comprehensive coverage gives agents the flexibility to compose operations. Performance varies across clients—some clients benefit from code execution combined with basic tools, while others are better suited to high-level workflows. When in doubt, prioritize comprehensive API coverage.

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

Context Management: Agents benefit from concise tool descriptions and the ability to filter/paginate results. Design tools that return focused, relevant data. Some clients support code execution, which can help agents efficiently filter and process data.

Actionable Error Messages: Error messages should guide agents toward solutions, providing specific suggestions and next steps.

1.2 Study the MCP Protocol Documentation

Browse the MCP specification:

Start with the sitemap to find relevant pages:https://modelcontextprotocol.io/sitemap.xml

Then use the .md suffix to get a specific page in 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 Study the Framework Documentation

Recommended tech stack:

  • Language: TypeScript (high-quality SDK support, good compatibility in many execution environments such as MCPB. In addition, AI models are good at generating TypeScript code, thanks to its widespread use, static typing, and good linting tools)
  • Transport: Remote servers use streamable HTTP with stateless JSON (easier to scale and maintain than stateful sessions and streaming responses). Local servers use stdio.

Load the framework documentation:

TypeScript (recommended):

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

Python：

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

1.4 Plan the Implementation

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

Tool selection: Prioritize comprehensive API coverage. List the endpoints to implement, starting with the most commonly used operations.

Phase 2: Implementation

2.1 Set up the project structure

Refer to the language-specific guide for project setup:

2.2 Implement core infrastructure

Create shared utilities:

  • API client with authentication
  • Error handling helper functions
  • 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
  • Add examples in field descriptions

Output schema:

  • Define structured data whenever possible outputSchema
  • Use in tool responses 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
  • Use proper error handling with actionable messages
  • Support pagination where applicable
  • When using a modern SDK, return both text content and structured data

Annotations:

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

Phase 3: Review and testing

3.1 Code quality

Review the following aspects:

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

3.2 Build and test

TypeScript：

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

Python：

  • Verify syntax:python -m py_compile your_server.py
  • Test with MCP Inspector

Refer to the language-specific guide for detailed testing methods and quality checklists.

Phase 4: Create evaluations

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

Load ✅ Evaluation Guide to get the complete evaluation guide.

4.1 Understand the purpose of evaluations

Use evaluations to test whether an LLM can effectively use your MCP server to answer real, complex questions.

4.2 Create 10 evaluation questions

To create effective evaluations, follow the process outlined in the evaluation guide:

  1. Tool inspection: List available tools and understand their functionality
  2. Content exploration: Use read-only operations to explore available data
  3. Question generation: Create 10 complex, realistic questions
  4. Answer verification: Answer each question yourself to verify the answers

4.3 Evaluation requirements

Ensure that each question:

  • Independent: Does not depend on other questions
  • Read-only: Requires only non-destructive operations
  • Complex: Requires multiple tool calls and deep exploration
  • Real: Based on use cases that humans actually care about
  • Verifiable: A single, clear answer that can be verified by string comparison
  • Stable: The answer will 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_pairs... -->
</evaluation>
Reference Files

📚 Documentation Library

Load these resources as needed during development:

Core MCP Documentation (load first)

  • MCP Protocol: Start from the sitemap at https://modelcontextprotocol.io/sitemap.xml , then use the .md suffix to fetch specific pages
  • 📋 MCP Best Practices - General MCP guidance, including:
    • Server and tool naming conventions
    • Response format guidance (JSON vs Markdown)
    • Pagination best practices
    • Transport selection (Streamable HTTP vs stdio)
    • Security and error handling standards

SDK Documentation (load during phase 1/2)

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

Language-specific implementation guidance (load during phase 2)

  • 🐍 Python Implementation Guide - Complete Python/FastMCP guide, including:

    • Server initialization patterns
    • Pydantic model examples
    • Register tools using @mcp.tool Registration Tool
    • Complete working examples
    • Quality checklist

  • ⚡ TypeScript Implementation Guide - Complete TypeScript guide, including:

    • Project structure
    • Zod schema patterns
    • Register tools using server.registerTool Registration Tool
    • Complete working examples
    • Quality checklist

Evaluation Guide (load during phase 4)

  • ✅ Evaluation Guide - Complete evaluation creation guide, including:
    • Question creation guidance
    • Answer verification strategies
    • XML format specification
    • Example questions and answers
    • Run the evaluation using the provided script