MCP STDIO Server Transport
The STDIO transport that powers 'praisonai-mcp serve –transport stdio
The STDIO server transport lets praisonai-mcp talk to Claude Desktop, Cursor, and Windsurf over stdin/stdout โ reliably, on every platform.
Quick Start
- Install the host
bash pip install "praisonai-mcp" - Serve over STDIO
bash praisonai-mcp serve --transport stdioWorks on Linux, macOS, and Windows โ including Windows + Python 3.13.
- Point your MCP client at it
json { "mcpServers": { "praisonai": { "command": "praisonai-mcp", "args": ["serve", "--transport", "stdio"] } } }
How It Works
The host reads stdin on a dedicated thread and hands lines to the asyncio loop, so the async pipe API is never touched.
sequenceDiagram
participant Client
participant Stdin as stdin.buffer
participant Reader as mcp-stdio-reader thread
participant Queue as queue.Queue(maxsize=1000)
participant Loop as asyncio loop
participant Server as server.handle_message
participant Stdout as sys.stdout.buffer
Client->>Stdin: JSON-RPC line (bytes)
Stdin->>Reader: read line
Reader->>Queue: put(line) โ backpressure if full
Loop->>Queue: run_in_executor(get)
Queue-->>Loop: line
Loop->>Server: handle_message(parsed)
Server-->>Loop: response
Loop->>Stdout: write(response) + flush
Stdout-->>Client: JSON-RPC responseReading stdin on a background thread โ instead of loop.connect_read_pipe(sys.stdin) โ is why the host runs on Windows ProactorEventLoop + Python 3.13, where the async pipe API raises OSError: [WinError 6] The handle is invalid.
Reliability Guarantees
| Guarantee | What it means |
|---|---|
| Cross-platform | Runs on Linux, macOS, and Windows (including Windows + Python 3.13, previously broken). |
| Malformed input is safe | Non-UTF-8 or invalid JSON becomes a JSON-RPC -32700 parse error; the server keeps running. |
| Bounded memory | The stdin queue is capped at 1000 lines with backpressure, so a fast or hostile client can’t grow memory without limit. |
| Clean shutdown | stop() wakes a reader blocked on idle-but-open stdin, so Ctrl+C and client disconnect never hang. |
A malformed line produces this response, and the transport continues:
{"jsonrpc": "2.0", "id": null, "error": {"code": -32700, "message": "Parse error: ..."}}Crash Recovery
A crashed stdio server respawns on the next call, up to 3 times, and the call that saw the crash is not replayed. See Auto-respawn on crash.
Best Practices
Platform support
STDIO transport runs the same on Linux, macOS, and Windows. On Windows it works under the ProactorEventLoop on Python 3.13 โ no workarounds needed.
Backpressure and queue size
The intake queue is fixed at 1000 lines. When it fills, the reader thread applies backpressure until the loop drains it โ the server stays responsive instead of buffering without limit.
What happens on malformed input
Invalid UTF-8 or bad JSON is reported as a JSON-RPC -32700 parse error. The server logs it to stderr and keeps serving; it never exits on bad bytes.
What happens on client disconnect
When stdin closes (client disconnect) or you press Ctrl+C, stop() enqueues an EOF sentinel that unblocks the reader, so run() exits cleanly without hanging.