MCP Builder

Iron Law

Never publish an MCP server without testing all tool schemas against the MCP spec; always validate tool descriptions are >= 10 words and parameters are fully typed.

MCP Server Development Guide

Create MCP servers that enable LLMs to interact with external services through well-designed tools.

High-Level Workflow

Phase 1: Research and Plan

• Study MCP spec from https://modelcontextprotocol.io/sitemap.xml (append .md for markdown)
• Fetch TypeScript SDK README from https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• Fetch Python SDK README from https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• Load design principles, agent patterns, and error taxonomy from reference files (see table below)

Phase 2: Implement

• Set up project structure using language-specific reference files (see table below)
• Create shared utilities: API client, error handling, response formatting, pagination
• For each tool: define input schema (Zod/Pydantic), output schema, description, annotations, and async implementation
• Recommended stack: TypeScript with streamable HTTP (remote) or stdio (local)

Phase 3: Review and Test

• Review for: no duplication, consistent error handling, full type coverage, clear tool descriptions
• TypeScript: npm run build then test with npx @modelcontextprotocol/inspector
• Python: python -m py_compile your_server.py then test with MCP Inspector

Phase 4: Create Evaluations

• Create 10 complex, realistic evaluation questions requiring multiple tool calls
• Each question must be: independent, read-only, complex, realistic, verifiable, stable
• Output as XML with <evaluation> root containing <qa_pair> elements

Tool Implementation Checklist

For each tool, define:

• Input schema — Zod (TypeScript) or Pydantic (Python) with constraints and descriptions
• Output schema — Use outputSchema and structuredContent where possible
• Description — Concise summary, parameter docs, return type
• Annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• Implementation — Async/await, proper error handling, pagination support
• Agent directive — Include next_actions and suggestion in every response
• Error taxonomy — Use MCPErrorCode enum with recovery actions

Reference Files

Common Mistakes

• Scoring/ranking logic in MCP layer — MCP tools are API entry points only. All business logic (scoring, filtering, matching) belongs in an upstream service. See reference/mcp-quality-compliance.md.
• Exceeding 25 tools — Agent decision accuracy degrades sharply past 25 tools. Consolidate by user intent, not by API endpoint. See reference/mcp-design-principles.md.
• Missing next_actions in responses — Every tool response must include next_actions (machine-readable) and suggestion (human-readable) or agents stall. No exceptions.
• Returning empty list/null on error — Never return [] or null as a silent fallback. Return a structured MCPErrorCode error so the agent knows what failed and how to recover.
• Tool descriptions written for developers — "Executes POST /api/v1/vendors" tells an LLM nothing. Write for the agent: "USE WHEN: Finding service vendors for a property. EXAMPLES: ..."

Error Handling

For the full error taxonomy and circuit breaker patterns, Read reference/error-taxonomy.md

Server startup failures: Validate all required environment variables at startup. Fail fast with a clear error message — never silently fall back to defaults.

Tool execution errors: Return structured MCP error responses with error codes. Never let unhandled exceptions crash the server.

// ✅ Required pattern — structured error, never silent failure
server.registerTool('search_vendors', { ... }, async (args) => {
  try {
    const results = await upstreamClient.search(args);
    return {
      content: [{ type: 'text', text: JSON.stringify({
        data: results,
        next_actions: ['vendor_get_details', 'vendor_request_quote'],
        suggestion: `Found ${results.length} vendors. Call vendor_get_details for full profiles.`,
      })}]
    };
  } catch (error) {
    return {
      isError: true,
      content: [{ type: 'text', text: JSON.stringify({
        code: 'SERVICE_UNAVAILABLE',
        message: error.message,
        retry_after_ms: 5000,
        recovery_actions: ['retry_search', 'use_cached_results'],
        fallback_tool: 'search_vendors_cached',
      })}]
    };
  }
});

Verify

Before publishing any MCP server:

• npm run build exits 0 (TypeScript) or python -m py_compile server.py exits 0 (Python)
• npx @modelcontextprotocol/inspector <entrypoint> — all tools listed with correct schemas
• All tool descriptions are ≥ 10 words
• All input parameters are fully typed (no any in TypeScript, no untyped dict in Python)
• Every tool response includes next_actions and suggestion fields
• npm test (or uv run pytest) exits 0 with coverage thresholds met
• No unhandled exceptions — all errors return structured MCPErrorCode responses
• Security checklist in reference/security-core.md reviewed