MCP Server Stdout Bug: What I Actually Found
Dozens of posts published in the last few months tell you that a stray console.log in an MCP server will break it, because stdio MCP servers can only write JSON-RPC messages to stdout. I tested that claim against the current @modelcontextprotocol/sdk (1.32.2) instead of repeating it, and it's only half right. A full line of stray text on stdout does not break anything in this SDK. A stray write with no trailing newline does, and it fails silently with no error, which is the more dangerous version of this bug.
My angle: this exact topic is covered by at least fifteen posts right now, and they all give the same fix without testing whether the bug still reproduces on the current SDK. I built a minimal server, broke it three different ways, and read the SDK's own source to see why two of the three didn't actually break it.
What the MCP spec says, and what I tested
The Model Context Protocol's stdio transport says a server "must not write anything to its stdout that is not a valid MCP message." The usual claim is that a console.log call, or any debug print, corrupts the stream and the host reports something like "no tools" or a connection error.
I wrote a server with the official TypeScript SDK, registered one tool, and called it from a client I wrote with the same SDK:
// server-broken.js - a minimal MCP server with ONE bug: a console.log call
const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
console.log("Server starting up..."); // stray stdout write, supposedly breaks the protocol
const server = new McpServer({ name: "demo", version: "1.0.0" });
server.registerTool("ping", { description: "replies pong", inputSchema: {} }, async () => ({
content: [{ type: "text", text: "pong" }],
}));
server.connect(new StdioServerTransport());
Connecting a real MCP client to it and calling tools/list, then tools/call:
--- broken server, tools/list ---
RESULT: OK, tools = [ 'ping' ]
--- broken server, tools/call ---
CALL RESULT: {"content":[{"type":"text","text":"pong"}]}
It worked. No error, no missing tools. I also moved the console.log inside the tool handler itself, so it fires in the middle of a live request, and got the same clean result.
Why it didn't break: reading the SDK's buffer
The SDK's stdio transport reads stdout line by line and tries to parse each line as JSON-RPC. Here is the relevant part of ReadBuffer, from node_modules/@modelcontextprotocol/sdk/dist/cjs/shared/stdio.js in the installed package:
readMessage() {
if (!this._buffer) return null;
const index = this._buffer.indexOf('\n');
if (index === -1) return null;
const line = this._buffer.toString('utf8', 0, index).replace(/\r$/, '');
this._buffer = this._buffer.subarray(index + 1); // <- advances past the line first
return deserializeMessage(line); // <- then tries to parse it
}
And the loop that calls it, from client/stdio.js:
processReadBuffer() {
while (true) {
try {
const message = this._readBuffer.readMessage();
if (message === null) break;
this.onmessage?.(message);
} catch (error) {
this.onerror?.(error); // no-op if nothing set this handler
}
}
}
The buffer is advanced past a line before that line is parsed, so a bad line gets consumed either way. If JSON.parse throws on it, the error goes to onerror, which does nothing unless the host explicitly wired a handler to it. The loop just continues to the next line. A single stray line is quietly thrown away, not fatal.
What actually does break it
I tried one more variant: writing to stdout with no trailing newline right before the SDK's own handshake output.
// server-broken3.js - a write with no trailing newline, right before the SDK starts
process.stdout.write("partial-no-newline-");
const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
const server = new McpServer({ name: "demo", version: "1.0.0" });
server.registerTool("ping", { description: "replies pong", inputSchema: {} }, async () => ({
content: [{ type: "text", text: "pong" }],
}));
server.connect(new StdioServerTransport());
RESULT: TIMEOUT / NO RESPONSE
This hangs. The stray text has no newline, so the buffer's first indexOf('\n') lands at the end of the SDK's own first JSON-RPC message instead of at the end of my junk text. The two get concatenated onto what the parser sees as a single line, JSON.parse fails on the combined garbage, and the message is thrown away the same way a clean stray line is, except this time it was a real protocol message, not junk. The client has no idea anything was sent and waits until it times out. No error, no log, nothing to grep for.
What to take from this if you're building an MCP server
- A log line that ends in its own newline before your server starts is not the real danger with the current SDK. Clean it up anyway, because the spec forbids it and a future SDK version or a different host's parser may not be this forgiving.
- The real danger is any
process.stdout.write()without a trailing newline, or output written mid-stream without one, landing next to a real protocol message. That failure mode is a silent hang, not a visible error, which makes it far worse to debug. - Send all your own logging to stderr. In Node.js, that means
console.errorinstead ofconsole.log, and watching for dependencies that write to stdout directly rather than throughconsole.log(dotenvhas done this in some versions, for example). - I did not test the official Python SDK's behavior here. Its transport may use a different buffering strategy, so do not assume this result carries over.
- If you maintain tooling, catching a bare
process.stdout.writecall in CI with a lint rule is worth it precisely because this bug produces no error message when it hits a host that, unlike my test client, ignoresonerrorthe same way.
Frequently Asked Questions
Does a console.log really not break an MCP server?
With the official @modelcontextprotocol/sdk (1.32.2) over stdio, a complete line of stray stdout text did not break tools/list or tools/call in my test. The bad line is parsed, fails, and is silently discarded. I did not test every SDK version or every host, so don't take this as true everywhere.
So why do so many posts say it breaks everything?
Possibly because older SDK versions, hand-rolled JSON-RPC parsers, or specific hosts handle a parse failure differently, for example by closing the connection instead of discarding one line. I can't verify what any of those posts actually tested, since none of the ones I read showed their own reproduction.
What's the actual failure mode I should watch for?
A write with no trailing newline landing next to a real protocol message. In my test, this caused a silent timeout with no error on either side, which is harder to debug than a visible crash.
What's the fix?
Write all logs to stderr, not stdout. In Node.js, use console.error. Check any dependency that might write to stdout directly.
Next step
If you maintain an MCP server, grep your code and your dependencies for process.stdout.write and console.log, and move anything that is not a protocol message to stderr. Then test it the way I did here: run a real client against your server and watch for a silent hang, not just a crash.
Last checked: November 15, 2026, by running the tests shown above against @modelcontextprotocol/sdk 1.32.2 on Node.js. Results may differ on other SDK versions or hosts.
Related posts
Exponential Backoff for OpenAI API Calls
How to implement exponential backoff with jitter for OpenAI API calls in Node.js, and why queue concurrency matters more than your retry formula.
pgvector vs Pinecone for Node.js Embeddings
pgvector vs Pinecone for Node.js apps: when Postgres vector search beats a dedicated vector database, with real code and a clear recommendation.
Stream OpenAI API Responses in Node.js with SSE
Learn how to stream OpenAI API responses in Node.js using Server-Sent Events, with real Express code and the mistakes that break streaming in production.
Fix OpenAI API Rate Limit Errors in Node.js
Get 429 rate_limit_exceeded errors from the OpenAI API in Node.js? Here is the real fix: exponential backoff, retry-after handling, and concurrency limits.
0 Comments
No comments yet — be the first to share your thoughts.