How Production MCP Servers Break and the Rules One Team Built to Fix Them

A development team running two production MCP servers — an analytics gateway and an AI coding tool called AI-Lens — documented recurring failures that only emerged after real-world deployment, not during demos. Key issues included unhelpful error messages that caused AI models to hallucinate incorrect values, users being unexpectedly logged out mid-session due to refresh token rotation conflicts, and tools silently disappearing from clients. The team found that structuring error responses with actionable hints — such as listing valid table names or suggesting query optimizations — dramatically reduced wasted retries by giving the model enough context to self-correct. They also identified a critical timeout mismatch, where client and server timeouts aligned too closely, preventing structured errors from reaching the model before the connection dropped. These findings were codified into an open standard published on GitHub under a CC BY 4.0 license, complete with a release-gate checklist for MCP server deployments.