How docker/mcp-gateway works
Project Type & Purpose
• This is a Go-based Docker CLI plugin (“docker-mcp”) plus a gateway component that implements the Model Context Protocol (MCP).
• It provides a unified CLI interface and gateway runtime to manage, discover, and route AI client calls to MCP servers running as Docker containers.
High-Level Architecture & Main Components
A. AI Clients (e.g. VS Code, Claude Desktop, Cursor)
B. Docker CLI Plugin (“docker mcp”)
• Entrypoint & commands (cmd/docker-mcp)
• Subsystems:
• Catalog manager
• Server manager
• Config & registry manager (internal/config)
• Secret & OAuth flows (internal/desktop, cmd/oauth, cmd/secret)
• Tool manager
• Telemetry & interceptors (internal/telemetry, internal/interceptors)
C. MCP Gateway Runtime
• Transports: stdio, streaming HTTP (cmd/docker-mcp/gateway)
• Handlers & routing logic (internal/gateway)
D. Docker Engine & Daemon
• Exposes REST API to spin up MCP server containers
E. MCP Servers (each a Docker container)
• Isolated containers, minimal host privileges
F. Local State & Configuration Store
• Files under ~/.docker/mcp: catalogs, registry.yaml, config.yaml, tools.yaml
G. External Services
• OAuth providers (GitHub, etc.)
• Telemetry / OpenTelemetry collector
• Desktop secret store
Relationships & Data Flows
1. AI Client → Docker CLI plugin (docker mcp …)
2. CLI invokes Gateway runtime (stdio or HTTP)
3. Gateway handlers parse MCP protocol, apply interceptors (logging, secrets-blocking, telemetry)
4. Gateway routes calls through L4/L7 proxies (tools/l4proxy, tools/l7proxy) to target MCP server container
5. Gateway awaits response, applies post-processing (telemetry, logs), forwards data back to client
6. CLI interacts with Docker Engine API to register/unregister servers, pull images, manage container lifecycles
7. CLI reads/writes local config store for catalogs, enabled servers, per-server configs, tool lists
8. CLI performs OAuth flows with external identity providers, storing tokens in desktop secret store
9. Telemetry subsystem emits metrics & traces to OTEL collector
Architectural Patterns & Principles
• Gateway Pattern: central message broker translating between AI client and server containers
• Plugin Pattern: Docker CLI extension
• Adapter Layers: internal/desktop abstracts across OSs, internal/docker abstracts Docker API
• Micro-service Deployment: each MCP server as discrete container
• Modular Design: cmd/ for CLI surface, internal/ for reusable domain logic
• Cross-cutting Concerns via Interceptors: logging, telemetry, secret-scan
g. Above or aside, place external services (OAuth provider, OTEL collector), connect to CLI (OAuth flows) and telemetry module.