mcp-builder-ms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP Server Development Guide

MCP服务器开发指南

When to Use

适用场景

Use this skill when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

当你使用Python（FastMCP）或Node/TypeScript（MCP SDK）构建MCP服务器以集成外部API或服务时，可参考本指南。

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.

创建MCP（Model Context Protocol，模型上下文协议）服务器，让大语言模型（LLMs）能够通过设计精良的工具与外部服务交互。MCP服务器的质量取决于它能否帮助LLMs高效完成实际任务。

Microsoft MCP Ecosystem

Microsoft MCP生态系统

Microsoft provides extensive MCP infrastructure for Azure and Foundry services. Understanding this ecosystem helps you decide whether to build custom servers or leverage existing ones.

Microsoft为Azure和Foundry服务提供了完善的MCP基础设施。了解该生态系统有助于你决定是构建自定义服务器还是利用现有服务器。

Server Types

服务器类型

Type	Transport	Use Case	Example
Local	stdio	Desktop apps, single-user, local dev	Azure MCP Server via NPM/Docker
Remote	Streamable HTTP	Cloud services, multi-tenant, Agent Service	`https://mcp.ai.azure.com` (Foundry)

类型	传输方式	适用场景	示例
本地	stdio	桌面应用、单用户、本地开发	通过NPM/Docker部署的Azure MCP Server
远程	可流式HTTP	云服务、多租户、Agent Service	`https://mcp.ai.azure.com` （Foundry）

Microsoft MCP Servers

Microsoft官方MCP服务器

Before building a custom server, check if Microsoft already provides one:

Server	Type	Description
Azure MCP	Local	48+ Azure services (Storage, KeyVault, Cosmos, SQL, etc.)
Foundry MCP	Remote	`https://mcp.ai.azure.com` - Models, deployments, evals, agents
Fabric MCP	Local	Microsoft Fabric APIs, OneLake, item definitions
Playwright MCP	Local	Browser automation and testing
GitHub MCP	Remote	`https://api.githubcopilot.com/mcp`

Full ecosystem: See 🔷 Microsoft MCP Patterns for complete server catalog and patterns.

在构建自定义服务器之前，请先查看Microsoft是否已提供相关服务器：

服务器	类型	描述
Azure MCP	本地	支持48+种Azure服务（存储、KeyVault、Cosmos、SQL等）
Foundry MCP	远程	`https://mcp.ai.azure.com` - 模型、部署、评估、Agent
Fabric MCP	本地	Microsoft Fabric API、OneLake、项目定义
Playwright MCP	本地	浏览器自动化与测试
GitHub MCP	远程	`https://api.githubcopilot.com/mcp`

完整生态系统： 查看🔷 Microsoft MCP Patterns获取完整的服务器目录和模式。

When to Use Microsoft vs Custom

选择官方服务器还是自定义服务器

Scenario	Recommendation
Azure service integration	Use Azure MCP Server (48 services covered)
AI Foundry agents/evals	Use Foundry MCP remote server
Custom internal APIs	Build custom server (this guide)
Third-party SaaS integration	Build custom server (this guide)
Extending Azure MCP	Follow Microsoft MCP Patterns

场景	推荐方案
Azure服务集成	使用Azure MCP Server（已覆盖48种服务）
AI Foundry Agent/评估	使用Foundry MCP远程服务器
自定义内部API集成	构建自定义服务器（参考本指南）
第三方SaaS集成	构建自定义服务器（参考本指南）
扩展Azure MCP	遵循Microsoft MCP Patterns

Process

开发流程

🚀 High-Level Workflow

🚀 整体工作流

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

创建高质量MCP服务器包含四个主要阶段：

Phase 1: Deep Research and Planning

阶段1：深度调研与规划

1.1 Understand Modern MCP Design

1.1 理解现代MCP设计理念

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 flexibility to compose operations. Performance varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level workflows. 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. Design 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 guide agents toward solutions with specific suggestions and next steps.

