I've built a handful of MCP servers. Here's what separates a good one from a demo.

This year I've built more MCP servers than I meant to, across three pretty different shapes: vellum : a self-hosted server over a folder of markdown, so my agent has a memory that's just files I own. (Open source, MIT.) Metrifyr : a marketing-data server that puts GA4, Search Console, AdSense and Tag Manager behind one connection. A read-only gateway over a company's internal user-data stack, federating half a dozen internal services behind one audited MCP surface. Personal, product, enterprise. Totally different data, totally different stakes. And yet the things that made each one good , versus a flashy demo that falls over the moment a real agent uses it in anger, were the same every time. Here are the seven that keep recurring. 1. Every tool you expose is a tax on the agent's context This is the one nobody warns you about. Every tool definition (name, description, JSON schema) gets loaded into the model's context on every single request , whether or not it's ever called. Twenty tools of boilerplate and the agent is reading pages of plumbing before it touches your data. So the design pressure runs the opposite way from a normal API: fewer, broader tools beat many narrow ones. vellum has 15 core tools and I fought to keep it there. If a tool doesn't earn its slot in the context window on most requests, it shouldn't be a tool. 2. Tools are for acting. Resources are for reading. The corollary to #1. Most servers expose everything (including "read this thing") as a tool. But MCP has a better primitive for reading: resources . In vellum, every note is a resource at a stable URI ( vellum://note/projects/x.md ). The agent attaches a document by reference instead of spending a tool round-trip to fetch it, and it can subscribe to that URI and get told the moment the note changes. Reading through a resource costs no tool definition. Reading through a tool costs one on every request. Use the right primitive. 3. Fail closed on auth, fail open on limits A token with no grants