---
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