mcp-builder

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 is measured by how well it enables LLMs to accomplish real-world tasks.

---

Process

🚀 High-Level Workflow

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

Phase 1: Deep 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 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.

#### 1.2 Study MCP Protocol Documentation

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:

#### 1.3 Study Framework Documentation

Recommended stack:

Load framework documentation:

For TypeScript (recommended):

For Python:

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

---

Phase 2: Implementation

#### 2.1 Set Up Project Structure

See language-specific guides for project setup:

#### 2.2 Implement Core Infrastructure

Create shared utilities:

#### 2.3 Implement Tools

For each tool:

Input Schema:

Output Schema:

Tool Description:

Implementation:

Annotations:

---

Phase 3: Review and Test

#### 3.1 Code Quality

Review for:

#### 3.2 Build and Test

TypeScript:

Python:

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

---

Phase 4: Create Evaluations

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

Load [✅ Evaluation Guide](./reference/evaluation.md) for complete evaluation guidelines.

#### 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 guide:

#### 4.3 Evaluation Requirements

Ensure each question is:

#### 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 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)

SDK Documentation (Load During Phase 1/2)

Language-Specific Implementation Guides (Load During Phase 2)

Evaluation Guide (Load During Phase 4)