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.

Diagram

๐Ÿ“‹ MCP Client

๐Ÿ“ฅ stdin
byte lines

๐Ÿงต mcp-stdio-reader
thread

๐Ÿ“ฆ bounded queue
maxsize 1000

โš™๏ธ asyncio loop

๐Ÿค– server handler

๐Ÿ“ค stdout buffer

Quick Start

  1. Install the host
    bash
    pip install "praisonai-mcp"
  2. Serve over STDIO
    bash
    praisonai-mcp serve --transport stdio

    Works on Linux, macOS, and Windows โ€” including Windows + Python 3.13.

  3. 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.

Diagram
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 response

Reading 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

GuaranteeWhat it means
Cross-platformRuns on Linux, macOS, and Windows (including Windows + Python 3.13, previously broken).
Malformed input is safeNon-UTF-8 or invalid JSON becomes a JSON-RPC -32700 parse error; the server keeps running.
Bounded memoryThe stdin queue is capped at 1000 lines with backpressure, so a fast or hostile client can’t grow memory without limit.
Clean shutdownstop() 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:

json
{"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.


Related