diff --git a/README.md b/README.md
index 720d9e6..5c4f826 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,11 @@ That creates and validates a typed RP2040 project. Continue to
 [generate the full demo candidate](#generate-the-demo-candidate), or run
 `hw --help` to inspect the CLI.
 
+The published package has also been independently exercised in a disposable
+Debian 13 x86-64 container with Python 3.11.15. See the
+[clean-platform reproduction report](docs/pypi-quickstart-reproduction.md) for
+the exact environment, commands, and passing output.
+
 <details>
 <summary><strong>What the public demo proves—and what remains blocked</strong></summary>
 
diff --git a/docs/pypi-quickstart-reproduction.md b/docs/pypi-quickstart-reproduction.md
new file mode 100644
index 0000000..afc938c
--- /dev/null
+++ b/docs/pypi-quickstart-reproduction.md
@@ -0,0 +1,79 @@
+# PyPI quickstart clean-platform reproduction
+
+The public `hw-codesign[mcp]==0.1.4` quickstart passes in a disposable Linux
+container. This run installed only the published PyPI distribution: the
+container had no repository checkout or host directory mounted into it.
+
+## Environment
+
+| Field | Observed value |
+|---|---|
+| Run date | 2026-07-29 |
+| Operating system | Debian GNU/Linux 13.6 (trixie) |
+| Architecture | x86-64 (`x86_64`; Docker `amd64`) |
+| Python | CPython 3.11.15 |
+| pip | 24.0 |
+| Container image | `python:3.11-slim` |
+| Image digest | `sha256:db3ff2e1800a8581e2c48a27c3995339d47bdf046da21c7627accd3d51053a93` |
+| Package source | PyPI |
+| Package | `hw-codesign[mcp]==0.1.4` |
+
+## Reproduction command
+
+From a machine with Docker installed:
+
+```bash
+docker run --rm --pull=always python:3.11-slim sh -euxc '
+cat /etc/os-release
+uname -m
+python --version
+python -m pip --version
+python -m pip install "hw-codesign[mcp]==0.1.4"
+mkdir /tmp/my-hardware-workspace
+cd /tmp/my-hardware-workspace
+hw --root . create-project my_usb_board --template rp2040_usb_device
+hw --root . validate-spec my_usb_board
+'
+```
+
+The image was pulled immediately before the run. The digest above records the
+exact image that the tag resolved to for this reproduction.
+
+## Result
+
+The install completed with `Successfully installed ... hw-codesign-0.1.4`.
+The environment probes and two quickstart commands then returned:
+
+```text
+PRETTY_NAME="Debian GNU/Linux 13 (trixie)"
+VERSION_ID="13"
+DEBIAN_VERSION_FULL=13.6
+x86_64
+Python 3.11.15
+pip 24.0 from /usr/local/lib/python3.11/site-packages/pip (python 3.11)
+
++ hw --root . create-project my_usb_board --template rp2040_usb_device
+{
+  "project_path": "/tmp/my-hardware-workspace/projects/my_usb_board",
+  "status": "generated",
+  "template": "rp2040_usb_device"
+}
++ hw --root . validate-spec my_usb_board
+{
+  "artifacts": [],
+  "backend": {},
+  "failures": [],
+  "gate": "spec_schema",
+  "metrics": {
+    "errors": 0,
+    "warnings": 0
+  },
+  "status": "pass"
+}
+```
+
+No Linux-specific installation or packaging friction was observed.
+
+This result verifies installation, bundled template and schema discovery, and
+typed-project activation. It does not generate a full hardware candidate or
+qualify any design for fabrication.
diff --git a/pyproject.toml b/pyproject.toml
index 86fbb2d..84808c1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,7 +36,9 @@ Repository = "https://github.com/mrcha033/hw-codesign"
 Issues = "https://github.com/mrcha033/hw-codesign/issues"
 
 [project.optional-dependencies]
-mcp = ["mcp>=1.0"]
+# mcp 2.0 removed the bundled ``mcp.server.fastmcp`` module that mcp_server.py
+# builds the server on, so keep this extra on the 1.x line.
+mcp = ["mcp>=1.0,<2"]
 cad = ["cadquery-ocp==7.9.3.1.1"]
 dev = ["pytest>=8.3", "pytest-cov>=6.0", "ruff>=0.9"]
 zephyr = [
diff --git a/uv.lock b/uv.lock
index 17e8419..d26a89c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -899,7 +899,7 @@ requires-dist = [
     { name = "intelhex", marker = "extra == 'zephyr'" },
     { name = "jsonschema", specifier = ">=4.23" },
     { name = "kicad-sch-api", specifier = "==0.5.6" },
-    { name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.0" },
+    { name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.0,<2" },
     { name = "packaging", marker = "extra == 'zephyr'" },
     { name = "patool", marker = "extra == 'zephyr'", specifier = ">=2.0.0" },
     { name = "progress", marker = "extra == 'zephyr'" },