diff --git a/.gitea/workflows/image-only.yml b/.gitea/workflows/image-only.yml
index 9d507d53..a6d30c2e 100644
--- a/.gitea/workflows/image-only.yml
+++ b/.gitea/workflows/image-only.yml
@@ -96,6 +96,13 @@ jobs:
             -t "${REGISTRY_PUSH}/${IMAGE}:${SHA_TAG}" \
             -t "${REGISTRY_PUSH}/${IMAGE}:${CORPUS_TAG}" \
             .
+          # Smoke: the image must at least import its server module before we
+          # publish it. mcp 2.x renamed mcp.server.fastmcp -> mcp.server.mcpserver,
+          # so an unpinned dep produced a green build that crash-looped in prod
+          # for 9 days (2026-09-01 -> 09-10). Import is side-effect-free here
+          # (lazy singletons), so this needs no Ollama/Chroma.
+          docker run --rm --entrypoint python \
+            "${REGISTRY_PUSH}/${IMAGE}:latest" -c "import docs_mcp.server"
           docker push "${REGISTRY_PUSH}/${IMAGE}:latest"
           docker push "${REGISTRY_PUSH}/${IMAGE}:${SHA_TAG}"
           docker push "${REGISTRY_PUSH}/${IMAGE}:${CORPUS_TAG}"
diff --git a/.gitea/workflows/refresh.yml b/.gitea/workflows/refresh.yml
index e32c9b0f..4702c8ab 100644
--- a/.gitea/workflows/refresh.yml
+++ b/.gitea/workflows/refresh.yml
@@ -179,6 +179,13 @@ jobs:
             -t "${REGISTRY_PUSH}/${IMAGE}:${SHA_TAG}" \
             -t "${REGISTRY_PUSH}/${IMAGE}:${CORPUS_TAG}" \
             .
+          # Smoke: the image must at least import its server module before we
+          # publish it. mcp 2.x renamed mcp.server.fastmcp -> mcp.server.mcpserver,
+          # so an unpinned dep produced a green build that crash-looped in prod
+          # for 9 days (2026-09-01 -> 09-10). Import is side-effect-free here
+          # (lazy singletons), so this needs no Ollama/Chroma.
+          docker run --rm --entrypoint python \
+            "${REGISTRY_PUSH}/${IMAGE}:latest" -c "import docs_mcp.server"
           docker push "${REGISTRY_PUSH}/${IMAGE}:latest"
           docker push "${REGISTRY_PUSH}/${IMAGE}:${SHA_TAG}"
           docker push "${REGISTRY_PUSH}/${IMAGE}:${CORPUS_TAG}"
diff --git a/requirements.txt b/requirements.txt
index 78d7261c..79bbb463 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,5 +1,5 @@
 # MCP server
-mcp[fastmcp]>=1.0.0
+mcp[fastmcp]>=1.0.0,<2  # 2.x removed mcp.server.fastmcp (FastMCP -> MCPServer); see docs_mcp/server.py
 pydantic>=2.0
 httpx>=0.27