mcp-builder

name	mcp-builder
description	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).
license	Complete terms in LICENSE.txt

MCP Server Development Guide

Create MCP servers that enable LLMs to interact with external services. Quality is measured by how well the server enables LLMs to accomplish real-world tasks.

Phase 1: Research and Planning

1.1 Design Principles

• API coverage vs. workflow tools: prioritize comprehensive API endpoint coverage; add workflow tools for common multi-step operations. When uncertain, prefer coverage.
• Tool naming: use consistent prefixes and action-oriented names (e.g., github_create_issue, github_list_repos)
• Context management: return focused, relevant data; support filtering and pagination
• Error messages: include specific suggestions and next steps to guide the agent toward solutions

1.2 Study MCP Protocol

Start with the sitemap: https://modelcontextprotocol.io/sitemap.xml Fetch pages with .md suffix for markdown (e.g., https://modelcontextprotocol.io/specification/draft.md).

Key areas: specification overview, transport mechanisms (streamable HTTP, stdio), tool/resource/prompt definitions.

1.3 Framework Documentation

Recommended stack: TypeScript with streamable HTTP (remote) or stdio (local).

Resource	Location
MCP Best Practices	reference/mcp_best_practices.md
TypeScript Guide	reference/node_mcp_server.md
Python Guide	reference/python_mcp_server.md
TypeScript SDK README	https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Python SDK README	https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

1.4 Plan Implementation

Review the service's API docs to identify key endpoints, auth requirements, and data models. Prioritize the most common operations.

Phase 2: Implementation

2.1 Project Structure

See language-specific guides for setup:

• TypeScript Guide — project structure, package.json, tsconfig
• Python Guide — module organization, dependencies

2.2 Core Infrastructure

Create shared utilities: API client with auth, error handling helpers, response formatting (JSON/Markdown), pagination support.

2.3 Implement Tools

For each tool:

Input schema: Use Zod (TypeScript) or Pydantic (Python) with constraints, clear descriptions, and examples.

Output schema: Define outputSchema where possible; use structuredContent for structured responses.

Implementation:

• Async/await for I/O
• Actionable error messages
• Pagination support where applicable

Annotations: Set readOnlyHint, destructiveHint, idempotentHint, openWorldHint as appropriate.

2.4 Define Resources and Prompts

Resources: Read-only data the model can fetch (file contents, API responses, config values). Register with registerResource() or resource() depending on SDK version. Handlers receive a uri argument.

Prompts: Reusable parameterised prompt templates the client can surface. Register with registerPrompt() or equivalent. Useful for complex multi-step workflows the model can invoke by name.

The SDK API for registration methods (tool() vs registerTool(), etc.) has changed across versions. Verify against the current SDK README or Context7 before using.

Phase 3: Review and Test

Best practices:

• Schema first: define input schemas for every tool; document parameters and return shape
• Idempotency: prefer idempotent tools so retries are safe
• Rate and cost: for tools that call external APIs, document rate limits and cost in the tool description
• Versioning: pin SDK version in package.json; check release notes when upgrading

Code quality: no duplicated code, consistent error handling, full type coverage, clear tool descriptions.

Build and test:

• TypeScript: npm run build, then npx @modelcontextprotocol/inspector
• Python: python -m py_compile your_server.py, then MCP Inspector

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

Phase 4: Create Evaluations

Test whether LLMs can effectively use your server to answer realistic, complex questions.

Load reference/evaluation.md for complete guidelines.

Process

1. Inspect tools: list available tools and understand capabilities
2. Explore content: use read-only operations to explore available data
3. Generate questions: create 10 complex, realistic questions
4. Verify answers: solve each question yourself

Question Requirements

Each question should be: independent, read-only, complex (multiple tool calls), realistic, verifiable (single clear answer), and stable over time.

Output Format

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames...</question>
    <answer>3</answer>
  </qa_pair>
</evaluation>

Official SDKs

Language	Package	Notes
TypeScript	@modelcontextprotocol/sdk (npm)	Use Context7 for current patterns
Go	modelcontextprotocol/go-sdk (GitHub)	Official Go SDK
C#	Official C# SDK for .NET	.NET ecosystem

MCP Version Notes (June 2026)

Current: MCP SDK v1.x (production). MCP v2 spec targeting stable release Q3 2026 (July 28, 2026).

• Governance: MCP is now under the Linux Foundation's Agentic AI Foundation (since late 2025)
• v2 direction: Stateless architecture for load-balanced enterprise environments (vs current stateful/session-based)
• v1.x SDKs: Continue using v1.x for production. v2 TypeScript SDK is pre-alpha.
• Python: Use fastmcp for quick server creation; mcp package for full control