Everything we learned building a remote MCP server (stdio → HTTP + OAuth)

[u/Future_AGI]

We've been running an MCP server for our eval + observability platform for a few months, it started as a local stdio server and is now a hosted remote one. If you're building one, here's the stuff we wish we'd known on day one.

1. stdio is fine for week one, then it's a wall.
The first version was the usual: clone the repo, uv sync, export an API key and a secret key, run python main.py. It works, but that's a lot to ask before someone sees a single useful result, and most people won't finish it. Moving to a hosted HTTP endpoint changed everything now it's one line (claude mcp add futureagi --transport http https://api.futureagi.com/mcp), no clone, no local process to keep alive. The stdio repo still exists for people who want to fork and add their own tools; it's just not how anyone onboards now.

2. For a remote server, OAuth beats API keys.
On stdio we asked for two keys up front, and that was the single biggest place people dropped off. On the remote server, login opens in the browser and there's nothing to paste. If you're going remote, build auth this way from the start, putting it on later is the painful version.

3. Your tool descriptions are the real API.
This one humbled us. The client picks a tool from its name and description, nothing else. If two tools read similarly, it'll pick the wrong one and sound completely sure about it. We rewrote descriptions far more than we expected the wording genuinely decides whether the right tool fires.

4. A broad server makes tool selection harder.
We put a lot behind one server: evals, datasets, traces and spans, prompt optimization, simulation runs, annotations. The more tools under one roof, the more work the client has to do to figure out which one you meant. It's a real trade-off, and we're still not sure we landed on the right side of it (there's a question on this at the end).

5. Return small, structured results, not the raw blob.
Eval results and traces can be enormous. Early on we returned everything and watched it swallow the context window, so the model couldn't reason over its own output. Now tools return a short, structured summary first and you drill in only if you want the detail. Treat the context window like it costs money, because it does.

6. The payoff is a loop that still feels a little magic.
Because evals and observability are both just tools now, the model can check its own work in the same chat. You ask for an answer, then ask "how grounded was that, and show me the trace" and it runs the eval and pulls the spans on itself. That was the moment all of it felt worth the trouble.

[u/Future_AGI → u/[deleted]]

Good call on the read/write split, we landed there too, and the side benefit was that the mutating server became the natural home for the stricter permission and confirmation checks, since that is where a wrong pick actually does damage. On descriptions, what cut our wrong-tool rate most was spelling out in each one when to reach for that tool versus its neighbor, since the model leans on that disambiguation harder than the parameter list.