Skip to content

docs: note Windows OpenBLAS hang with stdio tool imports #3717

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Amiirhosseini wants to merge 1 commit into from
Closed

docs: note Windows OpenBLAS hang with stdio tool imports #3717

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/run/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading