The MCP stdio transport: newline-delimited JSON-RPC on stdin and stdout.
The transport serves one client that starts the process as a
subprocess. Each line of stdin carries one JSON-RPC message; each
message the server sends is written as one line of UTF-8 text on
stdout. Nothing else may write to stdout: logs and stray prints
belong on stderr (OzMcp.Transport.Stdio.Console prepares the
devices and the Mix task mix oz_mcp.stdio calls it). The transport
holds one session with no id on the wire: the first initialize
creates it, the end of stdin ends it. A request that is not cheap
(tools/call, resources/read, ...) runs in a process of its own,
so a callback that waits for the client does not block the reading of
the next lines; the cheap methods (initialize, ping,
notifications, the answers of the client) run in the transport
process, in the order of the lines.
Authorization is not used on stdio: the client owns the process of
the server. A server that declares an authorization block runs
open — no principal, no scope check, no filter on the lists (see
OzMcp.Auth).
From any code, run/2 runs a server on stdio and blocks until the
connection ends; start_link/1 starts the transport process alone,
for a test or an entry of its own. The lifecycle, the refusals, the
ordering of the lines and the limits are in the guide
stdio transport.
The end of the connection
- The end of stdin starts a drain: the transport waits for the
requests in flight, up to
:drain_timeout_ms(default 1000), then it ends the session and stops normally. - A failed write to stdout, or a failure of the reader of stdin (a
readfunction that raises, or one that returns{:error, reason}), stops the transport with an error: no answer can reach, or no line will ever arrive. - The transport monitors the session process. When it stops (a
crash, for example), the transport writes an error on stderr and
stops with
{:shutdown, :session_lost}. The Mix task then exits with code 1 and a message that names the case. - A request that gets
-32001for the session of the connection (the instance lost the session) writes its error line first and the transport then stops with{:shutdown, :session_lost}: each later request would get the same error.
Summary
Functions
Returns a specification to start this module under a supervisor.
Runs a server on stdio and blocks until the connection ends. The
options and the result values are in the guide
stdio transport; the caller
prepares the :read and :write functions, so run/2 itself
changes no global state. When an instance with the name :instance
runs, the transport joins it; when it does not run, run/2 starts
one in the stdio mode, with the server module and :server_opts.
Functions
@spec child_spec(keyword()) :: Supervisor.child_spec()
Returns a specification to start this module under a supervisor.
See Supervisor.
Runs a server on stdio and blocks until the connection ends. The
options and the result values are in the guide
stdio transport; the caller
prepares the :read and :write functions, so run/2 itself
changes no global state. When an instance with the name :instance
runs, the transport joins it; when it does not run, run/2 starts
one in the stdio mode, with the server module and :server_opts.
@spec start_link(keyword()) :: GenServer.on_start()