API覆盖与工作流工具的平衡： 在全面覆盖API端点与提供专用工作流工具之间找到平衡。工作流工具针对特定任务更便捷，而全面的API覆盖则能让Agent灵活组合操作。不同客户端的性能表现不同——部分客户端受益于可组合基础工具的代码执行能力，而其他客户端则更适配高层级工作流。若不确定优先级，建议优先实现全面的API覆盖。

工具命名与可发现性： 清晰、描述性的工具名称能帮助Agent快速找到合适的工具。使用一致的前缀（例如

github_create_issue

、

github_list_repos

）和面向动作的命名方式。

上下文管理： Agent需要简洁的工具描述，以及对结果进行过滤/分页的能力。设计工具时应返回聚焦、相关的数据。部分客户端支持代码执行，可帮助Agent高效过滤和处理数据。

可操作的错误信息： 错误信息应提供具体建议和下一步操作，引导Agent解决问题。

1.2 Study MCP Protocol Documentation

1.2 学习MCP协议文档

Navigate the MCP specification:

Start with the sitemap to find relevant pages:

https://modelcontextprotocol.io/sitemap.xml

Then fetch specific pages with

.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

浏览MCP规范：

从站点地图开始查找相关页面：

https://modelcontextprotocol.io/sitemap.xml

然后使用

.md

后缀获取Markdown格式的具体页面（例如

https://modelcontextprotocol.io/specification/draft.md

）。

需重点查看的页面：

规范概述与架构
传输机制（可流式HTTP、stdio）
工具、资源与提示词定义

1.3 Study Framework Documentation

1.3 学习框架文档

Language Selection:

Language	Best For	SDK
TypeScript (recommended)	General MCP servers, broad compatibility	`@modelcontextprotocol/sdk`
Python	Data/ML pipelines, FastAPI integration	`mcp` (FastMCP)
C#/.NET	Azure/Microsoft ecosystem, enterprise	`Microsoft.Mcp.Core`

Transport Selection:

Transport	Use Case	Characteristics
Streamable HTTP	Remote servers, multi-tenant, Agent Service	Stateless, scalable, requires auth
stdio	Local servers, desktop apps	Simple, single-user, no network

Load framework documentation:

MCP Best Practices: 📋 View Best Practices - Core guidelines

For TypeScript (recommended):

TypeScript SDK: Use WebFetch to load

https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

⚡ TypeScript Guide - TypeScript patterns and examples

For Python:

Python SDK: Use WebFetch to load

https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

🐍 Python Guide - Python patterns and examples

For C#/.NET (Microsoft ecosystem):

🔷 Microsoft MCP Patterns - C# patterns, Azure MCP architecture, command hierarchy

语言选择：

语言	最佳适用场景	SDK
TypeScript（推荐）	通用MCP服务器、广泛兼容性	`@modelcontextprotocol/sdk`
Python	数据/ML流水线、FastAPI集成	`mcp` （FastMCP）
C#/.NET	Azure/Microsoft生态系统、企业级应用	`Microsoft.Mcp.Core`

传输方式选择：

传输方式	适用场景	特性
可流式HTTP	远程服务器、多租户、Agent Service	无状态、可扩展、需要身份验证
stdio	本地服务器、桌面应用	简单、单用户、无需网络

加载框架文档：

MCP最佳实践：📋 查看最佳实践 - 核心准则

对于TypeScript（推荐）：

TypeScript SDK：使用WebFetch加载

https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

⚡ TypeScript指南 - TypeScript模式与示例

对于Python：

Python SDK：使用WebFetch加载

https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

🐍 Python指南 - Python模式与示例

对于C#/.NET（Microsoft生态系统）：

🔷 Microsoft MCP Patterns - C#模式、Azure MCP架构、命令层级

1.4 Plan Your Implementation

1.4 规划实现方案

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 endpoints to implement, starting with the most common operations.

理解目标API： 查看服务的API文档，确定关键端点、身份验证要求和数据模型。必要时使用网页搜索和WebFetch工具。

