Serving a human-readable HTML page when browsers hit a GET /mcp endpoint cut support tickets sharply for an MCP server deployment.
Key Takeaways
Raw 401 JSON on mcp.acme.com/mcp caused users to file support tickets thinking the server was broken, not misconfigured on their client.
Fix: detect Accept: text/html without application/json or text/event-stream and return an explanation page instead of a JSON error.
The alternative, packaging connector plugins for every LLM client, is a slow whack-a-mole problem that scales poorly with enterprise self-hosted clients.
Author considers MCP a poor specification; the UX gap between spec authors and real onboarding users drove this workaround.
Hacker News Comment Review
Consensus: the Accept-header content negotiation trick is not really a hack; it is standard HTTP behavior for returning alternative representations to different clients.
One commenter raised a sharper UX objection: if the MCP URL is rendered as a clickable hyperlink in onboarding docs, the real fix is a copy-to-clipboard monospaced box, not a 401 handler.
Commenters noted a secondary benefit: when an agent pastes the URL directly, the HTML explanation page gives the agent useful text to relay back to the user.
Notable Comments
@stavros: argues the root cause is presenting MCP URLs as clickable links; a non-clickable copy box would prevent the confusion upstream.
