MCP Server Development 指南

概述

Create MCP (Model Context 协议) servers that enable LLMs to interact with external 服务s through well-设计ed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.

Process

🚀 High-Level 工作流

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

Phase 1: Deep Research and Planning

1.1 Understand Modern MCP 设计

API Coverage vs. 工作流 Tools: Balance comprehensive API endpoint coverage with specialized 工作流 tools. 工作流 tools can be more convenient for specific tasks, while comprehensive coverage gives agents flexibility to compose operations. 性能 varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level 工作流s. When uncertain, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Clear, descriptive tool names help agents find the right tools quickly. 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. 设计 tools that return focused, relevant data. Some clients support code execution which can help agents filter and process data efficiently.

Actionable Error Messages: Error messages should 指南 agents toward solutions with specific suggestions and next steps.

1.2 Study MCP 协议 文档

Navigate the MCP specification:

Start with the sitemap to find relevant pages: https://modelcontext协议.io/sitemap.xml

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

Key pages to review:

• Specification overview and 架构
• Transport mechanisms (streamable HTTP, stdio)
• Tool, resource, and prompt definitions

1.3 Study 框架 文档

Recommended stack:

• Language: TypeScript (high-quality SDK support and good 兼容性 in many execution 环境s e.g. MCPB. Plus AI models are good at generating TypeScript code, benefiting from its broad usage, static typing and good linting tools)
• Transport: Streamable HTTP for remote servers, using stateless JSON (simpler to scale and maintain, as opposed to stateful sessions and streaming responses). stdio for local servers.

Load 框架 文档:

• MCP Best Practices: 📋 View Best Practices - Core 指南lines

For TypeScript (recommended):

• TypeScript SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontext协议/typescript-sdk/main/README.md
• ⚡ TypeScript 指南 - TypeScript 模式s and 示例s

For Python:

• Python SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontext协议/python-sdk/main/README.md
• 🐍 Python 指南 - Python 模式s and 示例s

1.4 Plan Your 实现

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

Tool Selection: Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.

Phase 2: 实现

2.1 Set Up Project Structure

See language-specific 指南s for project setup:

• ⚡ TypeScript 指南 - Project structure, package.json, tsconfig.json
• 🐍 Python 指南 - 模块 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
• Add 示例s in field descriptions

Output Schema:

• Define outputSchema where possible for structured data
• Use structuredContent in tool responses (TypeScript SDK feature)
• Helps clients understand and process tool outputs

Tool Description:

• Concise summary of 函数ality
• 参数 descriptions
• Return type schema

实现:

• Async/await for I/O operations
• Proper error handling with actionable messages
• Support pagination where applicable
• Return both text content and structured data when using modern SDKs

Annotations:

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

Phase 3: Review and Test

3.1 Code Quality

Review for:

• No duplicated code (DRY principle)
• Consistent error handling
• Full type coverage
• Clear tool descriptions

3.2 Build and Test

TypeScript:

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

Python:

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

See language-specific 指南s for detailed 测试 approaches and quality checklists.

Phase 4: Create Evaluations

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

Load ✅ Evaluation 指南 for complete evaluation 指南lines.

4.1 Understand Evaluation Purpose

Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions.

4.2 Create 10 Evaluation Questions

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

1. Tool Inspection: List available tools and understand their capabilities
2. Content Exploration: Use READ-ONLY operations to explore available data
3. Question Generation: Create 10 complex, realistic questions
4. Answer Verification: Solve each question yourself to verify answers

4.3 Evaluation Requirements

Ensure each question is:

• Independent: Not dependent on other questions
• Read-only: Only non-destructive operations required
• Complex: Requiring multiple tool calls and deep exploration
• Realistic: Based on real use cases humans would care about
• Verifiable: Single, clear answer that can be verified by string comparison
• Stable: Answer won't change over time

4.4 Output Format

Create an XML file with this structure:

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety 设计ation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>

Reference Files

📚 文档 库

Load these resources as needed during development:

Core MCP 文档 (Load First)

• MCP 协议: Start with sitemap at https://modelcontext协议.io/sitemap.xml, then fetch specific pages with .md suffix
• 📋 MCP Best Practices - Universal MCP 指南lines 包括:
  • Server and tool naming conventions
  • Response format 指南lines (JSON vs Markdown)
  • Pagination best practices
  • Transport selection (streamable HTTP vs stdio)
  • 安全性 and error handling standards

SDK 文档 (Load During Phase 1/2)

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

Language-Specific 实现 指南s (Load During Phase 2)

• 🐍 Python 实现 指南 - Complete Python/FastMCP 指南 with:

  • Server initialization 模式s
  • Pydantic model 示例s
  • Tool registration with @mcp.tool
  • Complete working 示例s
  • Quality checklist

• ⚡ TypeScript 实现 指南 - Complete TypeScript 指南 with:

  • Project structure
  • Zod schema 模式s
  • Tool registration with server.registerTool
  • Complete working 示例s
  • Quality checklist

Evaluation 指南 (Load During Phase 4)

• ✅ Evaluation 指南 - Complete evaluation creation 指南 with:
  • Question creation 指南lines
  • Answer verification strategies
  • XML format specifications
  • 示例 questions and answers
  • Running an evaluation with the provided scripts