MCP Server Builder Patterns
Parent: MCP Server Development · Published reference · snapshot 2026-09-08
↓ Facts as markdownall context files
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 acc
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#overview]
🚀 High-Level Workflow
- Creating a high-quality MCP server involves four main phases: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#-high-level-workflow]
Phase 1: Deep Research and Planning
- #### 1.1 Understand Modern MCP Design [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Actionable Error Messages: Error messages should guide agents toward solutions with specific suggestions and next steps. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- #### 1.2 Study MCP Protocol Documentation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Navigate the MCP specification: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Start with the sitemap to find relevant pages: https://modelcontextprotocol.io/sitemap.xml [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Then fetch specific pages with .md suffix for markdown format (e.g., https://modelcontextprotocol.io/specification/draft.md). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Specification overview and architecture [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Transport mechanisms (streamable HTTP, stdio) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Tool, resource, and prompt definitions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- #### 1.3 Study Framework Documentation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Recommended stack: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Language: TypeScript (high-quality SDK support and good compatibility in many execution environments e.g. MCPB. Plus AI models are good at generating TypeScript code, benefiting from its broad usage, static typing and good linting tools) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Transport: Streamable HTTP for remote servers, using stateless JSON (simpler to scale and maintain, as opposed to stateful sessions and streaming responses). stdio for local servers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Load framework documentation: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- MCP Best Practices: 📋 View Best Practices - Core guidelines [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- For TypeScript (recommended): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- TypeScript SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- ⚡ TypeScript Guide - TypeScript patterns and examples [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Python SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- 🐍 Python Guide - Python patterns and examples [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- #### 1.4 Plan Your Implementation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
- Tool Selection: Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-1-deep-research-and-planning]
Phase 2: Implementation
- #### 2.1 Set Up Project Structure [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- See language-specific guides for project setup: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- ⚡ TypeScript Guide - Project structure, package.json, tsconfig.json [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- 🐍 Python Guide - Module organization, dependencies [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- #### 2.2 Implement Core Infrastructure [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Create shared utilities: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- API client with authentication [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Error handling helpers [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Response formatting (JSON/Markdown) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- #### 2.3 Implement Tools [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Use Zod (TypeScript) or Pydantic (Python) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Include constraints and clear descriptions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Add examples in field descriptions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Define outputSchema where possible for structured data [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Use structuredContent in tool responses (TypeScript SDK feature) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Helps clients understand and process tool outputs [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Tool Description: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Concise summary of functionality [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Parameter descriptions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Async/await for I/O operations [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Proper error handling with actionable messages [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Support pagination where applicable [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- Return both text content and structured data when using modern SDKs [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- readOnlyHint: true/false [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- destructiveHint: true/false [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- idempotentHint: true/false [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
- openWorldHint: true/false [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-2-implementation]
Phase 3: Review and Test
- #### 3.1 Code Quality [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- No duplicated code (DRY principle) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- Consistent error handling [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- Clear tool descriptions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- #### 3.2 Build and Test [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- Run npm run build to verify compilation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- Test with MCP Inspector: npx @modelcontextprotocol/inspector [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- Verify syntax: python -m py_compile your_server.py [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- Test with MCP Inspector [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
- See language-specific guides for detailed testing approaches and quality checklists. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-3-review-and-test]
Phase 4: Create Evaluations
- After implementing your MCP server, create comprehensive evaluations to test its effectiveness. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Load ✅ Evaluation Guide for complete evaluation guidelines. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- #### 4.1 Understand Evaluation Purpose [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- #### 4.2 Create 10 Evaluation Questions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- To create effective evaluations, follow the process outlined in the evaluation guide: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Tool Inspection: List available tools and understand their capabilities [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Content Exploration: Use READ-ONLY operations to explore available data [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Question Generation: Create 10 complex, realistic questions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Answer Verification: Solve each question yourself to verify answers [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- #### 4.3 Evaluation Requirements [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Ensure each question is: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Independent: Not dependent on other questions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Read-only: Only non-destructive operations required [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Complex: Requiring multiple tool calls and deep exploration [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Realistic: Based on real use cases humans would care about [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Verifiable: Single, clear answer that can be verified by string comparison [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Stable: Answer won't change over time [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- #### 4.4 Output Format [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
- Create an XML file with this structure: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#phase-4-create-evaluations]
📚 Documentation Library
- Load these resources as needed during development: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#-documentation-library]
Core MCP Documentation (Load First)
- MCP Protocol: Start with sitemap at https://modelcontextprotocol.io/sitemap.xml, then fetch specific pages with .md suffix [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#core-mcp-documentation-load-first]
- 📋 MCP Best Practices - Universal MCP guidelines including: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#core-mcp-documentation-load-first]
- Server and tool naming conventions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#core-mcp-documentation-load-first]
- Response format guidelines (JSON vs Markdown) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#core-mcp-documentation-load-first]
- Pagination best practices [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#core-mcp-documentation-load-first]
- Transport selection (streamable HTTP vs stdio) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#core-mcp-documentation-load-first]
- Security and error handling standards [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#core-mcp-documentation-load-first]
SDK Documentation (Load During Phase 1/2)
- Python SDK: Fetch from https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#sdk-documentation-load-during-phase-12]
- TypeScript SDK: Fetch from https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#sdk-documentation-load-during-phase-12]
Language-Specific Implementation Guides (Load During Phase 2)
- 🐍 Python Implementation Guide - Complete Python/FastMCP guide with: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#language-specific-implementation-guides-load-during-phase-2]
- Server initialization patterns [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#language-specific-implementation-guides-load-during-phase-2]
- Pydantic model examples [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#language-specific-implementation-guides-load-during-phase-2]
- Tool registration with @mcp.tool [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#language-specific-implementation-guides-load-during-phase-2]
- Complete working examples [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#language-specific-implementation-guides-load-during-phase-2]
- ⚡ TypeScript Implementation Guide - Complete TypeScript guide with: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#language-specific-implementation-guides-load-during-phase-2]
- Tool registration with server.registerTool [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#language-specific-implementation-guides-load-during-phase-2]
Evaluation Guide (Load During Phase 4)
- ✅ Evaluation Guide - Complete evaluation creation guide with: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#evaluation-guide-load-during-phase-4]
- Question creation guidelines [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#evaluation-guide-load-during-phase-4]
- Answer verification strategies [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#evaluation-guide-load-during-phase-4]
- XML format specifications [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#evaluation-guide-load-during-phase-4]
- Example questions and answers [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#evaluation-guide-load-during-phase-4]
- Running an evaluation with the provided scripts [archived source: https://llms-explorer.com/sources/mdb-context-hub/mcp-builder/#evaluation-guide-load-during-phase-4]
Where this helps
- Designing the tool surface for a new MCP server, deciding whether to expose broad API-coverage tools or a smaller set of purpose-built workflow tools for the tasks agents actually need. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Naming and documenting tools so an LLM client can reliably discover and pick the right one, especially once a server exposes more than a handful of tools. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding when to build a new MCP server versus wrapping an existing API directly, following the pack's four-phase workflow of research/planning, implementation, review/test, and evaluation. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Standing up evaluation infrastructure for an MCP server before shipping it, to verify LLMs can actually use the exposed tools to answer realistic, complex questions rather than just execute without error. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Project ideas
- Build an MCP server with a small set of workflow-oriented tools, rather than one-to-one API wrappers, for a task domain you use often, and give each tool a consistent naming prefix such as `service_verb_noun`. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build an evaluation suite for an MCP server following the pack's Phase 4 guidance — realistic question generation, XML-format answer verification, and a scored pass/fail per question. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build a Python (FastMCP) or TypeScript MCP server from the pack's referenced SDK docs, following its recommended project-structure conventions. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build a response-shaping layer for an existing MCP server's tools that trims and paginates results, since the pack flags context management — concise descriptions, filterable/paginated output — as a design concern. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Building one MCP tool per raw API endpoint by default instead of considering purpose-built workflow tools — comprehensive coverage without curation can leave an agent unable to tell which tool actually fits a task. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Shipping an MCP server without the Phase 4 evaluation step — code-quality review alone (DRY, consistent error handling) doesn't tell you whether an LLM can actually use the server to complete real tasks. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Giving tools inconsistent or generic names instead of a consistent prefix convention, which is exactly what the pack's discoverability guidance (e.g., github_create_issue, github_list_repos) is meant to prevent. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Skipping Phase 1 research — reading the current MCP protocol docs and SDK README before building — and working from stale or assumed knowledge of the protocol instead. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- This pack is itself a workflow/routing document — it points to external docs (protocol sitemap, SDK READMEs, best-practices guide) rather than containing the implementation details itself, so building a server still requires fetching those linked resources. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Balancing API coverage against workflow-tool curation is presented as a judgment call, not a formula — the pack gives no hard rule for when a server has too many or too few tools. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- The pack's evaluation guidance (XML-format answer verification, question-creation guidelines) implies real engineering effort beyond writing the server itself, which teams building MCP servers under time pressure often skip. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- FastMCP Python Patterns (frontier)
- TypeScript SDK Patterns (frontier)
- Tool Design Checklist (frontier)
- MCP Deployment Patterns (frontier)
- Production Hardening (frontier)
Frontier under this node: FastMCP Python Patterns, MCP Deployment Patterns, Production Hardening, Tool Design Checklist, TypeScript SDK Patterns