docs/development/v4-notes/known-gaps.mdx
The migration ships with a set of deliberate gaps: temporary shims, xfailed tests, and pins that depend on the MCP Python SDK v2 reaching GA. Each is tracked here with its removal trigger. This page is the checklist for the beta-to-stable transition and the advisory relationship with the SDK team.
Roughly forty xfail markers across the test tree name the SDK gaps and removed protocol surfaces they wait on. Re-running the suite against a new SDK beta surfaces which have closed (a strict xfail that starts passing fails the suite, prompting removal of the marker). They cluster in three areas — but the largest cluster is no longer a set of gaps to close.
Task suite (tests/server/tasks/, tests/client/tasks/) — SEP-1686 wire layer being removed; engine rebuilt on SEP-2663. The large majority. These cover the 2025 task protocol (SEP-1686), which left the core MCP spec and was reworked into the io.modelcontextprotocol/tasks extension (SEP-2663). FastMCP's SEP-1686 wire machinery (capability advertisement, the tasks/get|result|list|cancel handlers, the push notification/elicitation relay) is slated for removal, so the wire-protocol xfails disappear with the code they cover — they are not waiting on an SDK fix. The Docket/Redis execution engine underneath is not discarded: it is extracted into the planned fastmcp-tasks package and re-adapted to the SEP-2663 polling shape (see Background Tasks (SEP-2663)). The two SDK gaps these were originally filed against — sdk-feedback #1 (SEP-1686 task result types omitted from the method registries) and sdk-feedback #3 (no task field on ReadResourceRequestParams / GetPromptRequestParams) — are moot: they patched the SEP-1686 wire shape, which SEP-2663 replaces with a CreateTaskResult claimed on tools/call. The gap that matters for the rebuild is sdk-feedback #2 (extensions capability stripped at pre-2026 negotiated versions) — it now gates a flagship feature and is escalated accordingly.
Protocol eras (tests/server/test_protocol_eras.py). One remaining strict xfail, and it too is task-related: the v2 SDK high-level client exposes no task= parameter on call_tool, so a SEP-1686 task-augmented tools/call cannot be submitted through it. It resolves with the SEP-1686 wire-layer removal above; the SEP-2663 rebuild submits tasks by advertising the extension capability and claiming a CreateTaskResult, not through a task= params field. The earlier strict xfail for the ctx.elicit / ctx.sample "Method not found" degradation (sdk-feedback #10) is gone — the era-gating shipped in #4448 flipped it to a passing test.
MCP Apps (tests/test_apps.py). Two xfails tied to sdk-feedback #2 — the extensions capability is stripped by the pre-2026 version sieve, so the UI extension can't be advertised to legacy-era clients.
Every shim in the migration is temporary and carries a documented removal trigger.
| Shim | Location | Removal trigger |
|---|---|---|
_sdk_patches.py — task registry widening | fastmcp_slim/fastmcp/_sdk_patches.py | Removed with FastMCP's SEP-1686 wire machinery (server/tasks/), which is slated for removal now that the 2025 task protocol left the spec. The SEP-2663 rebuild does not need it — CreateTaskResult is claimed on tools/call through the extensions mechanism, which the SDK registries already admit. |
_compat.py — camelCase field bridge | fastmcp_slim/fastmcp/_compat.py | User-migration aid; removed in a future release after users migrate reads to snake_case. Users can preview removal with mcp_camelcase_compat = False. |
FastMCPRequestContext ContextVar | fastmcp_slim/fastmcp/server/dependencies.py | The SDK deliberately passes context as an argument with no ContextVar; FastMCP's public get_context() needs ambient access, and the shim also lifts _meta, which the SDK's TypedDict drops. No planned removal — this is a permanent boundary, not a beta gap. |
FastMCPServerMiddleware | fastmcp_slim/fastmcp/server/low_level.py | Already the native SDK ServerMiddleware path; no cleaner hook exists. Permanent. |
Client get_session_id header sniff | fastmcp_slim/fastmcp/client/transports/http.py | SDK exposes session id (or an on_session_created callback) from streamable_http_client, at parity with sse_client (sdk-feedback #5). |
_sdk_context_shim.py — generic handler aliases | fastmcp_slim/fastmcp/client/_sdk_context_shim.py | The SDK's ClientRequestContext is not subscriptable, so FastMCP keeps the public generic SamplingHandler/RootsHandler/ElicitationHandler aliases. Permanent unless the SDK makes the context subscriptable (sdk-feedback #7). |
The TaskNotificationHandler binding (sdk-feedback #8) is the client-side equivalent: it registers a NotificationBinding for the SEP-1686 notifications/tasks/status because the SDK no longer tees custom server notifications to the message handler. It goes away with the SEP-1686 wire machinery it serves; the fastmcp-tasks client half registers its own binding for the SEP-2663 notifications/tasks shape when it ships (push notifications are deferred to a later fastmcp-tasks version — v1 is polling-only).
The 2026-07-28 era is stateless by protocol construction, and the recurring maintainer question is whether that statelessness has to be woven through FastMCP everywhere. It does not — but the honest accounting has three parts: features that are legacy-only because the protocol removed the mechanism, features that already work because they never relied on a session, and a short list of design holes where the current code doesn't error but also doesn't work. Everything below concerns 2026-07-28 connections only. Every client in the field today negotiates a handshake era, where all of this behaves exactly as it always has.
The SDK ground truth. On the modern paths the SDK's Connection is strictly per-request: a fresh Connection is built from each POST's envelope, its exit_stack unwinds when the request returns, connection.session_id is always None, and connection.state is a fresh dict per request. The manager's stateless flag never enters the picture — modern routing short-circuits ahead of it. There is no standing server→client stream: notifications emitted during a request ride that POST's own SSE sink, and anything emitted after the POST returns is dropped (_NO_CHANNEL); server→client requests raise NoBackChannelError. The only replacement is subscriptions/listen, which carries four list-changed / resource-updated event kinds and nothing else — no logging, progress, or task-status events, no resumability, and it is not yet wired into FastMCP. There is no EventStore or Last-Event-ID on modern paths at all; both belong to the legacy transport.
These are not bugs. The protocol removed the mechanism they depend on, so they are simply out of scope on 2026-07-28:
logging/setLevel is absent from the 2026 method registry, so the _client_log_levels handler is unreachable. There is no per-session log-level state because there is no session.EventStore / resumability. EventStore, SessionScopedEventStore, and Last-Event-ID resumption are never constructed on the modern paths. Resumability presupposes a durable stream, which the era does not have.These work on 2026-07-28 today because they never leaned on a protocol session:
tasks/get polling. Task result retrieval is keyed by task_id and backed by Docket/Redis, so a client polls across independent requests without any session affinity. This session-free polling is exactly why the execution engine survives the SEP-1686-to-SEP-2663 rework: the SEP-2663 wire shape (poll tasks/get, resolve in-task input via tasks/update) maps onto the same durable store, and SEP-2663's Mcp-Name: <taskId> routing header is moot for a shared-Redis deployment where any replica can serve the poll. See the xfail register.The remaining items are real holes, deferred to the first-class 2026 client workstream because they all reduce to one unanswered question — what is a session when the protocol has none? The danger in each is that the code currently returns without erroring, which reads as "works" but is actually silent degradation. Again: these affect 2026-07-28 connections only; on the handshake eras every one of them behaves correctly.
ctx.session_id and ctx.set_state / ctx.get_state (broken even single-replica). On a modern request ctx.session_id mints a fresh uuid4, cached on the per-request connection.state that is discarded when the request returns. So ctx.set_state and ctx.get_state silently never round-trip across requests — no error, just lost data. The open design decision is whether session_id should become None with set_state documented as session-era-only, or be re-based on an app-level key (the auth subject, or a client-supplied header).input_required, surfaces its outstanding elicit/sample/roots requests in an inputRequests map on tasks/get, and the client answers via tasks/update. That round-trips through the durable store with no session affinity, so it is stateless-safe by construction. The SEP-1686 push relay (server/tasks/elicitation.py, notifications.py) is removed; the fastmcp-tasks rebuild implements the poll-based channel instead. Foreground (non-task) elicitation on 2026 remains the guard-mode InputRequiredResult._caches are keyed by the per-request Connection, so on modern connections the proxy collapses to stateless proxying: results stay correct, but the per-session affinity guarantee is lost. This is decided alongside the session_id question — same root — or gated to the legacy/stdio transports.Multi-replica concerns (per-process rate-limiter buckets, shared Redis backends for state and tasks, a Redis SubscriptionBus) are deployment configuration rather than protocol gaps and are out of scope for this section.
FastMCP acts as an advisor to the SDK team. The migration produced a dossier of ten findings (sdk-feedback.md) — verified bugs and hard edges to report upstream, plus questions to bundle into a feedback thread. The highest-priority items:
CreateTaskResult on tools/call through the extensions mechanism, which the registries already admit.capabilities.extensions stripped at pre-2026 negotiated versions. Elevated: this now gates the io.modelcontextprotocol/tasks extension (and MCP Apps) on the modern era, so it blocks a flagship v4 feature rather than an edge case. Worth prioritizing in the upstream thread.javascript:/data: schemes.streamable_http_client drops session-id access with no replacement.message_handler.ctx.elicit / ctx.sample are era-gated to raise a clear error on modern connections (#4448).Filing is gated on maintainer approval of each issue text.
Separately, the SDK delegation round two work depends on three upstream feature requests — per-session event-store scoping, a user-middleware injection hook, and a lifespan hook — that would let FastMCP collapse its HTTP builders onto the SDK's and inherit the SDK's session-owner credential enforcement.
The beta-to-stable transition is a small set of tracked steps:
mcp 2.0.0 reaches GA, change mcp-types==2.0.0b1 (core) and the mcp pin (the [mcp] extra) in fastmcp_slim/pyproject.toml from the beta to the stable release, and cut 4.0.0 instead of another pre-release.release/3.x is cut from pre-merge main and receiving upstream security patches for users who stay on the SDK v1 line.