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