工具选择： 优先实现全面的API覆盖。列出需要实现的端点，从最常用的操作开始。

Phase 2: Implementation

阶段2：开发实现

2.1 Set Up Project Structure

2.1 搭建项目结构

See language-specific guides for project setup:

⚡ TypeScript Guide - Project structure, package.json, tsconfig.json
🐍 Python Guide - Module organization, dependencies
🔷 Microsoft MCP Patterns - C# project structure, command hierarchy

参考各语言专属指南搭建项目结构：

⚡ TypeScript指南 - 项目结构、package.json、tsconfig.json
🐍 Python指南 - 模块组织、依赖管理
🔷 Microsoft MCP Patterns - C#项目结构、命令层级

2.2 Implement Core Infrastructure

2.2 实现核心基础设施

Create shared utilities:

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

创建共享工具类：

带身份验证的API客户端
错误处理工具
响应格式化（JSON/Markdown）
分页支持

2.3 Implement Tools

2.3 实现工具

For each tool:

Input Schema:

Use Zod (TypeScript) or Pydantic (Python)
Include constraints and clear descriptions
Add examples 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 functionality
Parameter descriptions
Return type schema

Implementation:

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

针对每个工具：

输入Schema：

使用Zod（TypeScript）或Pydantic（Python）
包含约束条件和清晰描述
在字段描述中添加示例

输出Schema：

尽可能定义
```
outputSchema
```
以返回结构化数据
在工具响应中使用
```
structuredContent
```
（TypeScript SDK特性）
帮助客户端理解和处理工具输出

工具描述：

简洁的功能概述
参数描述
返回类型Schema

实现细节：

使用Async/await处理I/O操作
带有可操作错误信息的异常处理
支持分页（如适用）
使用现代SDK时，同时返回文本内容和结构化数据

注解：

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

Phase 3: Review and Test

阶段3：评审与测试

3.1 Code Quality

3.1 代码质量检查

Review for:

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

检查以下内容：

无重复代码（遵循DRY原则）
一致的错误处理
完整的类型覆盖
清晰的工具描述

3.2 Build and Test

3.2 构建与测试

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

See language-specific guides for detailed testing approaches and quality checklists.

TypeScript：

运行
```
npm run build
```
验证编译是否通过
使用MCP Inspector测试：
```
npx @modelcontextprotocol/inspector
```

Python：

验证语法：
```
python -m py_compile your_server.py
```
使用MCP Inspector测试

参考各语言专属指南获取详细的测试方法和质量检查清单。

Phase 4: Create Evaluations

阶段4：创建评估用例

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

Load ✅ Evaluation Guide for complete evaluation guidelines.

完成MCP服务器开发后，创建全面的评估用例以测试其有效性。

加载✅ 评估指南获取完整的评估准则。

4.1 Understand Evaluation Purpose

4.1 理解评估目的

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

通过评估测试LLM能否有效使用你的MCP服务器来回答真实的复杂问题。

4.2 Create 10 Evaluation Questions

4.2 创建10个评估问题

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

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

按照评估指南中的流程创建有效的评估用例：

工具检查：列出可用工具并了解其功能
内容探索：使用只读操作探索可用数据
问题生成：创建10个复杂、真实的问题
答案验证：自行解决每个问题以验证答案正确性

4.3 Evaluation Requirements

4.3 评估要求

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

4.4 输出格式

Create an XML file with this structure:

xml

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation 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>

创建如下结构的XML文件：

xml

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation 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

参考文件

📚 Documentation Library

📚 文档库

Load these resources as needed during development:

开发过程中可按需加载以下资源：

Core MCP Documentation (Load First)

核心MCP文档（优先加载）

MCP Protocol: Start with sitemap at
```
https://modelcontextprotocol.io/sitemap.xml
```
, then fetch specific pages with
```
.md
```
suffix
📋 MCP Best Practices - Universal MCP guidelines including:
- Server and tool naming conventions
- Response format guidelines (JSON vs Markdown)
- Pagination best practices
- Transport selection (streamable HTTP vs stdio)
- Security and error handling standards

