# `OzMcp.Transport.Stdio`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/transport/stdio.ex#L1)

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](guides/runtime/stdio_transport.md).

## 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
    `read` function 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 `-32001` for 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.

# `child_spec`

```elixir
@spec child_spec(keyword()) :: Supervisor.child_spec()
```

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `run`

```elixir
@spec run(module(), keyword()) :: :ok | {:error, term()}
```

Runs a server on stdio and blocks until the connection ends. The
options and the result values are in the guide
[stdio transport](guides/runtime/stdio_transport.md); 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`.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*
