diff --git a/nix/agent-modules/mcp.nix b/nix/agent-modules/mcp.nix
index 1ae2af03..dafeda83 100644
--- a/nix/agent-modules/mcp.nix
+++ b/nix/agent-modules/mcp.nix
@@ -131,6 +131,12 @@ in
       it into `--mcp-config` + `--allowedTools`. Take effect on the
       agent's next harness restart (no operator approval needed beyond
       whatever brought the new agent.nix into deployed/*).
+
+      The `bash` entry above is illustrative only — it's auto-injected
+      below (`hyperhive.extraMcpServers.bash` via `lib.mkDefault`) already
+      tracking `hyperhive.mcp.bashHttpPort`, so overriding it directly
+      with a hardcoded port (as shown) is unusual and will drift if
+      `bashHttpPort` is changed separately; bump `bashHttpPort` instead.
     '';
   };