store: Docker MCP Gateway architecture: dynamic vs static server activation modes

graph/insights/docker-mcp-gateway-architecture-dynamic-vs-static-server-act-b81fd2.md

@@ -0,0 +1,38 @@
+---
+id: b81fd2b1-d974-4060-85f9-7a5c3c41b751
+type: insight
+title: "Docker MCP Gateway architecture: dynamic vs static server activation modes"
+tags: [docker-mcp-gateway, mcp, architecture, insight]
+importance: 0.6
+confidence: 0.8
+created: "2026-02-24T01:52:56.353969+00:00"
+updated: "2026-02-24T01:52:56.353969+00:00"
+---
+
+# Docker MCP Gateway: Dynamic vs Static Server Activation
+
+## Two Activation Modes
+
+### 1. Dynamic (default)
+Gateway starts with only built-in tools: `mcp-find`, `mcp-add`, `mcp-config-set`, `mcp-exec`, `code-mode`, `mcp-remove`. Claude Code uses `mcp-add` at runtime to spin up server containers on demand.
+
+**Problem:** `mcp-add` validates secrets against Docker Desktop backend. Fails on headless Docker Engine with "Missing required secrets".
+
+### 2. Static (`--servers` flag)
+Pre-starts named servers at gateway launch. Bypasses `mcp-add` validation. All server tools appear immediately in `tools/list`.
+
+```bash
+# Example: pre-start n8n and gitea
+--servers=n8n --servers=gitea
+```
+
+**Preferred approach for headless Docker Engine environments.**
+
+## Key Paths Inside Gateway Container (Alpine-based)
+- `/root/.docker/mcp/config.yaml` — per-server config
+- `/root/.docker/mcp/registry.yaml` — enabled servers
+- `/root/.docker/config.json` — Docker credential store config
+- `/misc/` — volume for docker-mcp-bridge binary
+
+## Secret Resolution Priority
+docker-desktop socket → /run/secrets/mcp_secret → /.env → custom --secrets paths