Create MCP servers that enable LLMs to interact with external services through well-designed tools. MCP server quality is measured by the ability of LLMs to complete real-world tasks.
High-Level Workflow
Creating a high-quality MCP server involves four main phases:
Phase 1: In-Depth Research and Planning
1.1 Understand Modern MCP Design: Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools are more convenient for specific tasks, while comprehensive coverage gives agents the flexibility to compose operations. Performance varies by client—some clients benefit from code execution that composes basic tools, while other clients are better suited to high-level workflows. When uncertain, prioritize comprehensive API coverage.
Tool Naming and Discoverability: Clear, descriptive tool names help agents quickly find the right tool. Use consistent prefixes (such as 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 efficiently filter and process data.
Actionable Error Messages: Error messages should guide agents toward solutions through specific suggestions and next steps.
1.2 Research the MCP Protocol Documentation: Start with the sitemap:https://modelcontextprotocol.io/sitemap.xml, then fetch specific pages with the .md suffix (such as https://modelcontextprotocol.io/specification/draft.md). Key pages: specification overview and architecture, transport mechanisms (streamable HTTP, stdio), tools, resources, and prompt definitions.
1.3 Research Framework Documentation: Recommended stack: TypeScript (high-quality SDK support and good compatibility with many execution environments, AI models are good at generating TypeScript code, benefits from widespread use, static typing, and good linting tools), transport: streamable HTTP for remote servers (using stateless JSON), stdio for local servers.
Load framework documentation: MCP best practices, TypeScript SDK (get README from GitHub), Python SDK (get README from GitHub).
1.4 Plan the Implementation: Understand the API (review the service API documentation to identify key endpoints, authentication requirements, and data models), tool selection (prioritize comprehensive API coverage, list the endpoints to implement, start with the most common operations).
Phase 2: Implementation
2.1 Set Up the Project Structure: See language-specific guides (TypeScript guide, Python guide).
2.2 Implement Core Infrastructure: Create shared utilities: API client with authentication, error handling helpers, response formatting (JSON/Markdown), pagination support.
2.3 Implement Tools: For each tool: input schema (use Zod (TypeScript) or Pydantic (Python), include constraints and clear descriptions, add examples in field descriptions), output schema (if possible define outputSchema for structured data, use in tool responses structuredContent(TypeScript SDK features)), tool description (concise summary of functionality, parameter descriptions, return type schema), implementation (use async/await for I/O operations, appropriate error handling with actionable messages, support pagination where applicable, return text content and structured data when using modern SDKs), comments (readOnlyHint、destructiveHint、idempotentHint、openWorldHint）。
Phase 3: Review and Testing
3.1 Code Quality: Review: no duplicate code (DRY principle), consistent error handling, complete type coverage, clear tool descriptions.
3.2 Build and Testing: TypeScript: run npm run build to verify compilation, test with MCP Inspector:npx @modelcontextprotocol/inspector; Python: verify syntax:python -m py_compile your_server.py, test with MCP Inspector.
Phase 4: Create Evaluations
After implementing the MCP server, create comprehensive evaluations to test its effectiveness.
4.1 Understand the Purpose of Evaluations: Use evaluations to test whether an LLM can effectively use your MCP server to answer realistic, complex questions.
4.2 Create 10 Evaluation Questions: Follow the process in the evaluation guidelines: tool inspection, content exploration, question generation, answer verification.
4.3 Evaluation Requirements: Ensure each question is: independent, read-only, complex (requires multiple tool calls and deep exploration), realistic (based on real use cases humans would care about), verifiable (a single, clear answer that can be verified by string comparison), stable (the answer does not change over time).
4.4 Output Format: Create an XML file containing the questions and answers.
Reference Files
Core MCP Documentation: Start from the sitemap, then fetch specific pages; MCP best practices (general MCP guidelines, including server and tool naming conventions, response format guidelines, pagination best practices, transport selection, security and error handling standards).
SDK Documentation: Python SDK, TypeScript SDK (fetch README from GitHub).
Language-Specific Implementation Guides: Python implementation guide (complete Python/FastMCP guide), TypeScript implementation guide (complete TypeScript guide).
Evaluation Guide: complete evaluation creation guide.