π The fast, Pythonic way to build MCP servers and clients.
Document mounted server state store isolation in upgrade guide (#3236)
Jeremiah Lowin390a11d7d230
diff --git a/docs/getting-started/upgrading/from-fastmcp-2.mdx b/docs/getting-started/upgrading/from-fastmcp-2.mdxindex bed6ed7d7..fb8c57bf5 100644--- a/docs/getting-started/upgrading/from-fastmcp-2.mdx+++ b/docs/getting-started/upgrading/from-fastmcp-2.mdx@@ -56,6 +56,8 @@ BREAKING CHANGES (will crash at import or runtime):3. ASYNC STATE: ctx.set_state() and ctx.get_state() are now async (must be awaited).State values must be JSON-serializable unless serializable=False is passed.+ Each FastMCP instance has its own state store, so serializable state set by parent middleware isn't visible to mounted tools by default.+ Fix: pass the same session_state_store to both servers, or use serializable=False (request-scoped state is always shared).4. PROMPTS: mcp.types.PromptMessage replaced by fastmcp.prompts.Message.Before: PromptMessage(role="user", content=TextContent(type="text", text="Hello"))@@ -222,6 +224,20 @@ State values must also be JSON-serializable by default (dicts, lists, strings, nawait ctx.set_state("client", my_http_client, serializable=False)```+**Mounted servers have isolated state stores**++Each `FastMCP` instance has its own state store. In v2 this wasn't noticeable because mounted tools ran in the parent's context, but in v3's provider architecture each server is isolated. Non-serializable state (`serializable=False`) is request-scoped and automatically shared across mount boundaries. For serializable state, pass the same `session_state_store` to both servers:++```python+from fastmcp import FastMCP+from key_value.aio.stores.memory import MemoryStore++store = MemoryStore()+parent = FastMCP("Parent", session_state_store=store)+child = FastMCP("Child", session_state_store=store)+parent.mount(child, namespace="child")+```+**Auth provider environment variables removed**In v2, auth providers like `GitHubProvider` could auto-load configuration from environment variables with a `FASTMCP_SERVER_AUTH_*` prefix. This magic has been removed β pass values explicitly: