How not to write an MCP server, lessons from the trenches

This session is a developer's diary of the hard lessons I learned building an effective MCP server. My first wrong turn was the naive one: wrapping my API as tools and calling it done. Over many iterations my MCP evolved from a context polluter into a genuinely useful toolset. Along the way I tried a Hypermedia approach to the API design, a bit of prompt injection, and learned some design principles the hard way.

We're used to designing for scripts and developers: transactional, contract-driven interfaces built for efficiency. None of that is what an autonomous agent needs. It arrives fresh each session, learns your tools from their descriptions alone, and gives up after a few failed attempts unless you give it a reason not to.

Among the lessons: why dumping data backfires (more context makes it worse), why exposing a whole API floods the model's context window, why granularity is a Goldilocks problem, and why descriptions should sell intent, not functionality. We'll also step back to a prior question: when an MCP server makes sense at all, versus a skill or a CLI the agent can just call.

My hope is to shorten the learning curve and help you skip a few wrong turns I didn't. This topic is highly relevant to any developer in modifying his current application for this use case or generating new APIs.