Why does my MCP server run fine in a terminal but refuse to connect?
The client parses everything on your stdout as JSON-RPC. Your log lines are not JSON-RPC.
Suppose someone reports the following. They built an MCP server. They run
uv run my-mcp in a terminal, and it prints its startup banner. No traceback,
exit code 0. Then they point Claude Desktop at it, and the client produces a wall
of schema errors and marks the server as failed.
Nothing crashed. So why won’t it connect?
The short version is that the client is reading stdout, and so is your logger.
A stdio MCP server talks to its client over two pipes. It reads JSON-RPC messages from stdin, and it writes its own to stdout. That is the whole transport. The client sits on the other end of stdout and parses every line that comes out as a JSON-RPC message.
You might think of stdout as the place where a program prints things for a human to read. In a terminal, that’s what it is. But when the client launches your server, nobody is looking at stdout except a parser with very firm opinions about what a line should contain.
Now trace what happens when your server logs something. Maybe it’s a structlog
line, or a dependency announcing “loaded model successfully.” The line goes to
stdout. The client receives it, tries to parse it as protocol, and rejects it:
unrecognized_keys: ["event", "level", "timestamp"]
invalid_value ... path: ["jsonrpc"]
Look at those key names. event, timestamp and level are not JSON-RPC
fields. They are your log fields. The client got your log record where it
expected a response, and it has no way to tell a debug message apart from a
malformed reply. (A plain-text line fails one step earlier, as a JSON syntax
error.) So if you see a burst of invalid_union and unrecognized_keys errors
from a server that starts perfectly in a shell, this is the first thing to check.
How much damage each bad line does depends on the client. The reference TypeScript SDK reports it as an error and skips it, so the real reply can still get through. The spec makes no such promise. It says the server MUST NOT write anything to its stdout that is not a valid MCP message.
This is one of those cases where running the program by hand actively misleads you. In the terminal, the log line lands on your screen and looks harmless. Under the client, the same bytes land in the protocol stream and break it.
So where should the logs go? Stderr. The client doesn’t parse it, which makes it
the right destination for every diagnostic byte your server produces. If you use
structlog, point its logger factory at sys.stderr:
import sys
import structlog
structlog.configure(
processors=[
structlog.processors.add_log_level,
structlog.processors.TimeStamper(fmt="iso"),
structlog.processors.JSONRenderer(),
],
logger_factory=structlog.PrintLoggerFactory(file=sys.stderr), # ← not stdout
)
The last line is the fix. Everything the logger emits now goes to fd 2.
Don’t call print() in any runtime path. A bare print() writes to stdout by
definition. The one you left in an error branch you rarely hit will corrupt the
protocol on the day that branch finally runs. If you really need it, write
print(..., file=sys.stderr), though the logger is the better choice.
Your dependencies count too. A library that prints a banner or a progress bar to stdout poisons the channel just as well as your own code does. Import such libraries with that in mind, and silence the chatty ones.
Okay, so why didn’t the tests catch this? The tests never looked. A typical unit test imports a function and checks its return value. It doesn’t launch the server as a subprocess and read stdout the way a real client does. The bug lives entirely in the integration, and that’s the one place the suite doesn’t go.
The remedy is a small stdio smoke test. Spawn the server as a subprocess, send a
tools/list request the way your protocol revision expects, and assert that every
line that comes back on stdout is clean, parseable JSON-RPC listing the tools you
expect. For revision 2025-11-25 and earlier, that means an initialize request,
then the notifications/initialized notification,
then tools/list. Revision 2026-07-28 removed that handshake:
each request carries its protocol version in _meta, and a server/discover
call up front is optional.
Run it before you tell anyone the server works. If a log line is leaking, the test
fails right away. It also catches import-time crashes and startup failures on an
empty config in the same run.
Postscript: The JSONRenderer in the configuration above has a side effect
on Windows. It serializes with json.dumps, which escapes non-ASCII
characters by default, so
every log line is plain ASCII. Up to Python 3.14,
a piped stderr there uses the ANSI code page,
such as cp1252, while the spec describes stderr output as UTF-8. Python won’t
crash on a stray emoji, because stderr always uses the backslashreplace error
handler,
but an accented character would reach the client as a byte that isn’t valid
UTF-8. Python 3.15 turns on UTF-8 mode by default,
which removes the mismatch, and the escaping still covers older interpreters.
Exercise: When you run the server by hand, print("hello") and
print("hello", file=sys.stderr) both show up in your terminal, and they look
identical. Explain why only one of them breaks the connection when the client
launches the server.
Show an answer
In your terminal, file descriptors 1 and 2 both point at the same tty. Both lines land on your screen, and the only thing reading them is you.
When the client launches the server, fd 2 is inherited or routed to the client’s log, and nobody parses it. fd 1 is different. The client replaces it with a pipe and reads every line on that pipe as a JSON-RPC message. hello isn’t JSON, so the parse fails.