Three MCP Server Gotchas That Wasted My Week
Everything I wish someone had told me before writing my first production MCP server — stdio framing, tool-name collisions, and the auth model that isn't.
Table of Contents
The Model Context Protocol looks deceptively simple on the first read. Tools in, results out, JSON-RPC on the wire — what could go wrong? Plenty. Here are the three failure modes I hit building the DevFlow MCP server, each of which cost me half a day.
Gotcha 1 — stdio framing silently breaks
MCP over stdio is line-delimited JSON. Sounds trivial — except half the Node libraries you’ll reach for (winston, various loggers, even some transport wrappers) will emit a stray \n mid-message. The host reads a partial JSON, fails, and disconnects. No error in your code. Just silence.
The fix I ended up on: one outbound writer that JSON.stringifys, appends a single \n, and holds a lock during the write. Every other log line goes to stderr. Once I enforced that separation the disconnects vanished.
Gotcha 2 — tool-name collisions across plugins
If you have two MCP plugins installed and both expose a tool called flow_list, the host doesn’t disambiguate. You get the first one, silently. My DevFlow tools kept getting shadowed by a local MCP server I’d forgotten I had running.
Namespace every tool. I switched from flow_list to devflow_flow_list across the board. Verbose, ugly, worth it.
Gotcha 3 — there is no auth model
MCP itself has no notion of auth. Whatever host loads your server can call any tool. That’s fine for a local stdio transport — but the moment you run the server as a network service, you own authentication end-to-end. Token in a header, token in a query string, your problem.
I now assume every MCP server starts stdio-first and only moves to HTTP after I’ve wrapped it in a proxy that enforces a bearer token. The hit is one extra process to manage. The payoff is that I stop writing half-baked auth into the server itself.
What this means in practice
The MCP spec is great. The ecosystem around it is fifteen months old and still finding its rough edges. If you’re starting a server today:
- Use the official SDK rather than rolling your own JSON-RPC layer.
- Prefix every tool with your project’s short name.
- Run stdio until you have a real reason to run HTTP.
Three rules. They would have saved me a week.
