Repository navigation
Upgrade FastMCP to v4 and fix "lost dataset" bug - #21
Merged
Merged
Conversation
Lifts the `fastmcp>=3.4,<4` cap to `>=4.0.11,<5`. Of the ~16 breaking
changes 3->4 documents, exactly one reaches this codebase; the rest are
inert here (no `ctx.elicit`, no `ctx.sample`/`list_roots`, no
`McpError` construction, no `httpx` imports, no `as_proxy`/`mount`,
no `serializer=`/`exclude_args=`, no resources, no OAuth). Verified
against the installed 4.0.11 tree rather than the docs.
Component classes moved out of their submodules, so
`fastmcp.tools.tool.ToolResult` becomes `fastmcp.tools.ToolResult` in
six places.
The one that matters: **`ctx.session_id` is not a client identity.**
`_session_key` treated it as one, but that was never contractual --
FastMCP's own docstring only promises "a generated ID for other
transports". The stability came from where FastMCP cached a minted
uuid4: on SDK v1, a long-lived `ServerSession` per connection; on SDK
v2, a long-lived `Connection` -- but only on the handshake era. The
modern `2026-07-28` protocol builds a fresh `Connection` per request
and tears it down afterwards, so `connection.state` is empty, a new
uuid4 is minted, and the cache write is discarded. Every call therefore
gets a different `session_id`.
Because it is always truthy, it also made the `"default"` fallback --
the correct key for stdio -- unreachable. The symptom was
`NO_ACTIVE_DATASET` from the second tool call onward: ingest a cohort,
then ask for it without repeating `edata_id`, and the active handle is
gone. Eight tests across three files failed this way, including two
argument-folding tests that were never about argument folding.
The fix consults an attribute only where it is an identity:
- `client_id` first. It is whatever the client puts in
`_meta.client_id` and reads the same on both eras, so a supervisor
can supply a real key.
- `session_id` only for a stateful transport speaking a handshake-era
protocol version, where it genuinely is the negotiated
`mcp-session-id`.
- otherwise a process-global key, which is correct for stdio by
construction: one process, one stdin/stdout pair, one client. The
in-process transport the tests use is single-tenant too.
Era detection reads `ctx.request_context.protocol_version` against
`mcp_types.version.HANDSHAKE_PROTOCOL_VERSIONS`, which is how FastMCP
gates `ctx.elicit` internally. There is no server-side way to pin the
era -- a client picks it with its first frame, and raising from
`on_discover` breaks `mode="auto"` clients rather than downgrading
them -- so the code has to be era-correct, not era-dependent.
`UserSession` and `ctx.set_state` are not alternatives here: the first
raises `SessionAuthError` with no authenticated principal (and the auth
layer short-circuits on stdio entirely), and the second namespaces its
keys by `session_id`, inheriting the same instability.
tests/mcp/test_session_key.py pins the reasoning rather than the
implementation, so the probe order cannot be simplified back into the
bug: it asserts the premise that `session_id` really is unstable on
the modern era, and that an ingested handle survives repeated
session-scoped calls. Verified by mutation -- restoring unconditional
trust in `session_id` fails five of them.
Also of note: `uv.lock` is gitignored, so CI resolves from
pyproject.toml on every run and that constraint is the only dependency
control there is.
Verified: 96 MCP tests and 679 total on py3.12 and py3.14; MCP
handshake against dist/*.whl (ALL_OK, 14 tools); and against the
packaged wheel under a supervisor's environment, where session-scoped
preprocessing and get calls succeed, read-only is still enforced, and
nothing lands outside the pinned cache.
jeremy-wayland
force-pushed
the
fix/fastmcp4-upgrade
branch
from
October 14, 2026 06:53
7b5c632 to
fa7882c
Compare
jeremy-wayland
approved these changes
Oct 14, 2026
jeremy-wayland
left a comment
Member
There was a problem hiding this comment.
LGTM! Rebased onto main to drop the already-merged PR #19 commits.
_session_keyprecedence (client_id-> handshake-era non-stdiosession_id-> process-widedefault) cleanly resolves the FastMCP v4 /2026-07-28per-requestConnectionissue.- Keeping the
<5upper bound inpyproject.tomlis the right call sinceuv.lockis gitignored. ToolResultimport migration andtests/mcp/test_session_key.pycoverage look solid.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Why
>=3.4,<4to>=4.0.11,<5.The bug
edata_id→NO_ACTIVE_DATASETerror from the second call onward.ehrapy/mcp/session.pyused FastMCP'ssession_idas the client's identity. FastMCP never guaranteed that. v3 happened to keep it stable; v4's newer protocol (2026-07-28) generates a new one on every request.client_idfrom the request metadata (stable on all protocol versions)session_id, only on protocol versions where it is a real negotiated IDOther code changes
fastmcp.tools.tool.ToolResult→fastmcp.tools.ToolResult(6 places).Tests
tests/mcp/test_session_key.pylocks in the reasoning above, so the logic can't be "simplified" back into the bug.tests/mcp: 96 passed (py3.12, py3.14). Full suite: 679 passed, 1 skipped (py3.14).edata_idnow work. Read-only mode and cache/allowed-root restrictions still hold.Considered and rejected
UserSession: needs authentication, which stdio doesn't have.ctx.set_state: keyed bysession_id, so it has the same bug.Reviewer decision needed
uv.lockis gitignored, so CI resolves frompyproject.tomlevery run. I capped at<5to block unattended major upgrades. Say so if you'd rather leave it uncapped.