MCP协议：从站点地图
```
https://modelcontextprotocol.io/sitemap.xml
```
开始，然后使用
```
.md
```
后缀获取具体页面
📋 MCP最佳实践 - 通用MCP准则，包括：
- 服务器与工具命名规范
- 响应格式准则（JSON vs Markdown）
- 分页最佳实践
- 传输方式选择（可流式HTTP vs stdio）
- 安全与错误处理标准

Microsoft MCP Documentation (For Azure/Foundry)

Microsoft MCP文档（适用于Azure/Foundry）

🔷 Microsoft MCP Patterns - Microsoft-specific patterns including:
- Azure MCP Server architecture (48+ Azure services)
- C#/.NET command implementation patterns
- Remote MCP with Foundry Agent Service
- Authentication (Entra ID, OBO flow, Managed Identity)
- Testing infrastructure with Bicep templates

🔷 Microsoft MCP Patterns - Microsoft专属模式，包括：
- Azure MCP Server架构（支持48+种Azure服务）
- C#/.NET命令实现模式
- 基于Foundry Agent Service的远程MCP
- 身份验证（Entra ID、OBO流程、托管标识）
- 使用Bicep模板的测试基础设施

SDK Documentation (Load During Phase 1/2)

SDK文档（阶段1/2加载）

Python SDK: Fetch from

https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

TypeScript SDK: Fetch from

https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Microsoft MCP SDK: See Microsoft MCP Patterns for C#/.NET

Python SDK：从

https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

获取

TypeScript SDK：从

https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

获取

Microsoft MCP SDK：查看Microsoft MCP Patterns获取C#/.NET相关内容

Language-Specific Implementation Guides (Load During Phase 2)

语言专属实现指南（阶段2加载）

🐍 Python Implementation Guide - Complete Python/FastMCP guide with:
- Server initialization patterns
- Pydantic model examples
- Tool registration with
```
@mcp.tool
```
- Complete working examples
- Quality checklist
⚡ TypeScript Implementation Guide - Complete TypeScript guide with:
- Project structure
- Zod schema patterns
- Tool registration with
```
server.registerTool
```
- Complete working examples
- Quality checklist
🔷 Microsoft MCP Patterns - Complete C#/.NET guide with:
- Command hierarchy (BaseCommand → GlobalCommand → SubscriptionCommand)
- Naming conventions (
```
{Resource}{Operation}Command
```
  )
- Option handling with
```
.AsRequired()
```
  /
```
.AsOptional()
```
- Azure Functions remote MCP deployment
- Live test patterns with Bicep

🐍 Python实现指南 - 完整的Python/FastMCP指南，包括：
- 服务器初始化模式
- Pydantic模型示例
- 使用
```
@mcp.tool
```
  注册工具
- 完整的工作示例
- 质量检查清单
⚡ TypeScript实现指南 - 完整的TypeScript指南，包括：
- 项目结构
- Zod Schema模式
- 使用
```
server.registerTool
```
  注册工具
- 完整的工作示例
- 质量检查清单
🔷 Microsoft MCP Patterns - 完整的C#/.NET指南，包括：
- 命令层级（BaseCommand → GlobalCommand → SubscriptionCommand）
- 命名规范（
```
{Resource}{Operation}Command
```
  ）
- 使用
```
.AsRequired()
```
  /
```
.AsOptional()
```
  处理选项
- Azure Functions远程MCP部署
- 使用Bicep的实时测试模式

Evaluation Guide (Load During Phase 4)

评估指南（阶段4加载）

✅ Evaluation Guide - Complete evaluation creation guide with:
- Question creation guidelines
- Answer verification strategies
- XML format specifications
- Example questions and answers
- Running an evaluation with the provided scripts

✅ 评估指南 - 完整的评估用例创建指南，包括：
- 问题创建准则
- 答案验证策略
- XML格式规范
- 问题与答案示例
- 使用提供的脚本运行评估