diff --git a/dev-server-mcp/Dockerfile b/dev-server-mcp/Dockerfile
index 9728d18..b9cedd1 100644
--- a/dev-server-mcp/Dockerfile
+++ b/dev-server-mcp/Dockerfile
@@ -29,6 +29,10 @@ RUN apt-get update \
 ARG MCP_UID=10001
 ARG MCP_GID=10001
 RUN set -eux; \
+  case "${MCP_UID}${MCP_GID}" in *[!0-9]*) \
+    echo "MCP_UID and MCP_GID must be plain numbers; got '${MCP_UID}' and '${MCP_GID}'." >&2; \
+    echo "A compose .env file takes literal values: write the output of 'id -u', not the command." >&2; \
+    exit 2;; esac; \
   if ! getent group "${MCP_GID}" >/dev/null; then groupadd -g "${MCP_GID}" mcp; fi; \
   if ! getent passwd "${MCP_UID}" >/dev/null; then useradd -r -u "${MCP_UID}" -g "${MCP_GID}" -M -d /nonexistent mcp; fi; \
   mkdir -p /tmp/dev-server /instances /npm-cache; \
diff --git a/mcp-stack.env.example b/mcp-stack.env.example
index ab309b5..04f1a45 100644
--- a/mcp-stack.env.example
+++ b/mcp-stack.env.example
@@ -6,6 +6,8 @@ DEV_SERVER_WORKER_TOKEN=replace-with-a-private-worker-token-32-chars
 
 # Use a dedicated project directory, never a home directory or filesystem root.
 MCP_WORKSPACE_HOST_PATH=/absolute/path/to/project
+# Whoever owns the workspace directory on the host. This file is read literally - no shell runs
+# over it - so write the numbers that 'id -u' and 'id -g' print, not the commands themselves.
 MCP_UID=10001
 MCP_GID=10001