fastmcp/docs
Jeremiah Lowin 8363ec4d26
Add stateless session state (UserSession / SessionId) (#4604)
* Design doc: stateless session state

* Add stateless session-state primitives: Scope, SessionCodec, scoped state

* Add SessionProvider and Session() annotation for stateless session state

* Rewrite session-state design to final shape (Session object, two patterns, no seal)

* Rework stateless session state to final Session/SessionId design

Remove Scope, SessionCodec/sealing, and scoped ctx.get_state. Add the
Session object (get/set/delete/clear over one dict per (principal,
session_id) key), injected session: Session (keyed by principal, requires
auth), session_id: SessionId argument with auto-filled description, and
SessionProvider contributing create_session/end_session.

* Rename injected marker to UserSession; auto-wire SessionProvider on SessionId

* Document stateless session state as a v4 feature

* Require SessionProvider and make sessions create-then-validate

Remove the implicit SessionProvider auto-wiring; a SessionProvider must now be
registered explicitly. create_session records an owned session and get_session
validates the id, rejecting uncreated or foreign ids.

* Add Session.id (public id for session_id sessions, None for UserSession)

* Fix ty: narrow Tool | None and ToolResult.structured_content in session tests

* Fix session-provider enforcement gap for non-local tools; stop embedding raw principal in UserSession key

* Fix disabled session_id tools blocking listing; reject local tools shadowing SessionProvider lifecycle names

* Decouple SessionId description from lifecycle tool name so it survives namespaced mounts

* Remove SessionProvider enforcement; get_session validation is the guarantee

* Fix stale enforcement/key-format docs; document store-owned session TTL

* Dedup SessionId contract description; tighten context.mdx session-state lead

* Make session store/description resolution work in Docket task workers and for partial tools

* Expose get_session as a standalone task-safe function; drop foreground-only Context.get_session

* Move get_session to dependencies alongside the other request accessors

* Reframe context state docs as Request State; cross-request persistence points to Session State

* Address UserSession injection edge cases from review

- inject a UserSession instance (not bare Session) so isinstance holds
- support session: UserSession | None = None (inject None when unauth)
- detect SessionId params past a partial's positional binding
2026-07-23 19:21:00 -04:00
..
.cursor/rules Clean up parameter documentation 2025-06-22 20:59:53 -04:00
apps Trim fastmcp.types to FastMCP-unique types only 2026-07-20 20:53:11 -04:00
assets Animated (#3231) 2026-02-19 11:56:51 -05:00
cli Align CLI, deployment, and config docs (#4259) 2026-07-19 14:24:07 -04:00
clients Expose era-neutral client server metadata (#4599) 2026-07-23 15:06:26 -05:00
community Normalize repo references to PrefectHQ/fastmcp casing (#3218) 2026-02-18 14:51:18 -05:00
css Restore Mintlify's fixed banner positioning (#4542) 2026-07-18 21:25:39 -04:00
deployment Align CLI, deployment, and config docs (#4259) 2026-07-19 14:24:07 -04:00
development Add stateless session state (UserSession / SessionId) (#4604) 2026-07-23 19:21:00 -04:00
getting-started Bridge camelCase ToolAnnotations reads (#4597) 2026-07-22 13:55:41 -05:00
integrations Trim fastmcp.types to FastMCP-unique types only 2026-07-20 20:53:11 -04:00
more Speed up the unit test suite, and fix the task-notification race it surfaced (#4550) 2026-07-19 18:52:04 -04:00
patterns Align CLI, deployment, and config docs (#4259) 2026-07-19 14:24:07 -04:00
public/schemas/fastmcp.json chore: Update fastmcp.json schema (#1955) 2025-09-29 20:12:24 -04:00
python-sdk chore: Update SDK documentation (#4589) 2026-07-21 13:10:24 -05:00
servers Add stateless session state (UserSession / SessionId) (#4604) 2026-07-23 19:21:00 -04:00
snippets Fix docs app demo iframe assets (#4194) 2026-05-20 13:18:45 -04:00
tutorials Migrate to MCP SDK v2.0.0b2 (httpx2) (#4503) 2026-07-18 15:12:47 -04:00
v2 docs: quote pip extras install examples (#4568) 2026-07-20 11:09:50 -04:00
.ccignore Add comprehensive OAuth 2.1 authentication system with WorkOS integration (#1327) 2025-08-01 17:06:55 -04:00
changelog.mdx Fix typos (#4498) 2026-07-18 21:18:39 -04:00
docs.json Add stateless session state (UserSession / SessionId) (#4604) 2026-07-23 19:21:00 -04:00
fastmcp-analytics.js [codex] Add FastMCP docs telemetry (#3727) 2026-03-31 19:32:09 -04:00
prefab-demo-payloads.js Fix docs app demo iframe assets (#4194) 2026-05-20 13:18:45 -04:00
python-sdk-pages.json chore: Update SDK documentation (#4569) 2026-07-20 18:44:54 -04:00
unify-intent.js Add tag to deployment pages (#3624) 2026-03-25 11:39:25 -04:00
updates.mdx Docs: forward-port v3.4.4 changelog entries (#4476) 2026-07-08 20:55:43 -04:00
v2-banner.js Update docs for 3.0 GA release (#3216) 2026-02-18 14:29:28 -05:00
v2-navigation.json chore: split v2 docs navigation into separate file (#3762) 2026-04-04 21:17:39 -04:00