A stdio server behaves perfectly when run by hand in a terminal but drops its connection under the host within a second. Logs show a multi-line JSON blob the server pretty-prints for readability. Where is the fault?

The principle — Two rules govern this transport's output, and a server can satisfy one while breaking the other.

Why the key is correct — The framing rule is the one being broken: messages are delimited by newlines, and MUST NOT contain embedded newlines. A pretty-printed object is one logical message spread over many lines, so the reader sees the first line as a truncated message and each following line as a new one that makes no sense. Working by hand proves nothing here, because a terminal renders the blob for a person rather than parsing it as frames. The second rule explains why the failure is total rather than cosmetic — the server MUST NOT write anything to its stdout that is not a valid MCP message — and the remedy is the stream that exists for readable text: the server MAY write UTF-8 strings to stderr for any logging purposes including informational, debug, and error messages.

Why the others are wrong — The host's line-by-line reading is the specified framing, not a strict interpretation of it. Valid JSON is not sufficient when the frame is a line. And redirecting to a file solves it by accident while ignoring the stream provided for the purpose.

Remember this — One message, one line. Everything human-readable belongs on the other stream. The general shape of this bug is worth recognising on sight: a program that behaves differently under a parent process than it does under a terminal is almost always emitting something for a human on a channel a machine is reading.

Sources — MCP first-party documentation.