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).
Tasks
Implement core infrastructure including an API client with authentication, error handling helpers, response formatting, and pagination support
Implement each tool with an input schema using Zod or Pydantic, define an output schema where possible, and set appropriate annotations such as readOnlyHint or destructiveHint
Create 10 evaluation questions that are independent, read-only, complex, realistic, verifiable, and stable, then output them as an XML file containing qa_pairs
Inputs
Service API documentation including key endpoints, authentication requirements, and data models
MCP specification pages fetched via sitemap (https://modelcontextprotocol.io/sitemap.xml) with .md suffixes
MCP Best Practices reference document (./reference/mcp_best_practices.md)
TypeScript SDK README (https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md) or Python SDK README (https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md)
TypeScript implementation guide (./reference/node_mcp_server.md) or Python implementation guide (./reference/python_mcp_server.md)
Evaluation guide (./reference/evaluation.md)
Outputs
MCP server source code with tools, schemas, and annotations
Evaluation XML file containing qa_pairs with complex questions and verifiable answers
Limitations and checks
Quality of an MCP server depends on how well it enables LLMs to accomplish real-world tasks, which can vary by client performance
API coverage should be balanced with specialized workflow tools; when uncertain, prioritize comprehensive API coverage
Transport choice depends on deployment: Streamable HTTP with stateless JSON for remote servers, stdio for local servers
Verify there is no duplicated code (DRY principle), consistent error handling, full type coverage, and clear tool descriptions
For TypeScript, run npm run build to verify compilation
For Python, verify syntax with python -m py_compile your_server.py
Test the server with MCP Inspector via npx @modelcontextprotocol/inspector
Verify each evaluation question is independent, read-only, complex, realistic, verifiable by string comparison, and stable over time
AI Search
Find projects, verify facts, compare options, or turn a complex need into an actionable plan
Try a searchA click only fills the search box; you stay in control