Skip to content

Upgrade FastMCP to v4 and fix "lost dataset" bug - #21

Merged
jeremy-wayland merged 1 commit into
mainfrom
fix/fastmcp4-upgrade
Oct 14, 2026
Merged

jeremy-wayland merged 1 commit into
mainfrom
fix/fastmcp4-upgrade

Conversation

@sgathrid

@sgathrid sgathrid commented Oct 5, 2026 •

Copy link
Copy Markdown
Member

What this does

  • Upgrades FastMCP (the library behind our AI-assistant/MCP interface) from v3 to v4.
  • Fixes a bug v4 exposed: after loading a dataset, the next request forgot it.

Why

  • v4 adds Background Tasks and progress reporting. We were carrying workarounds for both.
  • Dependency range changes from >=3.4,<4 to >=4.0.11,<5.

The bug

  • Symptom: load a dataset, then run a follow-up without re-specifying edata_id → NO_ACTIVE_DATASET error from the second call onward.
  • Cause: ehrapy/mcp/session.py used FastMCP's session_id as 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.
  • Fix: identify the client in this order:
    1. client_id from the request metadata (stable on all protocol versions)
    2. session_id, only on protocol versions where it is a real negotiated ID
    3. Otherwise one process-wide key. This is correct for stdio (one process = one client).

Other code changes

  • One import path moved: fastmcp.tools.tool.ToolResult → fastmcp.tools.ToolResult (6 places).
  • Of the ~16 documented v3→v4 breaking changes, only this one affects us. We don't use the rest (checked against the installed 4.0.11 code).

Tests

  • New tests/mcp/test_session_key.py locks 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).
  • Built wheel passes MCP handshake (14 tools). Follow-up calls without edata_id now 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 by session_id, so it has the same bug.
  • Background Tasks: doesn't fix this. Cancellation is cooperative, so it can't prevent state corruption. Still the right tool for long-running jobs, as separate follow-up work.

Reviewer decision needed

  • uv.lock is gitignored, so CI resolves from pyproject.toml every run. I capped at <5 to block unattended major upgrades. Say so if you'd rather leave it uncapped.

@sgathrid sgathrid changed the title Upgrade to FastMCP 4 and stop keying sessions on a per-request id Upgrade FastMCP to v4 and fix "lost dataset" bug Oct 5, 2026
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 jeremy-wayland left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Rebased onto main to drop the already-merged PR #19 commits.

  • _session_key precedence (client_id -> handshake-era non-stdio session_id -> process-wide default) cleanly resolves the FastMCP v4 / 2026-07-28 per-request Connection issue.
  • Keeping the <5 upper bound in pyproject.toml is the right call since uv.lock is gitignored.
  • ToolResult import migration and tests/mcp/test_session_key.py coverage look solid.

@jeremy-wayland
jeremy-wayland merged commit 1d880ec into main Oct 14, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants