MCP stdio Protocol's 3 Hidden Traps: When All Unit Tests Pass but the MCP Server Won't Respond

A developer debugging a Node.js MCP Server found three hidden traps in the stdio protocol that caused all 404 unit tests to pass while the server failed to respond in real environments. The root causes were an immediate process.exit() call, a missing check for the --watch flag, and mishandling of the 'close' event, which together prevented the server from listening or responding. The developer outlines iron rules for building long-running stdio processes, including avoiding process.exit() in run() functions and waiting for in-flight promises before exiting.

This article records a real MCP Server debugging session: every automated test of story-cli passed, yet in a real environment the MCP Server couldn't respond to any request at all. The root cause turned out to be 3 bugs, each touching low-level details of the Node.js process model and the stdio protocol. If you're building an MCP Server or any long-running process that speaks a stdio protocol , remember three iron rules: process.exit inside a run function --watch modes, and any other long-running command are not one-shot CLI tools. process.exit kills the process before it even starts listening. If you must make an exception, extract the "long-running" abstraction e.g. isLongRunning instead of enumerating specific commands. close event close only means the input stream closed, not that your callbacks have finished. You need to wait for all in-flight Promises before exiting.First, a quick introduction to the project. story-cli is a zero-deployment, Git-native Markdown content management CLI . It manages stories/papers/notes/tutorials with a simple directory convention NN-名称/ — "NN-name/" — containing config.json + text.md , auto-generates READMEs, exports EPUB, and is bilingual Chinese/English . On our roadmap, the MCP Server was a P0-level strategic task — the gateway to the AI era. The design principle: "AI does the thinking, the CLI does the governance." We exposed 6 tools over JSON-RPC 2.0 over stdio: | MCP tool | Purpose | |---|---| scan stories | List all stories and their metadata | read chapter | Read a chapter's content from a story | write chapter | Write body text to a story atomic write | validate | Validate the config.json of every story | build | Trigger a README rebuild | import json | Bulk-import stories from structured JSON | The code structure was clean: src/mcp/ ├── protocol.ts JSON-RPC 2.0 protocol parsing/serialization pure functions, fully tested ├── tools.ts MCP tool registration reuses shared logic from core/loader.ts └── server.ts stdio server startup and request dispatch Everything looked perfect — until we actually called it . At the time we had 404 automated tests, 401 passing . tests/mcp.test.ts covered protocol parsing, serialization, tool registration, and every tool handler — all passing . So I started the MCP Server against a real story repository and sent a JSON-RPC request through a pipe: echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node bin/index.ts mcp-server 💀 Empty output. No response at all. I thought my pipe syntax was wrong. I tried several variations: approach 1: printf printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | node bin/index.ts mcp-server approach 2: file redirection printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' /tmp/req.json && node bin/index.ts mcp-server < /tmp/req.json approach 3: keep stdin open { printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n'; sleep 2; } | node bin/index.ts mcp-server Still nothing. Even weirder: when sending the request through Node.js's spawnSync , the process exit code was 0 it looked "successful" , but both stdout and stderr were empty. At that moment I realized: this isn't a calling convention problem — our MCP Server has a bug. But 404 tests were green How could there be a bug? I first looked at the CLI entry file bin/index.ts : js /usr/bin/env node import { run } from "../src/cli.ts" const exitCode = await run process.argv process.exit exitCode The problem was obvious at a glance. When a user runs story mcp-server : run process.argv is invoked run , runMcpServer rootDir is called → startMcpServer starts listening on stdin run returns 0 immediately startMcpServer is an async pattern that "registers listeners and returns" — it doesn't block process.exit 0 executes immediately The MCP Server died the moment it was born. js /usr/bin/env node import { run } from "../src/cli.ts" const exitCode = await run process.argv // An MCP server needs to stay alive and keep listening on stdin. // Process exit is handled by the close/SIGINT events inside server.ts. if process.argv 2 == "mcp-server" && process.argv 2 == "mcp" { process.exit exitCode } ⚠️ Note: this fix looked fine at the time, but later that same day testing exposed itslimitation— see "Bug 1.5: The Same Bug Returns" below. This is the first trap when turning a CLI tool into a service: | Mode | Lifecycle | When to exit | |---|---|---| CLI tool | Exits after the command finishes | process.exit exitCode is the right thing | Long-running process MCP Server / daemon | Keeps listening for input until EOF/signal | Exit must be driven by a callback triggered by the input source | process.exit is unconditional, immediate, and uninterruptible. It doesn't wait for pending I/O, timers, or Promises. In the MCP Server scenario, that "feature" killed our server outright. After fixing Bug 1, I kept testing the MCP Server. That same day, I wanted to check the performance of story build --watch : story build --watch The output said 「👀 监听模式已启动，文件变更自动重建...」 "👀 watch mode started, auto-rebuilding on file changes..." , but the process exited immediately — --watch mode never actually started watching files. I tried modifying a story file: echo "新内容" "01-测试故事/text.md" Nothing happened. The README was never updated. I looked back at the fix in bin/index.ts : if process.argv 2 == "mcp-server" && process.argv 2 == "mcp" { process.exit exitCode } What this logic says is: "for every command except mcp-server and mcp, call process.exit ." But build --watch is also a long-running process It needs to keep watching files until it receives SIGINT . Only the two MCP Server commands were exempted — build --watch wasn't on the whitelist, so it got killed by process.exit immediately too. The first MCP Server bug was fixed, and the same ghost reappeared on build --watch. The right fix isn't to enumerate even more commands — it's to extract the essential property of " which commands are long-running ": js /usr/bin/env node import { run } from "../src/cli.ts" const exitCode = await run process.argv // Long-running processes need to stay alive; exit is handled by internal close/SIGINT events: // - MCP server: keeps listening on stdin; exit is controlled by server.ts's close/SIGINT // - build --watch: keeps watching file changes; exit is controlled by build.ts's SIGINT const isLongRunning = process.argv 2 === "mcp-server" || process.argv 2 === "mcp" || process.argv 2 === "build" && process.argv 3 === "--watch" || process.argv 2 === "b" && process.argv 3 === "--watch" if isLongRunning { process.exit exitCode } This was the biggest lesson of the whole session: | Fix approach | Code shape | Problem | |---|---|---| Enumerate instances at the time | if cmd == "mcp-server" && cmd == "mcp" | Adding one more long-running command means coming back to edit this line | Extract an abstraction final | const isLongRunning = ... | Any new command just expresses its property inside this set | When you see an "exclusion list" in code if cmd == "A" && cmd == "B" , it means you're enumerating specific commands instead of expressing the essential property of "which commands are long-running". The moment a new long-running command appears like --watch , the same bug returns. Checklist : if your CLI is ever going to add a "keep-listening" feature watch / serve / daemon , check the isLongRunning list in bin/index.ts first — it must include the new command. After fixing Bug 1, I was pleasantly surprised to see tools/list respond But only these responded: tools/list ✅ initialize ✅Meanwhile, the async tools/call still got no response scan stories / read chapter / validate .I tested scan stories on its own: echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"scan stories","arguments":{}}}' | node bin/index.ts mcp-server Still empty. I tried a different angle — calling loadStories directly in Node: js node --experimental-strip-types -e " import { loadStories } from './src/core/loader.ts'; const { stories } = await loadStories '/tmp/test-story-cli' ; console.log 'STORIES:', stories.length ; " Output: 📊 01-测试故事: 自动计算字数为 约 13 字（未写回，使用 --save-counts 持久化） 📊 02-二创故事: 自动计算字数为 约 13 字（未写回，使用 --save-counts 持久化） 📊 03-English-Story: 自动计算字数为 ~7 words（未写回，使用 --save-counts 持久化） STORIES: 3 Found it Inside loadStories , a console.log was printing "auto-computed word count" diagnostic lines. console.log Kill MCP? MCP's stdio transport spec says stdout is the protocol-dedicated channel : ├── stdin ← client sends JSON-RPC requests ├── stdout → server returns JSON-RPC responses protocol-dedicated, the only legal output └── stderr → logs/warnings/errors for humans, not for the protocol When an MCP client sends a scan stories request, the server calls loadStories while handling it, and console.log dumps a 📊 01-测试故事: ... line to stdout. Now stdout looks like: 📊 01-测试故事: 自动计算字数为 约 13 字... ← pollution {"jsonrpc":"2.0","id":3,"result":{...}} ← the real response MCP clients VSCode / Claude Desktop / Cursor expect every line of stdout to be a valid JSON-RPC message when parsing. The first line isn't JSON at all — the client gives up on parsing, which looks like "no response". As a side note, MCP's stdio transport also has a hard requirement about newlines: every JSON-RPC message must end with \n . If your server outputs JSON without a trailing newline, the client also fails to parse it. That's why the official MCP docs' Debugging page states it plainly: "Local MCP servers should not log messages to stdout standard out , as this will interfere with protocol operation." — The docs warned us all along; we only truly understood it after stepping on it in a real environment. And this kind of bug is especially sneaky: scan stories 's handler is called directly and nobody parses stdout → tests pass // Before if config.wordCount { console.log locale.autoWordCount folder, story.wordCount, saveCounts } // After if config.wordCount { // Use stderr for diagnostics so we don't pollute the stdout channel of the MCP stdio protocol. console.error locale.autoWordCount folder, story.wordCount, saveCounts } The console.log locale.generatedText ... inside loadStoryContentAsync was changed the same way. In a stdio protocol, stdout is not for logging. It's the protocol channel between two processes. Any extra output — even a single seemingly harmless log line — breaks protocol parsing. This is a silent runtime failure : the code doesn't throw, tests don't fail, and only real clients mysteriously stop working. In an MCP Server, stdout = protocol , stderr = logs . Never mix them. After fixing Bug 2, I thought everything was done. But testing showed tools/call still responded intermittently : sometimes a response came back, sometimes not. I stared at the old code in src/mcp/server.ts : export function startMcpServer rootDir: string, tools: RegisteredTool : void { const rl = createInterface { input: process.stdin, terminal: false } rl.on "line", async line = { // ... parse and handle the request const response = await handleRequest request, rootDir, tools if response process.stdout.write serializeMessage response } rl.on "close", = { // Wait for stdout to flush before exiting avoid truncated output process.stdout.write "", = process.exit 0 } // ... } In pipe mode echo '...' | node bin/index.ts mcp-server , stdin closes immediately after all lines are read, which fires the close event. When close fires, the async await handleRequest inside rl.on "line" hasn't finished yet Here's the timing: t0: stdin receives the JSON-RPC request line t1: rl fires the "line" event and enters the async callback t2: the async callback hits await handleRequest and suspends shaded area = waiting for the async result t3: stdin finishes reading all lines → rl fires the "close" event t4: the "close" callback runs process.stdout.write "", = process.exit 0 t5: the process exits while await handleRequest is still suspended → the response is lost forever This is an async race : close says "the input stream is closed", but it doesn't wait for your Promises to finish. Track all in-flight requests with a pending Set, and wait for all of them on close before exiting: export function startMcpServer rootDir: string, tools: RegisteredTool : void { const rl = createInterface { input: process.stdin, terminal: false } const pending = new Set<Promise<void rl.on "line", line = { const trimmed = line.trim if trimmed return let request: JsonRpcRequest try { request = parseRequest trimmed } catch e { const code = e as Error & { code?: number } .code ?? JsonRpcErrorCode.InternalError process.stdout.write serializeMessage makeErrorResponse null, code, e as Error .message , return } // Track in-flight requests so we know the async handler has finished when stdin closes. const task = async = { const response = await handleRequest request, rootDir, tools if response process.stdout.write serializeMessage response } pending.add task task.finally = pending.delete task } rl.on "close", = { // Wait for all in-flight requests to finish, then flush stdout before exiting avoid truncated output . void Promise.allSettled ...pending .then = { process.stdout.write "", = process.exit 0 } } process.on "SIGINT", = { rl.close } } In Node.js's event loop, readline's close event only means "the input stream closed", not "your async callbacks have run" . This is a universal problem for every stdio protocol server: when stdin hits EOF, you may still have queued Promises. You need to track and wait for them explicitly: close or SIGINT , wait with Promise.allSettled process.exit The biggest insight from this session was the value of layered testing : | Test layer | Our previous coverage | What it would catch | |---|---|---| Unit tests calling handler functions directly | ✅ 401 all green | Can't catch Bug 1 / 2 / 3 | Integration tests calling startMcpServer without a real process | ❌ none | — | End-to-end tests spawnSync a real child process + real stdin/stdout | ❌ none | All 3 bugs at once | Green unit tests don't mean the system works. You need to start the server in a real process, send requests through real pipes, and parse real stdout — because only end-to-end tests can catch problems at the "process lifecycle" and "protocol integrity" levels. // tests/mcp-server.test.ts the end-to-end test we added function sendRequests dir: string, requests: string { const input = ${requests.join "\n" }\n const result = spawnSync process.execPath, binPath, "mcp-server" , { cwd: dir, input, encoding: "utf-8", timeout: 5000, } return { stdout: result.stdout || "", stderr: result.stderr || "", status: result.status ?? -1, } } test "MCP server responds to async tools/call scan stories ", = { const { stdout, stderr } = sendRequests dir, '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"scan stories","arguments":{}}}', // stderr must not contain JsonRpcResponse content → guards against console.log/stdout pollution assert.ok stderr.includes "jsonrpc" // Split by lines and filter empty lines instead of JSON.parse stdout.trim . // If stdout contains multiple lines, trim only strips leading/trailing whitespace // and the inner newlines make JSON.parse fail. const lines = stdout .split "\n" .map l = l.trim .filter Boolean assert.ok lines.length = 1, "there should be at least one JSON-RPC response" // Take the last line or look up the line by id when multiple responses are requested const response = JSON.parse lines lines.length - 1 ?? "{}" // ... } This test starts the MCP Server in a real child process , sends JSON-RPC requests through real pipes , and validates the stdout contents. If anyone ever adds a console.log to loadStories , this test fails immediately. Follow-up same day : after fixing Bug 1.5, we added an end-to-end regression test for build --watch tests/watch.test.ts — it uses spawnSync to start a real child process and asserts "the process stays alive" + "the README is rebuilt within 5 seconds of editing a story". If we'd had that test back then, Bug 1.5 would have been caught the day it was fixed, instead of surfacing by accident during a later performance check. That's test layering proven once again:unit tests can't cover process lifecycle — only end-to-end tests can. 1. Create a test repository mkdir -p /tmp/test-story-cli && cd /tmp/test-story-cli node /path/to/story-cli/bin/index.ts init node /path/to/story-cli/bin/index.ts new "测试故事" 2. Start the MCP Server find the problem echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node /path/to/story-cli/bin/index.ts mcp-server → empty output Bug 1 3. After fixing 1 → tools/list responds, but scan stories doesn't Bug 2's stdio pollution 4. Verify loadStories behavior in isolation node --experimental-strip-types -e " import { loadStories } from './src/core/loader.ts'; await loadStories '/tmp/test-story-cli' ; " → see the 📊 logs appearing on stdout 5. After fixing 2 → sometimes responds, sometimes not Bug 3's async race 6. Verify repeatedly via the end-to-end test node --test tests/mcp-server.test.ts → 7 tests pass Everything above is "post-mortem" debugging. If you integrate MCP Inspector MCP's official debugging tool during development, many of these problems can be caught before release: npx @modelcontextprotocol/inspector node /path/to/story-cli/bin/index.ts mcp-server MCP Inspector launches a visual web UI that lets you: It's the "X-ray machine" of MCP Server development — I recommend every MCP Server developer run everything through the Inspector before CI/CD. There are also third-party helpers in the community like mcp-stdio-guard for catching stdout pollution , but the Inspector as the official tool covers most scenarios. An MCP Server has to handle not only protocol traps 1 / 2 / 3 but also traps in the AI interaction layer : When create story creates a directory, it converts spaces in the title to hyphens e.g. "AI 创作的故事" → 02-AI-创作的故事 , but the LLM may pass back the original space form "02-AI 创作的故事" — safeFolder has to match both variants to hit the right directory. Protocol-layer traps and interaction-layer traps — we stepped on all of them the same day. If you only take away three sentences, plus one lesson about fixing bugs themselves: process.exit belongs only to one-shot CLI commands. close ≠ all work finished. pending Set + Promise.allSettled to explicitly wait for async work. if cmd == "A" && cmd == "B" , you're enumerating specific commands — when a new long-running command appears, the same bug recurs somewhere new.What these four problems have in common: none of them can be caught by unit tests ; they only surface in real process environments. So — after writing your handlers, don't forget to write a spawnSync end-to-end test. Note that these four iron rules are language-agnostic — whether you build a stdio server in Node.js, Python, or Go, the same four traps exist: process.exit / stdout pollution / un-awaited async work / enumerating instead of abstracting. This article uses Node.js only because our project happens to be on the Node stack. This article is based on a real debugging session from the story-cli project. Repository: story-cli https://github.com/yuelinghuashu/story-cli