39 lines
1.4 KiB
Markdown
39 lines
1.4 KiB
Markdown
---
|
|
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
|