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

Ouverte
#3,089 3 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

documentation enhancement needs decision P3 v1 v2
Langage dominant
Python
Étoiles
24.3k
Forks
4k
Merge moyen
1 j 1 h
PR mergées (30 j)
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.

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par la documentation de FastMCP et le chemin d’initialisation stdio décrit dans le rapport ; comparez les indications existantes sur anyio.to_thread avec le comportement observé sous Windows. La section « Done » doit fournir des indications documentées pour l’initialisation limitée par le CPU/GIL et l’isolation des sous-processus, en indiquant clairement tout délai de initialize ou toute décision de considérer un élément comme hors périmètre.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
backend-api-design, documentation
Type d'issue
Documentation
Difficulté
3/5
Temps estimé
1-2 jours
Activité
Calme
Clarté
Plutôt claire
Accessibilité débutants
48/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.