1---
2name: mcp-builder
3description: 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) or Node/TypeScript (MCP SDK).
4license: Complete terms in LICENSE.txt
5---
6 
7# MCP Server Development Guide
8 
9## Overview
10 
11Create 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.
12 
13---
14 
15# Process
16 
17## 🚀 High-Level Workflow
18 
19Creating a high-quality MCP server involves four main phases:
20 
21### Phase 1: Deep Research and Planning
22 
23#### 1.1 Understand Modern MCP Design
24 
25**API Coverage vs. Workflow Tools:**
26Balance 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.
27 
28**Tool Naming and Discoverability:**
29Clear, 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.
30 
31**Context Management:**
32Agents 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.
33 
34**Actionable Error Messages:**
35Error messages should guide agents toward solutions with specific suggestions and next steps.
36 
37#### 1.2 Study MCP Protocol Documentation
38 
39**Navigate the MCP specification:**
40 
41Start with the sitemap to find relevant pages: `https://modelcontextprotocol.io/sitemap.xml`
42 
43Then fetch specific pages with `.md` suffix for markdown format (e.g., `https://modelcontextprotocol.io/specification/draft.md`).
44 
45Key pages to review:
46- Specification overview and architecture
47- Transport mechanisms (streamable HTTP, stdio)
48- Tool, resource, and prompt definitions
49 
50#### 1.3 Study Framework Documentation
51 
52**Recommended stack:**
53- **Language**: TypeScript (high-quality SDK support and good compatibility in many execution environments e.g. MCPB. Plus AI models are good at generating TypeScript code, benefiting from its broad usage, static typing and good linting tools)
54- **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.
55 
56**Load framework documentation:**
57 
58- **MCP Best Practices**: [📋 View Best Practices](./reference/mcp_best_practices.md) - Core guidelines
59 
60**For TypeScript (recommended):**
61- **TypeScript SDK**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
62- [⚡ TypeScript Guide](./reference/node_mcp_server.md) - TypeScript patterns and examples
63 
64**For Python:**
65- **Python SDK**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
66- [🐍 Python Guide](./reference/python_mcp_server.md) - Python patterns and examples
67 
68#### 1.4 Plan Your Implementation
69 
70**Understand the API:**
71Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.
72 
73**Tool Selection:**
74Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.
75 
76---
77 
78### Phase 2: Implementation
79 
80#### 2.1 Set Up Project Structure
81 
82See language-specific guides for project setup:
83- [⚡ TypeScript Guide](./reference/node_mcp_server.md) - Project structure, package.json, tsconfig.json
84- [🐍 Python Guide](./reference/python_mcp_server.md) - Module organization, dependencies
85 
86#### 2.2 Implement Core Infrastructure
87 
88Create shared utilities:
89- API client with authentication
90- Error handling helpers
91- Response formatting (JSON/Markdown)
92- Pagination support
93 
94#### 2.3 Implement Tools
95 
96For each tool:
97 
98**Input Schema:**
99- Use Zod (TypeScript) or Pydantic (Python)
100- Include constraints and clear descriptions
101- Add examples in field descriptions
102 
103**Output Schema:**
104- Define `outputSchema` where possible for structured data
105- Use `structuredContent` in tool responses (TypeScript SDK feature)
106- Helps clients understand and process tool outputs
107 
108**Tool Description:**
109- Concise summary of functionality
110- Parameter descriptions
111- Return type schema
112 
113**Implementation:**
114- Async/await for I/O operations
115- Proper error handling with actionable messages
116- Support pagination where applicable
117- Return both text content and structured data when using modern SDKs
118 
119**Annotations:**
120- `readOnlyHint`: true/false
121- `destructiveHint`: true/false
122- `idempotentHint`: true/false
123- `openWorldHint`: true/false
124 
125---
126 
127### Phase 3: Review and Test
128 
129#### 3.1 Code Quality
130 
131Review for:
132- No duplicated code (DRY principle)
133- Consistent error handling
134- Full type coverage
135- Clear tool descriptions
136 
137#### 3.2 Build and Test
138 
139**TypeScript:**
140- Run `npm run build` to verify compilation
141- Test with MCP Inspector: `npx @modelcontextprotocol/inspector`
142 
143**Python:**
144- Verify syntax: `python -m py_compile your_server.py`
145- Test with MCP Inspector
146 
147See language-specific guides for detailed testing approaches and quality checklists.
148 
149---
150 
151### Phase 4: Create Evaluations
152 
153After implementing your MCP server, create comprehensive evaluations to test its effectiveness.
154 
155**Load [✅ Evaluation Guide](./reference/evaluation.md) for complete evaluation guidelines.**
156 
157#### 4.1 Understand Evaluation Purpose
158 
159Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions.
160 
161#### 4.2 Create 10 Evaluation Questions
162 
163To create effective evaluations, follow the process outlined in the evaluation guide:
164 
1651. **Tool Inspection**: List available tools and understand their capabilities
1662. **Content Exploration**: Use READ-ONLY operations to explore available data
1673. **Question Generation**: Create 10 complex, realistic questions
1684. **Answer Verification**: Solve each question yourself to verify answers
169 
170#### 4.3 Evaluation Requirements
171 
172Ensure each question is:
173- **Independent**: Not dependent on other questions
174- **Read-only**: Only non-destructive operations required
175- **Complex**: Requiring multiple tool calls and deep exploration
176- **Realistic**: Based on real use cases humans would care about
177- **Verifiable**: Single, clear answer that can be verified by string comparison
178- **Stable**: Answer won't change over time
179 
180#### 4.4 Output Format
181 
182Create an XML file with this structure:
183 
184```xml
185<evaluation>
186  <qa_pair>
187    <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>
188    <answer>3</answer>
189  </qa_pair>
190<!-- More qa_pairs... -->
191</evaluation>
192```
193 
194---
195 
196# Reference Files
197 
198## 📚 Documentation Library
199 
200Load these resources as needed during development:
201 
202### Core MCP Documentation (Load First)
203- **MCP Protocol**: Start with sitemap at `https://modelcontextprotocol.io/sitemap.xml`, then fetch specific pages with `.md` suffix
204- [📋 MCP Best Practices](./reference/mcp_best_practices.md) - Universal MCP guidelines including:
205  - Server and tool naming conventions
206  - Response format guidelines (JSON vs Markdown)
207  - Pagination best practices
208  - Transport selection (streamable HTTP vs stdio)
209  - Security and error handling standards
210 
211### SDK Documentation (Load During Phase 1/2)
212- **Python SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
213- **TypeScript SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
214 
215### Language-Specific Implementation Guides (Load During Phase 2)
216- [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Complete Python/FastMCP guide with:
217  - Server initialization patterns
218  - Pydantic model examples
219  - Tool registration with `@mcp.tool`
220  - Complete working examples
221  - Quality checklist
222 
223- [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Complete TypeScript guide with:
224  - Project structure
225  - Zod schema patterns
226  - Tool registration with `server.registerTool`
227  - Complete working examples
228  - Quality checklist
229 
230### Evaluation Guide (Load During Phase 4)
231- [✅ Evaluation Guide](./reference/evaluation.md) - Complete evaluation creation guide with:
232  - Question creation guidelines
233  - Answer verification strategies
234  - XML format specifications
235  - Example questions and answers
236  - Running an evaluation with the provided scripts
237