From d4289b27c0106373a9b5aba0c0ced55aa517ef14 Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Sat, 28 Mar 2026 21:15:27 -0400
Subject: [PATCH] Add prefab-ui version pinning warning to docs (#3688)
---
docs/apps/overview.mdx | 12 +++++++++++-
docs/apps/prefab.mdx | 6 +++---
2 files changed, 14 insertions(+), 4 deletions(-)
diff --git a/docs/apps/overview.mdx b/docs/apps/overview.mdx
index 895c91301..98856eafd 100644
--- a/docs/apps/overview.mdx
+++ b/docs/apps/overview.mdx
@@ -25,9 +25,19 @@ The examples throughout the Apps docs require the `apps` extra:
pip install "fastmcp[apps]"
```
-This installs [Prefab UI](https://prefab.prefect.io), the component library used to build app UIs. Pin `prefab-ui` to a specific version in production — it's in early development and its API changes frequently.
+This installs [Prefab UI](https://prefab.prefect.io), the component library used to build app UIs.
+
+FastMCP pins a **minimum** version of `prefab-ui` for compatibility but intentionally does **not** pin an upper bound. Prefab is a rapidly evolving library with frequent breaking changes. If you are deploying to production, you **must** pin `prefab-ui` to a specific version in your own dependencies:
+
+```
+prefab-ui==0.15.0
+```
+
+Without a pin, a `pip install --upgrade` or fresh deploy could pull a newer Prefab version that changes component APIs, breaking your app. FastMCP's minimum ensures baseline compatibility; your pin ensures stability.
+
+
## Prefab Apps
diff --git a/docs/apps/prefab.mdx b/docs/apps/prefab.mdx
index 0ee703f5e..871ad1b9d 100644
--- a/docs/apps/prefab.mdx
+++ b/docs/apps/prefab.mdx
@@ -10,9 +10,9 @@ import { VersionBadge } from '/snippets/version-badge.mdx'
-
-[Prefab](https://prefab.prefect.io) is in early, active development — its API changes frequently and breaking changes can occur with any release. Always pin `prefab-ui` to a specific version in your dependencies (see below).
-
+
+[Prefab](https://prefab.prefect.io) is in early, active development — breaking changes can occur with any release. FastMCP pins a minimum version of `prefab-ui` for compatibility but does not pin an upper bound. If you are deploying to production, **pin `prefab-ui` to a specific version** in your own dependencies (e.g. `prefab-ui==0.15.0`).
+
[Prefab UI](https://prefab.prefect.io) is the component library behind all FastMCP app features. You describe layouts, charts, tables, and forms in Python, and Prefab compiles them to interactive UIs that render in the host's conversation.