Building Production-Grade MCP Servers

Practical lessons from building and shipping Model Context Protocol server packages: protocol design, error handling, testing strategies, and the patterns that separate demo tools from production systems.

#The Problem

Most MCP implementations work in demos but fail when real users bring bad inputs, slow networks, retries, and partial outages. The fix is to treat the server like a small production service, not like a script.

#Architecture Overview

1. Schema-first design: define tool contracts before handlers.
2. Layered architecture: keep protocol handling separate from business logic.
3. Idempotent operations: every call should be safe to retry.

from mcp import Server

class ProductionMCPServer:
    def __init__(self, config):
        self.server = Server(config.name)
        self.logger = structlog.get_logger()
        self._register_tools()

    def _register_tools(self):
        @self.server.tool("analyze_code")
        async def analyze_code(params):
            try:
                result = await self._do_analysis(params)
                return {"success": True, "data": result}
            except AnalysisError as error:
                self.logger.error("analysis_failed", error=str(error))
                return {"success": False, "error": str(error)}

#The Math Behind Load Balancing

When requests are distributed across server instances, a practical health-adjusted weight can be modeled as:

#Protocol Flow

sequenceDiagram
    participant Client as LLM Client
    participant Server as MCP Server
    participant Handler as Tool Handler

    Client->>Server: initialize()
    Server-->>Client: capabilities + tool list
    Client->>Server: tools/call("analyze_code", params)
    Server->>Handler: validate(params)
    Handler->>Handler: execute()
    Handler-->>Server: ToolResult
    Server-->>Client: result