From 9d111d9d703f02551f5bf020b76ed861d45fd1f1 Mon Sep 17 00:00:00 2001
From: Speculator55005 <50082482+fas89@users.noreply.github.com>
Date: Sun, 11 Oct 2026 10:06:22 +0200
Subject: [PATCH] docs(mcp): the minimum mcp is 1.22; 1.20 and 1.21 fail to
 import with pydantic 2.14 (forge-cli #710)

---
 docs/cli/mcp.md                     | 4 ++--
 docs/walkthrough/mcp-output-port.md | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/cli/mcp.md b/docs/cli/mcp.md
index d3fb183..99fc4ea 100644
--- a/docs/cli/mcp.md
+++ b/docs/cli/mcp.md
@@ -81,9 +81,9 @@ Both servers run on the official `mcp` Python SDK.
 
 | | |
 | --- | --- |
-| **Dependency pin** | `mcp>=1.20,<3.0` |
+| **Dependency pin** | `mcp>=1.22,<3.0` *(unreleased, [forge-cli #710](https://github.com/Agenticstiger/forge-cli/pull/710); 0.19.0 and earlier pin `mcp>=1.20,<3.0`)* |
 | **What a fresh install resolves** | The newest `2.x`. `mcp` is a core dependency rather than an extra, so `pip install data-product-forge` picks it up. A fresh 0.18.1 install resolved `mcp 2.3.0` on 5 Oct 2026. |
-| **Existing environments** | Do not move until you upgrade them. Pinning `mcp>=1.20,<2.0` yourself remains supported. |
+| **Existing environments** | Do not move until you upgrade them. Pinning `mcp>=1.22,<2.0` yourself remains supported. mcp 1.20 and 1.21 fail to import with pydantic 2.14 or later, which removed a private helper they import; keep pydantic below 2.14 if you must stay on them. |
 | **3.x** | Outside the pin. |
 
 The protocol version is negotiated by the SDK at `initialize`, not fixed by Forge. A client built on that `mcp 2.3.0` was offered `2025-11-25` by both servers.
diff --git a/docs/walkthrough/mcp-output-port.md b/docs/walkthrough/mcp-output-port.md
index 0235a47..b93878e 100644
--- a/docs/walkthrough/mcp-output-port.md
+++ b/docs/walkthrough/mcp-output-port.md
@@ -343,7 +343,7 @@ declared capabilities under `experimental.fluid`, which both SDK generations par
 ```
 
 An existing environment does not move until it is upgraded, and pinning
-`mcp>=1.20,<2.0` still works. None of this applies once authentication is enforced:
+`mcp>=1.22,<2.0` still works (mcp 1.20 and 1.21 fail to import with pydantic 2.14 or later). None of this applies once authentication is enforced:
 verified JWT claims replace self-attestation outright, and with `FLUID_MCP_AUTH_TOKEN` set the self-attested values are dropped.
 :::