What Breaks MCP Servers in Production

A team running two multi-user MCP servers in production—one an internal analytics gateway, the other an analytics tool for AI coding assistants—ran into a set of failures that never showed up in demos but consistently appeared by the second week of real usage. Those recurring fixes eventually became a normative standard, published on GitHub under a CC BY 4.0 license.

One key insight: error messages are read by the model, not a human. Since models hallucinate values and auto-retry, error responses need to bundle valid options, a fuzzy suggestion, and clear next steps in a single reply. Internal query timeouts also had to be kept shorter than the client's default 60-second window, otherwise the client cancels the request before a structured error can even arrive.

A second major issue was refresh token rotation silently forcing users into repeated re-logins; disabling rotation while keeping refresh token issuance solved this. A third problem came from Anthropic's API rejecting an entire tools array over a single JSON Schema key violating its allowed character pattern—causing every tool to vanish without any server-side error logs, which pushed the team to validate the actual tools/list output at boot time. Finally, responses needed truncation by both row count and byte size, since a single oversized cell could blow past client limits on its own. The resulting standard separates hard requirements—OAuth, HTTP transport, centralized logging—from optional, swappable implementation choices.