DEV BOX

'26/11/17 UPDATE

MCP / STDIO TRANSPORT / FIELD NOTES

What breaks when you add one console.log to an MCP server on stdio?

On an MCP server connected over stdio, stdout is the channel the client reads replies from, so even one console.log line lands there as a non-JSON line. A demo server and client on Node.js v24.21.0, run with console.log, indented JSON and console.error, show what breaks; the note also sets out the stdio rules of MCP specification version 2026-07-28 and what to fix.

When an MCP server is connected over stdio, the server process's stdout is not a screen for people. It is the channel the client reads replies from, and a console.log line added for debugging goes down that same channel. A small server and client written with nothing but Node.js were run four ways: a normal reply, one console.log line, indented JSON, and the fix with console.error. By the end you will know what to look for in your own server code and how to check it after the fix.

On the stdio transport, stdout is the message channel

On the stdio transport the client launches the MCP server as a subprocess. The client writes requests to the server's stdin, and the server writes replies to its stdout. Responses and notifications all share this one channel; there is no separate stream per request.

The stdio transport page of the MCP specification, version 2026-07-28, sets a few rules for that channel.

  • Each message is a single JSON-RPC request, notification or response, and messages are delimited by newlines. A message MUST NOT contain embedded newlines.
  • The server MUST NOT write anything to its stdout that is not a valid MCP message. The client, likewise, must not write anything but MCP messages to the server's stdin.
  • The server MAY write UTF-8 strings to stderr for any logging, such as informational, debug and error messages. The client MAY capture, forward or ignore stderr, and SHOULD NOT assume that output on stderr means an error.

In Node.js the global console is set up to write to process.stdout and process.stderr, and console.log writes to stdout. So a console.log inside an MCP server mixes exactly what the rule forbids, something that is not an MCP message, into the message channel. The server code does not even have to call it: if another module running in the same process calls console.log, it goes to the same stdout.

DEV NOTES

The three streams of the stdio transport

The client launches the server as a subprocess and talks over its standard streams

  • stdin: client to server

    {"jsonrpc":"2.0","id":2,…}

    • Requests and notifications, one per line
    • MUST NOT write anything but MCP messages
    • The client does not write responses
  • stdout: server to client, messages only

    JSON.stringify(msg) + '\n'

    • Responses and notifications only, one per line
    • Messages MUST NOT contain newlines
    • MUST NOT write anything but MCP messages
    • console.log, info and debug land here
  • stderr: the server's logs

    console.error('got request', …)

    • Any logs, as UTF-8 strings (MAY)
    • The client MAY capture, forward or ignore it
    • SHOULD NOT treat it as a sign of error
    • console.error and warn land here

Rules from the stdio transport page of the MCP specification, version 2026-07-28 (checked 2026-11-09). The stream of each console method was checked by running Node.js v24.21.0.

For an MCP server on stdio, stdout is the stream the client reads replies from. Logs belong on stderr.

A server and a client built with Node.js alone

No SDK was used. To see only what happens on the channel, two files were written by hand.

  • server.mjs reads stdin line by line and answers tools/list and tools/call (an add tool). Both replies carry in their result the resultType that version 2026-07-28 requires in every result, and otherwise follow a trimmed version of the examples on the specification's tools page. It has no server/discover, no _meta checks and no capabilities, so it is not a full MCP server, only a demo for watching the channel. A command-line argument picks one of four modes.
  • client.mjs launches the server as a subprocess and writes two requests to its stdin, one per line (id 1 tools/list, id 2 tools/call). It cuts stdout at every newline, runs JSON.parse on each line, and matches the id of each message it reads to the request it sent. It prints stderr separately, prefixed with stderr:. After one second it closes the server's stdin and counts matched replies and parse errors.

The four modes: ok writes each reply as one line with JSON.stringify(msg), and log prints console.log('got request', req.method) before each reply. pretty writes each reply indented with JSON.stringify(msg, null, 2), and stderr prints the same line as log, but with console.error. Everything ran on 2026-11-09 on macOS 27.0.1 with Node.js v24.21.0, with no packages installed.

Terminal output. node client.mjs ok gets reply id 1 (tools/list) and id 2 (tools/call) on stdout lines 1 and 2: replies matched 2/2, parse errors 0. node client.mjs log shows parse error: Unexpected token 'g', "got reques"... is not valid JSON on stdout lines 1 and 3 and the two replies on lines 2 and 4: replies matched 2/2, parse errors 2. node client.mjs pretty shows line 1 Expected property name or '}' in JSON, line 2 Unexpected non-whitespace character after JSON, line 22 JSON but not a reply it is waiting for, "b", and lines 41 and 42 parse errors on '}': replies matched 0/2, parse errors 41, no reply for id 1, 2. node client.mjs stderr shows stderr: got request tools/list and stderr: got request tools/call, then the two replies on stdout lines 1 and 2: replies matched 2/2, parse errors 0.
Actual output of the same demo client against the server in four modes. One console.log line put a non-JSON line between the replies, and indented JSON left no reply matched. With console.error, stdout carries only the replies.

