store: Docker MCP Gateway secrets workaround for headless Docker Engine (no Docker Desktop)

graph/solutions/docker-mcp-gateway-secrets-workaround-for-headless-docker-en-d82c52.md

@@ -0,0 +1,39 @@
+---
+id: d82c5205-7afd-4e6f-9018-7a701323a11d
+type: solution
+title: "Docker MCP Gateway secrets workaround for headless Docker Engine (no Docker Desktop)"
+tags: [docker-mcp-gateway, mcp, secrets, docker, workaround, headless]
+importance: 0.9
+confidence: 0.8
+created: "2026-02-24T01:52:45.096864+00:00"
+updated: "2026-02-24T01:52:45.096864+00:00"
+---
+
+# Docker MCP Gateway: Secrets on Headless Docker Engine
+
+## Problem
+`docker mcp secret set` requires Docker Desktop's `docker-pass` CLI plugin (looks for it at `/root/.docker/cli-plugins/docker-pass`). On headless Docker Engine (like LXC 303), this plugin doesn't exist. Error: "docker pass has not been installed".
+
+Investigation via `strace` confirmed the `/docker-mcp` binary runs `docker pass`, which looks for the `docker-pass` CLI plugin — NOT the `pass` password manager.
+
+## Workaround: `--secrets` flag with .env file
+1. Create `/home/cal/mcp-gateway/secrets.env` with `key=value` pairs:
+   ```
+   n8n.api_key=<JWT>
+   gitea.token=<PAT>
+   ```
+2. Mount it read-only into the container:
+   `-v /home/cal/mcp-gateway/secrets.env:/secrets/secrets.env:ro`
+3. Pass `--secrets=/secrets/secrets.env` to the gateway at launch
+
+## Important Caveat
+The `--secrets` .env file is used by the gateway runtime when starting MCP server containers, but the `mcp-add` API tool still validates secrets against the Docker Desktop backend and rejects servers with "Missing required secrets".
+
+**Solution:** Use `--servers=name` flag to pre-start servers at gateway launch, bypassing `mcp-add` validation entirely.
+
+## Open GitHub Issues (as of Feb 2026)
+- docker/mcp-gateway#317
+- docker/mcp-gateway#355
+
+## Secret Resolution Priority (inside gateway)
+docker-desktop socket → /run/secrets/mcp_secret → /.env → custom --secrets paths