Quick summary

  • An MCP server can pass unit tests yet fail to respond when a host launches it over stdio. The lesson is to test process and stream boundaries as an integration contract, not just tool logic.
  • A transport failure can make every tool unavailable and can be mistaken for a model, authorization, or schema problem.
  • Add an integration test that launches the server as the real host does and asserts its stdin/stdout exchange, timeout behavior, stderr, and exit code.

What happened

“All tests pass, but the server does not respond” is an unusually expensive MCP integration failure. The headline on three hidden traps in the MCP stdio protocol makes the central point well: unit correctness and host-run behavior are separate things to prove.

With stdio, messages and control signals cross a process boundary. A server can therefore be functionally correct while failing to communicate in the environment that actually launches it.

Why unit tests are insufficient

Unit tests commonly invoke functions directly and assert returned values. They can miss process startup, stream handling, and failures that become invisible while a host waits for a response.

Engineer testing a local server process with data and separate diagnostics channels.
Engineer testing a local server process with data and separate diagnostics channels.

The source title alone does not establish the three specific traps, so they should not be inferred. Its operational implication is still clear: transport needs its own test suite, using a host or harness that resembles real client execution.

Test the boundary, not only the handler

Add an integration test that launches the executable as the host will, writes a request to stdin, and reads the response from stdout. Cover initialization, a successful tool call, an intentional failure, and shutdown.

  • Reserve stdout for protocol data; send diagnostic logging through an appropriate separate channel.
  • Use timeouts so hangs fail visibly rather than waiting forever.
  • Capture stderr and exit codes on failures.
  • Run the test with the expected command, environment variables, and runtime environment.

Make failures easier to classify

When a server is silent, ask in order: did the process start, did streams exchange data, and did the handler process the request? That sequence avoids blaming schemas or the model before lifecycle and transport are ruled out.

Discussion of building, securing, and serving MCP servers reinforces the point: defining a tool is not the whole product. Entrypoints, logs, and diagnostics are operational features.

When stdio is the right choice

stdio can fit a locally managed host process and a simple connection path. It also demands I/O discipline and integration testing. Do not put a server into a critical workflow until its end-to-end behavior has been exercised.

In 5 Minutes

  • Green unit tests do not prove correct MCP stdio communication.
  • Tests should launch the process and exercise streams.
  • Timeouts, stderr, and exit codes make hangs diagnosable.
  • Separate lifecycle, transport, and handler failures.

Sources

Why developers should care

A transport failure can make every tool unavailable and can be mistaken for a model, authorization, or schema problem.

  1. 1Add an integration test that launches the server as the real host does and asserts its stdin/stdout exchange, timeout behavior, stderr, and exit code.