CSE Roadmap

Core tier · about 6 hours · 14 parts

Part 2 of 14 · 2 min read

A transport carries messages; it never changes what they mean

Think of the post van, not the letter. The van carries the letter from one place to another and does not change what it says.

In plain words: a transport is a binding that defines how messages are framed and delivered, how request metadata is carried, how a client cancels an in-flight request, and how a connection ends. Protocol semantics stay identical on every transport, though. A server written once can run over stdio or HTTP without changing what any message means.

A worked example. Over stdio the client launches the server as a subprocess, and messages travel one per line over stdin and stdout. In the example, a tool called chatty has a stray print("DEBUG: looking things up...") left in it by its author. The call still succeeds, but the client now sees an extra line on stdout that is not a valid MCP message at all. A naive client that calls json.loads on every line crashes on a bug that lives entirely in the server. The fix belongs in the server: send logs to stderr, never print to stdout. A well-written client also treats an unparsable line as a diagnostic, not a crash.

That same discipline governs how a server shuts down. The specification's order is close stdin, wait, and only then terminate. The example has three kinds of server, and the client's shutdown ladder gives three different results. One that exits on end of input took about 0.01 s. One that ignores it but responds to a terminate signal took about 0.3 s. One that ignores both took about 0.6 s, killed only at the last step.

The key lines. From code/mini-transport/stdio_client.py:

# from code/mini-transport/stdio_client.py
def close(self, grace: float = 1.0) -> str:
    """Close stdin; wait; terminate; wait; kill. Returns how it ended."""
    if self.proc is None or self.proc.poll() is not None:
        return "already-exited"
    try:
        self.proc.stdin.close()
    except OSError:
        pass
    try:
        self.proc.wait(grace)
        return "exited"
    except subprocess.TimeoutExpired:
        pass
    self.proc.terminate()

Read it as: the method tries the gentlest option first and only escalates on a timeout. Closing stdin is "the only portable" signal a well-behaved server should exit on. The ladder (close, wait, terminate, wait, kill) exists precisely for the servers that do not behave that way, and the three timings above are what that ladder actually costs.

Transport

A transport is a binding: it defines how messages are framed and delivered, how request metadata is carried, how a client cancels a request, and how a connection ends. It never changes what a message means.

Example: the same search tool, called through the same JSON-RPC message, behaves identically whether it travels as a line on stdout or as a POST body over HTTP. The transport decided how the bytes moved, not what the call was asking for.