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

Create /home/cal/mcp-gateway/secrets.env with key=value pairs:
```
n8n.api_key=<JWT>
gitea.token=<PAT>
```
Mount it read-only into the container: -v /home/cal/mcp-gateway/secrets.env:/secrets/secrets.env:ro
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)

Secret Resolution Priority (inside gateway)

docker-desktop socket → /run/secrets/mcp_secret → /.env → custom --secrets paths

1.7 KiB Raw Blame History