modelcontextprotocol / modelcontextprotocol/python-sdk

Heavy sync init work (e.g. local ML models) starves stdio initialize/tool calls even with threadpool offload -- Windows GIL contention

Open
#3,089 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation enhancement needs decision P3 v1 v2
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

Description

Environment
  • mcp 1.28.1 (Python SDK, mcp.server.fastmcp.FastMCP)
  • stdio transport, Windows 11
  • Blocking work: sentence-transformers / torch (local embedding model), but this
    generalizes to any CPU/GIL-bound library load (onnxruntime, local LLM inference, etc.)
Summary

Related to #1839 / #1909, but a distinct failure mode that threadpool offload does not
fix: GIL-bound CPU work (loading a torch model) contends with the anyio stdio
transport's Windows pipe-reader thread for the GIL, regardless of where it runs in-process.
This makes several reasonable-looking designs fail in ways that are easy to ship and hard
to reproduce in a quick manual test.

Measurements

Same model load (sentence-transformers/all-MiniLM-L6-v2), only the location changes:

Where the load runs initialize First tool call
Standalone script, no event loop ~8s
Synchronously before mcp.run() ("warm on start") blocks 8–70s instant
In a background thread, started before mcp.run() delayed deadlocks
Lazily on first call, offloaded via anyio.to_thread / threadpool instant ~70s
In a separate subprocess, talked to over a pipe ~1s ~8–9s

Only the subprocess isolation keeps both connection time and first-call time bounded.
The variance (8s → 70s) is driven by contention between the model-loading thread and
anyio's Windows stdio reader thread — both fighting for the GIL.

Why this matters beyond my case

It's tempting to "fix" a slow first tool call by warming eagerly before mcp.run().
That instead moves the stall onto the initialize handshake — which is worse, because a
client that doesn't get the handshake in time just drops the server with no visible
error. That's a silent failure (tools missing, no exception) that's intermittent
(fine when warm/cached, broken on a cold start), so it's easy to ship and hard to catch
in CI or a quick manual check.

Suggested fix / ask

Not asking for an SDK-level fix necessarily — run_in_threadpool from #1909 is the right
answer for I/O-bound blocking calls. But it'd help other implementers to:

  1. Note in the docs/guidance for FastMCP that CPU/GIL-bound initialization (local model
    loads, etc.) should NOT be threadpool-offloaded in-process — it should run in a
    separate subprocess — since threadpool offload does not release the GIL contention
    the way it does for I/O-bound blocking calls.
  2. Consider whether initialize should have an explicit, documented deadline/backpressure
    behavior so implementers know exactly how much startup latency is safe.

Disclaimer: I'm not a Python/asyncio expert — this diagnosis, the measurements, and
this write-up were produced by Claude Code (Anthropic's coding agent) while it was
building a local memory/retrieval MCP server for me and debugging why it intermittently
failed to connect. I'm filing it because the finding looked substantive and reproducible,
but I likely can't answer deep follow-up questions about the internals myself.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the FastMCP documentation and the stdio initialization path described in the report; compare existing guidance on anyio.to_thread with the observed Windows behavior. Done should be documented guidance for CPU/GIL-bound initialization and subprocess isolation, with any initialize deadline or out-of-scope decision stated clearly.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend-api-design, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.