One console.log line: a non-JSON line between the replies

In log mode the client received four stdout lines. Lines 1 and 3 were got request tools/list and got request tools/call, and JSON.parse failed on them with Unexpected token 'g'. This demo client is written to skip a line it cannot parse and read the next one, so it still matched both replies.

Whether to skip or to stop is the client's choice. With the same client changed to stop reading at the first bad line and kill the server (--strict), it left every later line unhandled, replies included, and matched no reply (0/2). What real clients such as Claude Code, Claude Desktop or the official SDKs do with such a line was not checked; Claude Code and Claude Desktop would have needed their settings changed, and the SDKs a package install, so they were left out of the experiment. Either way the server did something the specification forbids, and the outcome depends on how the client treats the line.

Indented JSON: one reply split across many lines

pretty mode printed no log line at all, and the result was worse. The two replies became 42 stdout lines, and the client hit a parse error on 41 of them. A line holding only {, or a line ending in a comma such as "jsonrpc": "2.0",, is not JSON on its own. Both replies did arrive, but in fragments, so neither id 1 nor id 2 was matched (0/2).

Line 22 did parse. The last element of the tool list's "required": ["a", "b"] array, "b", sat alone on its line, and that is a valid JSON string. A fragment that happens to be valid JSON is still not a message. This demo client checks jsonrpc and the id as well, so it did not take the line for a reply.

A reply with a newline inside a string is not a problem. The add tool's result text contains a newline, and written with JSON.stringify(msg) and no indent argument, that newline was escaped as the two characters \n and the whole message came out on one line. Written with JSON.stringify(msg, null, 2), the same reply took 14 lines. The example messages in the specification are spread over several lines, but on the stdio channel each one must go on a single line.

Terminal output. node client.mjs log --strict prints a parse error for stdout line 1, then strict: closing the connection, then replies matched 0/2, parse errors 1, no reply for id 1, 2. Piping one tools/call request line into node server.mjs ok prints one line: {"jsonrpc":"2.0","id":2,"result":{"resultType":"complete","content":[{"type":"text","text":"sum: 5\ninputs: 2, 3"}],"isError":false}}. The same request into node server.mjs pretty, counted with wc -l, gives 14. node console-streams.mjs 2>/dev/null prints log, info and debug; node console-streams.mjs >/dev/null prints warn and error.
Actual runs: a demo client that stops at the first bad line, the line count of a one-line reply and an indented reply, and the streams five console methods write to.

Logs go to stderr: the result with console.error

In stderr mode the same two log lines arrived separately as stderr:, and stdout carried only the two reply lines, with zero parse errors. The two streams flow independently, and in the 2026-11-09 run the stderr lines were printed before the stdout lines. To match logs to replies later, it helps to include the request id in each log line.

Avoiding console.log alone is not enough. In Node.js, console.info and console.debug are aliases of console.log and go to stdout, while console.warn is an alias of console.error and goes to stderr. In the run, throwing stderr away left log, info and debug; throwing stdout away left warn and error.

Some methods are not aliases. Run the same way, console.dir, console.count, console.timeEnd, the label of console.group and console.table also wrote to stdout; of the methods run alongside them, only the message of a failed console.assert and console.trace went to stderr. The Node.js v24 documentation likewise says console.dir, console.count, console.timeEnd and console.timeLog print to stdout and console.trace to stderr.

MCP also has a Logging feature, in which the server sends logs to the client as notifications/message notifications. Those are MCP messages, so sending them on stdout does not break the stdio rules, but they cannot be sent at any time. The Logging page of the same version says the server MUST NOT send them for a request whose _meta lacks io.modelcontextprotocol/logLevel. The feature is also marked deprecated as of version 2026-07-28. New implementations SHOULD NOT adopt it, and existing ones SHOULD move to stderr logging for stdio, or to OpenTelemetry for structured observability.

What to find and fix in your server

  • Keep one place that writes to stdout. Only the function that sends messages calls process.stdout.write(JSON.stringify(msg) + '\n'), and it passes no indent argument.
  • Search the code for console.log, console.info, console.debug, console.dir, console.dirxml, console.table, console.count, console.timeEnd, console.timeLog, console.group, console.groupCollapsed and any process.stdout.write outside that function, and send them to console.error or stderr instead.
  • After the fix, feed in one request line the server answers, throw stderr away and look at stdout. Every line should pass JSON.parse and be a message carrying "jsonrpc": "2.0", and there should be no lines other than replies and notifications.

The rules here follow version 2026-07-28 of the MCP specification; the wording of earlier versions was not rechecked for this note. The run results are the behaviour of a hand-written demo client. For an MCP server on stdio, leave one piece of code that writes to stdout, the one that sends messages, and send every other line of output to stderr.

THE END
RSS feedBack to the library
COMMENTS BOX

Add your perspective.

Share a question, another approach, or something you have tried.

Newest first

Checking sign-in…

Loading comments…