Transports I: stdio

The famous trap: print()

On stdio, stdout is the protocol channel. Think of an old telegraph line, where everything on the wire gets read as the message. The server must never write anything to stdout that isn't a valid MCP message. Now picture a tool function with a friendly debug line:

def get_campaign(campaign_id):
    print("looking up", campaign_id)        # writes to stdout!
    return fetch(campaign_id)

That stray text lands in the middle of the host's message stream. The host tries to parse looking up cmp_103 as JSON, fails, and typically drops the connection. The server "works" when you test the function directly, and breaks the moment it runs inside a host.

The fixes:

• Log to stderr: print(..., file=sys.stderr), or use logging, which writes to stderr by default.
• Defend in depth: while running handlers, redirect anything they print (including what libraries print) to stderr. The exercise does exactly this.

In plain words: stdout is for protocol messages and nothing else. Everything meant for humans goes to stderr.

The loop

A stdio server is a loop, like a clerk working through an in-tray:

1. Read one line from stdin. End of input (EOF) means the host closed the pipe: exit cleanly.
2. Skip blank lines.
3. Dispatch the message (the dispatcher from two lessons ago).
4. If there's a reply, write it as one line to stdout, then flush, so it leaves the buffer now. A buffer holds output until there's enough to send, like a mail carrier waiting for a full bag. Flushing sends what's there.

Real servers handle several requests at once, so replies can go out in a different order from the requests. The ids match them up.

import io, json, sys

def dispatch(line):
    msg = json.loads(line)
    if "id" not in msg:
        return None
    if msg["method"] == "tools/list":
        return {"jsonrpc": "2.0", "id": msg["id"], "result": {"resultType": "complete", "tools": []}}
    return {"jsonrpc": "2.0", "id": msg["id"], "error": {"code": -32601, "message": "Method not found"}}

stdin = io.StringIO(
    '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}\n'
    '\n'
    '{"jsonrpc": "2.0", "method": "notifications/cancelled", "params": {"requestId": 1}}\n'
    '{"jsonrpc": "2.0", "id": 2, "method": "prompts/list", "params": {}}\n'
)
stdout = io.StringIO()
for line in stdin:                    # reading stops at end of input (EOF)
    if not line.strip():
        continue
    reply = dispatch(line)
    if reply is not None:
        stdout.write(json.dumps(reply) + "\n")
        stdout.flush()

print(stdout.getvalue())

Cancellation and shutdown

• Cancellation. stdio has one shared channel, so a client cancels a request by sending a notification: notifications/cancelled with the requestId. The server should stop that work and send nothing more for that id. A reply that was already on its way may still arrive, and clients ignore it.
• Shutdown. The client closes the server's stdin and waits. A good server exits promptly at end of input. If it doesn't, the client escalates, the way a bar does at closing time: a polite SIGTERM, then a forced SIGKILL.
• Crashes. If the server dies, the host restarts it. Modern MCP is stateless, so nothing is lost except the requests that were in flight, and those can be retried.

The same framing (one JSON message per line) works over any reliable two-way byte stream, such as a local socket. Only the subprocess parts, like startup and stderr, are specific to stdio.

The bugs that only stdio has

print() breaks everything. Stdout belongs to the protocol. One stray print("got here") puts text in the stream where the client expects JSON, and the connection fails with a confusing parse error. It's the first thing to check when a local server dies right after starting. Send your debug output to stderr instead:

import sys

print("debug: got here", file=sys.stderr)

Pretty-printed JSON breaks framing. Each message must fit on one line, since the line break is what separates messages. json.dumps(msg, indent=2) spreads one message over many lines, and the client tries to parse each line on its own. Use plain json.dumps(msg), which contains no line breaks.

Flush after every message. Python often holds output in a buffer when it's writing to a pipe, not a screen. So your reply can sit there while the client waits, like a letter in your bag you forgot to mail. Both sides hang with no error. Call sys.stdout.flush() after each write, or print with flush=True.

Local servers don't need OAuth. A stdio server runs on the user's own machine, started by their host. It reads credentials from environment variables, set in the host's config. Adding a browser login flow to it only creates something more to go wrong.