diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index a34c5e8c..fcdff0a8 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -227,7 +227,7 @@ jobs:
           # it so test coverage exists. If mcp install fails (Python 3.13
           # wheel not yet available, etc.), tests/test_mcp_server.py uses
           # importorskip and the matrix stays green.
-          pip install mcp || echo "mcp install failed — test_mcp_server.py will importorskip"
+          pip install "mcp<2" || echo "mcp install failed — test_mcp_server.py will importorskip"
 
       - name: Get Playwright version
         if: needs.changes.outputs.docs_only != 'true'
diff --git a/mcp_server.py b/mcp_server.py
index 53ff2ef4..1eeeb900 100644
--- a/mcp_server.py
+++ b/mcp_server.py
@@ -7,7 +7,7 @@ Option A rewrite (2026-05-08): imports api.models and api.profiles
 directly from the webui codebase, using canonical helpers for
 locking, profile scoping, index consistency, and validation.
 
-    pip install mcp       # one-time setup
+    pip install "mcp<2"   # one-time setup
     python3 mcp_server.py # start via stdio
 
 MCP config for Hermes Agent (add to config.yaml):
diff --git a/requirements-dev.txt b/requirements-dev.txt
index d6b5ca39..78bcc82a 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -8,7 +8,7 @@ pytest-timeout
 pytest-asyncio
 pytest-shard
 ruff
-mcp
+mcp<2
 # Optional Office parsers — runtime-optional (commented in requirements.txt), but
 # installed here so the workspace Office-preview tests (tests/test_issue540_*.py)
 # run under the documented ./scripts/test.sh entry point. These files
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 98e2a0b2..53044a3b 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -18,10 +18,8 @@ from pathlib import Path
 import pytest
 
 # Skip the entire module when the optional `mcp` package isn't installed.
-# CI runs with stdlib-only deps (pyyaml + pytest + pytest-timeout), and the
-# `mcp` package is only required for users who actually run the MCP server.
-# Locally with `pip install mcp pytest-asyncio` these tests run; on CI they
-# skip cleanly without breaking the matrix.
+# CI and the local test runner install the compatible dependency; minimal
+# runtime environments can still collect the rest of the suite without it.
 pytest.importorskip("mcp", reason="mcp package not installed (optional MCP server dep)")
 
 # pytest-asyncio is also optional but always installed alongside mcp tests