From 27045cf90abc1e09032f7975e8c39f9a0225fc9d Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Mon, 23 Feb 2026 19:52:45 -0600 Subject: [PATCH] store: Docker MCP Gateway secrets workaround for headless Docker Engine (no Docker Desktop) --- ...orkaround-for-headless-docker-en-d82c52.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 graph/solutions/docker-mcp-gateway-secrets-workaround-for-headless-docker-en-d82c52.md diff --git a/graph/solutions/docker-mcp-gateway-secrets-workaround-for-headless-docker-en-d82c52.md b/graph/solutions/docker-mcp-gateway-secrets-workaround-for-headless-docker-en-d82c52.md new file mode 100644 index 00000000000..a0de4df8ce8 --- /dev/null +++ b/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= + gitea.token= + ``` +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