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

1. Install the host

   pip install "praisonai-mcp"
   
2. Serve over STDIO

   praisonai-mcp serve --transport stdio
   

   Works on Linux, macOS, and Windows — including Windows + Python 3.13.

3. Point your MCP client at it

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

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

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: ..."}}

---

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

PraisonAI MCP Server

Heavy MCP host reference and client setup.

MCP Transports

All MCP transport mechanisms compared.

praisonai-mcp Package

Standalone host package guide.

Windows SDK Quickstart

Run the MCP host on Windows.