Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node/TypeScript (MCP SDK), or C#/.NET (Microsoft MCP SDK).
Add this skill
npx mdskills install microsoft/mcp-builderComprehensive guide for building MCP servers with clear phases, best practices, and language-specific patterns
1---2name: mcp-builder3description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node/TypeScript (MCP SDK), or C#/.NET (Microsoft MCP SDK).4---56# MCP Server Development Guide78## Overview910Create 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.1112---1314## Microsoft MCP Ecosystem1516Microsoft provides extensive MCP infrastructure for Azure and Foundry services. Understanding this ecosystem helps you decide whether to build custom servers or leverage existing ones.1718### Server Types1920| Type | Transport | Use Case | Example |21|------|-----------|----------|---------|22| **Local** | stdio | Desktop apps, single-user, local dev | Azure MCP Server via NPM/Docker |23| **Remote** | Streamable HTTP | Cloud services, multi-tenant, Agent Service | `https://mcp.ai.azure.com` (Foundry) |2425### Microsoft MCP Servers2627Before building a custom server, check if Microsoft already provides one:2829| Server | Type | Description |30|--------|------|-------------|31| **Azure MCP** | Local | 48+ Azure services (Storage, KeyVault, Cosmos, SQL, etc.) |32| **Foundry MCP** | Remote | `https://mcp.ai.azure.com` - Models, deployments, evals, agents |33| **Fabric MCP** | Local | Microsoft Fabric APIs, OneLake, item definitions |34| **Playwright MCP** | Local | Browser automation and testing |35| **GitHub MCP** | Remote | `https://api.githubcopilot.com/mcp` |3637**Full ecosystem:** See [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) for complete server catalog and patterns.3839### When to Use Microsoft vs Custom4041| Scenario | Recommendation |42|----------|----------------|43| Azure service integration | Use **Azure MCP Server** (48 services covered) |44| AI Foundry agents/evals | Use **Foundry MCP** remote server |45| Custom internal APIs | Build **custom server** (this guide) |46| Third-party SaaS integration | Build **custom server** (this guide) |47| Extending Azure MCP | Follow [Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md)4849---5051# Process5253## 🚀 High-Level Workflow5455Creating a high-quality MCP server involves four main phases:5657### Phase 1: Deep Research and Planning5859#### 1.1 Understand Modern MCP Design6061**API Coverage vs. Workflow Tools:**62Balance 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.6364**Tool Naming and Discoverability:**65Clear, 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.6667**Context Management:**68Agents 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.6970**Actionable Error Messages:**71Error messages should guide agents toward solutions with specific suggestions and next steps.7273#### 1.2 Study MCP Protocol Documentation7475**Navigate the MCP specification:**7677Start with the sitemap to find relevant pages: `https://modelcontextprotocol.io/sitemap.xml`7879Then fetch specific pages with `.md` suffix for markdown format (e.g., `https://modelcontextprotocol.io/specification/draft.md`).8081Key pages to review:82- Specification overview and architecture83- Transport mechanisms (streamable HTTP, stdio)84- Tool, resource, and prompt definitions8586#### 1.3 Study Framework Documentation8788**Language Selection:**8990| Language | Best For | SDK |91|----------|----------|-----|92| **TypeScript** (recommended) | General MCP servers, broad compatibility | `@modelcontextprotocol/sdk` |93| **Python** | Data/ML pipelines, FastAPI integration | `mcp` (FastMCP) |94| **C#/.NET** | Azure/Microsoft ecosystem, enterprise | `Microsoft.Mcp.Core` |9596**Transport Selection:**9798| Transport | Use Case | Characteristics |99|-----------|----------|-----------------|100| **Streamable HTTP** | Remote servers, multi-tenant, Agent Service | Stateless, scalable, requires auth |101| **stdio** | Local servers, desktop apps | Simple, single-user, no network |102103**Load framework documentation:**104105- **MCP Best Practices**: [📋 View Best Practices](./reference/mcp_best_practices.md) - Core guidelines106107**For TypeScript (recommended):**108- **TypeScript SDK**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`109- [⚡ TypeScript Guide](./reference/node_mcp_server.md) - TypeScript patterns and examples110111**For Python:**112- **Python SDK**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`113- [🐍 Python Guide](./reference/python_mcp_server.md) - Python patterns and examples114115**For C#/.NET (Microsoft ecosystem):**116- [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) - C# patterns, Azure MCP architecture, command hierarchy117118#### 1.4 Plan Your Implementation119120**Understand the API:**121Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.122123**Tool Selection:**124Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.125126---127128### Phase 2: Implementation129130#### 2.1 Set Up Project Structure131132See language-specific guides for project setup:133- [⚡ TypeScript Guide](./reference/node_mcp_server.md) - Project structure, package.json, tsconfig.json134- [🐍 Python Guide](./reference/python_mcp_server.md) - Module organization, dependencies135- [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) - C# project structure, command hierarchy136137#### 2.2 Implement Core Infrastructure138139Create shared utilities:140- API client with authentication141- Error handling helpers142- Response formatting (JSON/Markdown)143- Pagination support144145#### 2.3 Implement Tools146147For each tool:148149**Input Schema:**150- Use Zod (TypeScript) or Pydantic (Python)151- Include constraints and clear descriptions152- Add examples in field descriptions153154**Output Schema:**155- Define `outputSchema` where possible for structured data156- Use `structuredContent` in tool responses (TypeScript SDK feature)157- Helps clients understand and process tool outputs158159**Tool Description:**160- Concise summary of functionality161- Parameter descriptions162- Return type schema163164**Implementation:**165- Async/await for I/O operations166- Proper error handling with actionable messages167- Support pagination where applicable168- Return both text content and structured data when using modern SDKs169170**Annotations:**171- `readOnlyHint`: true/false172- `destructiveHint`: true/false173- `idempotentHint`: true/false174- `openWorldHint`: true/false175176---177178### Phase 3: Review and Test179180#### 3.1 Code Quality181182Review for:183- No duplicated code (DRY principle)184- Consistent error handling185- Full type coverage186- Clear tool descriptions187188#### 3.2 Build and Test189190**TypeScript:**191- Run `npm run build` to verify compilation192- Test with MCP Inspector: `npx @modelcontextprotocol/inspector`193194**Python:**195- Verify syntax: `python -m py_compile your_server.py`196- Test with MCP Inspector197198See language-specific guides for detailed testing approaches and quality checklists.199200---201202### Phase 4: Create Evaluations203204After implementing your MCP server, create comprehensive evaluations to test its effectiveness.205206**Load [✅ Evaluation Guide](./reference/evaluation.md) for complete evaluation guidelines.**207208#### 4.1 Understand Evaluation Purpose209210Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions.211212#### 4.2 Create 10 Evaluation Questions213214To create effective evaluations, follow the process outlined in the evaluation guide:2152161. **Tool Inspection**: List available tools and understand their capabilities2172. **Content Exploration**: Use READ-ONLY operations to explore available data2183. **Question Generation**: Create 10 complex, realistic questions2194. **Answer Verification**: Solve each question yourself to verify answers220221#### 4.3 Evaluation Requirements222223Ensure each question is:224- **Independent**: Not dependent on other questions225- **Read-only**: Only non-destructive operations required226- **Complex**: Requiring multiple tool calls and deep exploration227- **Realistic**: Based on real use cases humans would care about228- **Verifiable**: Single, clear answer that can be verified by string comparison229- **Stable**: Answer won't change over time230231#### 4.4 Output Format232233Create an XML file with this structure:234235```xml236<evaluation>237 <qa_pair>238 <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>239 <answer>3</answer>240 </qa_pair>241<!-- More qa_pairs... -->242</evaluation>243```244245---246247# Reference Files248249## 📚 Documentation Library250251Load these resources as needed during development:252253### Core MCP Documentation (Load First)254- **MCP Protocol**: Start with sitemap at `https://modelcontextprotocol.io/sitemap.xml`, then fetch specific pages with `.md` suffix255- [📋 MCP Best Practices](./reference/mcp_best_practices.md) - Universal MCP guidelines including:256 - Server and tool naming conventions257 - Response format guidelines (JSON vs Markdown)258 - Pagination best practices259 - Transport selection (streamable HTTP vs stdio)260 - Security and error handling standards261262### Microsoft MCP Documentation (For Azure/Foundry)263- [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) - Microsoft-specific patterns including:264 - Azure MCP Server architecture (48+ Azure services)265 - C#/.NET command implementation patterns266 - Remote MCP with Foundry Agent Service267 - Authentication (Entra ID, OBO flow, Managed Identity)268 - Testing infrastructure with Bicep templates269270### SDK Documentation (Load During Phase 1/2)271- **Python SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`272- **TypeScript SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`273- **Microsoft MCP SDK**: See [Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) for C#/.NET274275### Language-Specific Implementation Guides (Load During Phase 2)276- [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Complete Python/FastMCP guide with:277 - Server initialization patterns278 - Pydantic model examples279 - Tool registration with `@mcp.tool`280 - Complete working examples281 - Quality checklist282283- [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Complete TypeScript guide with:284 - Project structure285 - Zod schema patterns286 - Tool registration with `server.registerTool`287 - Complete working examples288 - Quality checklist289290- [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) - Complete C#/.NET guide with:291 - Command hierarchy (BaseCommand → GlobalCommand → SubscriptionCommand)292 - Naming conventions (`{Resource}{Operation}Command`)293 - Option handling with `.AsRequired()` / `.AsOptional()`294 - Azure Functions remote MCP deployment295 - Live test patterns with Bicep296297### Evaluation Guide (Load During Phase 4)298- [✅ Evaluation Guide](./reference/evaluation.md) - Complete evaluation creation guide with:299 - Question creation guidelines300 - Answer verification strategies301 - XML format specifications302 - Example questions and answers303 - Running an evaluation with the provided scripts304
Full transparency — inspect the skill content before installing.