How to fix stdio transport issues with MCP

1// TypeScript — the rule
2// NEVER use these in MCP stdio servers:
3console.log("anything");         // writes to stdout — BREAKS MCP
4process.stdout.write("data");    // writes to stdout — BREAKS MCP
5
6// ALWAYS use these instead:
7console.error("anything");       // writes to stderr — safe
8process.stderr.write("data");    // writes to stderr — safe
9
10# Python — the rule
11# NEVER use these:
12print("anything")                # writes to stdout — BREAKS MCP
13sys.stdout.write("data")         # writes to stdout — BREAKS MCP
14
15# ALWAYS use these instead:
16print("anything", file=sys.stderr)  # writes to stderr — safe
17sys.stderr.write("data")            # writes to stderr — safe
18logging.info("anything")            # safe IF configured for stderr

1// Add PYTHONUNBUFFERED to your host config
2{
3  "mcpServers": {
4    "python-server": {
5      "command": "uvx",
6      "args": ["my-mcp-server"],
7      "env": {
8        "PYTHONUNBUFFERED": "1",
9        "API_KEY": "your-key"
10      }
11    }
12  }
13}
14
15# Alternative: use python -u flag for unbuffered mode
16{
17  "mcpServers": {
18    "python-server": {
19      "command": "python3",
20      "args": ["-u", "server.py"]
21    }
22  }
23}

1// Node.js — intercept stdout to find pollution sources
2const originalWrite = process.stdout.write.bind(process.stdout);
3process.stdout.write = (chunk: any, ...args: any[]) => {
4  // Log the source with a stack trace
5  const stack = new Error().stack?.split("\n").slice(2, 5).join("\n");
6  console.error(`\n[STDOUT POLLUTION DETECTED]`);
7  console.error(`Data: ${String(chunk).substring(0, 100)}`);
8  console.error(`Source:\n${stack}`);
9  return originalWrite(chunk, ...args);
10};
11
12# Python — intercept stdout
13import sys
14import traceback
15
16class StdoutInterceptor:
17    def __init__(self, original):
18        self.original = original
19    def write(self, s):
20        if s.strip():  # Ignore empty writes
21            traceback.print_stack(file=sys.stderr)
22            sys.stderr.write(f"[STDOUT POLLUTION]: {s}\n")
23        return self.original.write(s)
24    def flush(self):
25        self.original.flush()
26
27sys.stdout = StdoutInterceptor(sys.stdout)

1// Ensure UTF-8 encoding in Node.js
2// The MCP SDK handles this automatically, but if you write
3// custom transport code:
4process.stdout.setDefaultEncoding("utf-8");
5process.stdin.setEncoding("utf-8");
6
7# Python — ensure UTF-8
8import sys
9import io
10
11# Force UTF-8 for stdin/stdout
12sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
13sys.stdin = io.TextIOWrapper(sys.stdin.buffer, encoding='utf-8')
14
15// When returning tool results with multi-line text,
16// the SDK handles JSON escaping of newlines automatically.
17// Do NOT try to manually escape or format the protocol messages.
18server.tool("example", "Example", {}, async () => ({
19  content: [{
20    type: "text",
21    // Newlines in content are fine — SDK handles JSON escaping
22    text: "Line 1\nLine 2\nLine 3"
23  }]
24}));

1# Test stdio server with MCP Inspector
2npx -y @modelcontextprotocol/inspector
3
4# For a quick manual test, send the initialize message:
5echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | node dist/index.js
6
7# If the server responds with valid JSON-RPC → stdio is clean
8# If you see non-JSON output mixed in → stdout is polluted