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

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. When uncertain, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Use consistent prefixes (e.g., github_create_issue, github_list_repos) and action-oriented naming.

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

1.2 Study MCP Protocol Documentation

Start with the sitemap: https://modelcontextprotocol.io/sitemap.xml

Then fetch specific pages with .md suffix for markdown format.

1.3 Framework Documentation

Recommended stack:

• Language: TypeScript (high-quality SDK support, good AI model familiarity, static typing)
• Transport: Streamable HTTP for remote servers (stateless JSON). stdio for local servers.

For TypeScript:

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

For Python:

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

1.4 Plan Your Implementation

Review the service's API documentation to identify key endpoints, authentication requirements, and data models. List endpoints to implement, starting with the most common operations.

---

Phase 2: Implementation

2.1 Set Up Project Structure

TypeScript:

my-mcp-server/
├── src/
│   ├── index.ts
│   └── tools/
├── package.json
├── tsconfig.json
└── README.md

Python:

my-mcp-server/
├── server.py
├── requirements.txt
└── README.md