What is STDIO Transport?
Updated on
STDIO Transport is a Model Context Protocol transport in which an MCP client launches a server subprocess, writes protocol messages to the server's standard input, and reads protocol messages from its standard output.
Quick Facts
| Specification | Official Specification |
|---|
How It Works
Preserve the newline-delimited protocol stream
The MCP STDIO specification delimits messages with newline characters and forbids embedded newlines inside a message. JSON strings may contain an escaped \n, but pretty-printed multi-line JSON and log text on stdout corrupt framing. Both sides should serialize one complete JSON-RPC message, append one newline, flush promptly, validate a maximum line size, and reserve stderr for logs that the client may capture separately.
Correlate JSON-RPC independently of process I/O
Requests carry an ID and require a response with the same ID; notifications omit an ID and receive no response. Implementations should maintain an in-flight map because responses need not be inferred from line position. Cancellation is a protocol notification and therefore cooperative: it does not guarantee that work stopped. Transport readers must continue processing valid responses and notifications while requests are outstanding.
Own shutdown, restart, and the local trust boundary
The client launches the command with an explicit executable, arguments, environment, and working directory. For orderly shutdown it closes the server's stdin, waits for exit, then terminates the process if it does not stop. A restart creates a new process and loses in-flight state unless the application layer can retry safely. Avoiding a network port reduces remote exposure, but the child still runs with local filesystem, environment, and process permissions granted by the host.
Key Characteristics
- Uses a client-managed child process rather than a network listener
- Frames each UTF-8 JSON-RPC message as exactly one newline-delimited line
- Reserves server stdout for protocol messages and stderr for diagnostics
- Uses JSON-RPC IDs for request-response correlation and no ID for notifications
- Requires explicit cancellation, EOF, exit, timeout, and forced-termination handling
- Inherits a local security boundary defined by executable, environment, and OS permissions
Common Use Cases
- Running a user-scoped MCP filesystem or repository server from a desktop host
- Connecting an IDE agent to a local tool without opening a listening port
- Packaging a command-line integration that the MCP client can launch on demand
- Testing protocol framing, cancellation, and process failure in a local harness
- Distributing a local server whose executable and permissions are centrally controlled
Example
Loading code...Frequently Asked Questions
How are MCP messages framed over STDIO?
Each message is a complete UTF-8 JSON-RPC object followed by a newline. A message must not contain a raw embedded newline, although a JSON string may encode one as `\n`. Do not use pretty-printed JSON on the wire, set an explicit maximum line size, and flush each completed message.
Can an MCP server write logs to stdout?
No. In STDIO Transport, server stdout is reserved for valid protocol messages. A banner, debug print, progress bar, or library log can make the client parse an invalid JSON-RPC line and terminate the session. Send diagnostics to stderr and keep protocol serialization on a dedicated writer.
Is STDIO Transport more secure than HTTP?
It avoids a listening network endpoint, but that is not a complete security model. The launched executable receives the local privileges, environment variables, working directory, and inherited resources allowed by the host. Pin trusted commands, minimize the environment, restrict filesystem access, and still authorize MCP operations.
What happens to in-flight requests when a STDIO server exits?
The byte stream ends and unresolved requests fail unless the client defines a higher-level retry policy. Starting a new process does not restore protocol state automatically. Retry only operations known to be idempotent or protected by application-level request keys, and surface uncertain side effects to the caller.
When should MCP use HTTP instead of STDIO?
Use STDIO when one local client owns one local subprocess. Use Streamable HTTP when the server must be reached across a network, serve independently of the client process, or integrate with network authentication and deployment controls. Transport choice does not alter the capabilities exposed by MCP.