What I Learned Building an MCP Server Boilerplate (The Hard Parts Nobody Talks About)

Been heads-down building out an MCP server boilerplate kit for the past few months. Figured I'd share the actual technical lessons, not the "here's why AI agents are the future" takes you can find anywhere. ## The thing that bit me first: tool schema design My initial instinct was to build fat tools. One tool that does a lot. Felt clean from an API design perspective. It was wrong. LLMs call tools more reliably when they're narrow and explicit. A tool called get_user_and_recent_orders_and_preferences fails silently way more often than three separate tools. The model gets confused about intent, passes malformed args, or just picks the wrong tool entirely. The pattern that actually works: // Instead of this get_full_user_context(userId) // Do this get_user(userId) get_recent_orders(userId, limit) get_user_preferences(userId) More surface area, way better reliability. ## State management across tool calls is trickier than it looks MCP is stateless by default. That's fine until your agent needs to do multi-step work where step 3 depends on what step 1 returned. What I ended up doing in the boilerplate was adding a lightweight session context object that tools can read from and write to within a single run. Not persisted, just in-memory scoped to the request lifecycle. Saved me from passing enormous payloads through every tool call. ## Error messages are part of your tool's interface This one is subtle. When a tool fails, the error string goes back to the LLM. If it says Error: undefined the agent usually gives up or hallucinates a fix. If it says User not found. Verify the userId format is a UUID before retrying. the agent actually recovers. Treat your error messages like you're writing them for another developer, because in a way you are. ## What I'd do differently I'd spec out the tool surface area on paper before writing any code. The architecture decisions at that layer ripple through everything else. Building the MCP Server Boilerplate Kit forced me to make all of these mistakes at small scale, which is honestly the best outcome. --- Anyone else building MCP servers or multi-tool agents? Curious what your session/state patterns look like - I've seen a few different approaches and haven't landed on a definitive answer yet.