From 5b532a1c37fc663121fee59ad9e6f1474215dcbc Mon Sep 17 00:00:00 2001 From: Amirreza Hosseini Date: Thu, 15 Oct 2026 10:13:49 -0600 Subject: [PATCH] docs: note Windows OpenBLAS hang with stdio tool imports Point server authors at pre-importing numpy/scipy/torch before mcp.run() on Windows stdio, and link the troubleshooting path people search when a tool call hangs with no error (#2832). Co-authored-by: Cursor --- docs/run/index.md | 10 ++++++++++ docs/troubleshooting.md | 1 + 2 files changed, 11 insertions(+) diff --git a/docs/run/index.md b/docs/run/index.md index fb23b4bb54..1c34d912ec 100644 --- a/docs/run/index.md +++ b/docs/run/index.md @@ -41,6 +41,16 @@ Nothing prints, and it doesn't return. It is waiting on stdin for a host to spea That also means stdout **is the wire**. While serving, the SDK moves the wire to a private descriptor and diverts output that is *flushed* to stdout (a subprocess writing to its inherited stdout, a flushed `print()`) to stderr, where it can't corrupt the stream. Output flushed to stdout *before* serving begins (a wrapper script echoing, an unbuffered import-time print) still lands on the wire, and so does a `print()` that stays buffered until the interpreter drains it at exit. For output you actually want, the `logging` module is the right tool: its handler flushes each record to stderr as it happens. That story is in **[Logging](../handlers/logging.md)**. +!!! tip "Windows: import heavy native libraries before `run()`" + On Windows, a tool that **first-imports** an OpenBLAS-backed library (`numpy`, + `scipy`, `torch`, …) over **stdio** can hang with no error and no log line. + The stdio transport reads piped stdin on a background thread; that overlaps with + DLL init under the Windows loader lock (the same family as + [numpy#24290](https://github.com/numpy/numpy/issues/24290)). Import those + libraries at module scope **before** `mcp.run()`, so the in-tool import is a + cache hit. `streamable-http` is unaffected. Background: + [python-sdk#2832](https://github.com/modelcontextprotocol/python-sdk/issues/2832). + ### Try it ```console diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e23b5b16e1..912baceec0 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -421,6 +421,7 @@ mcp = MCPServer("Weather", request_state_security=RequestStateSecurity(keys=[key * If a message the SDK produced is not on this page, that is a documentation bug worth reporting on its own. * Search the [issue tracker](https://github.com/modelcontextprotocol/python-sdk/issues); most error strings appearing there are already someone's write-up. +* Tool call **hangs on Windows** over stdio with no traceback (often after a first `import numpy` / `scipy` / `torch` inside the tool): that is not an SDK exception — import those libraries at module scope before `mcp.run()`, or use `streamable-http`. See **[Running your server → stdio](run/index.md#stdio)** and [#2832](https://github.com/modelcontextprotocol/python-sdk/issues/2832). * Found nothing? [Open an issue](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml) with the full traceback, or ask in [#python-sdk-dev on the MCP Contributors Discord](https://discord.gg/6CSzBmMkjX). ## Recap