DEV Community
Follow
What Breaks MCP Servers in Production (MCP Best Practicies)?
The team operates two multi-user MCP servers for company-wide analytics, an analytics gateway and an AI coding assistant tool called AI-Lens. Production use revealed common issues like unactionable errors, user disconnections, disappearing tools, and oversized responses. These recurring problems led to the development of the mcp-server-standard, a normative document with a release-gate checklist.A key principle is designing error messages for models, not just humans, providing actionable information and suggested corrections. Error messages are part of the server's API and should be as robust as tool schemas. Returning all necessary error information at once prevents wasted model turns. Preventing errors by providing reference lists in tool descriptions or server instructions is also crucial.The standard addresses refresh token rotation by recommending non-rotating refresh tokens for MCP clients to prevent random user logouts. It clarifies that server redeployments do not drop user sessions if client persistence is handled correctly. Invalid JSON Schema property keys in tool definitions can cause the entire tool list to fail, so this is treated as a boot-time invariant check.Response truncation must consider both row count and byte size to prevent client-side errors. The instructions field for a model's session start also has a strict size limit. The mcp-server-standard mandates core requirements like OAuth, HTTP transport, and centralized, queryable logging with secret redaction. It imposes properties, not specific tools, allowing for flexible stack choices. The standard also honestly documents its limitations, such as the lack of zero-downtime rolling deploys for stateful servers. The full standard is organized into ten sections with stable requirement IDs for clear reference.