# docker/mcp-gateway architecture

> Architecture diagram of the GitHub repository docker/mcp-gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docker/mcp-gateway
- Repository: https://github.com/docker/mcp-gateway

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% AI Client
    AIC["AI Client"]:::external

    %% CLI & Gateway Zone (Blue)
    subgraph "CLI & Gateway (Go Code)" 
        style CLIZone fill:#bbdefb,stroke:#000
        CLIEntrypoint["Entrypoint\n(main.go)"] 
        Commands["CLI Commands"] 
        CatalogMgr["Catalog Manager"] 
        ServerMgr["Server Manager"] 
        ConfigMgr["Config & Registry Manager"] 
        SecretMgr["Secret Management"] 
        OAuthFlow["OAuth Flows"] 
        ToolMgr["Tool Manager"] 
        Telemetry["Telemetry Subsystem"] 
        Interceptors["Interceptors"] 
        DockerAdapter["Docker Engine Adapter"] 
        GatewayRun["MCP Gateway Runtime"] 
        Transports["Transports\n(stdio & HTTP)"] 
        Handlers["Gateway Handlers & Routing"] 
    end

    %% Docker Engine Zone (Gray)
    DockerEngine[(Docker Engine\nREST API)]:::gray

    %% MCP Servers Zone (Green)
    subgraph "MCP Servers (Containers)"
        style ServersZone fill:#c8e6c9,stroke:#000
        ServerA["MCP Server A"]
        ServerB["MCP Server B"]
        ServerC["MCP Server C"]
    end

    %% Config Store
    ConfigStore[(Local Config Store\n~/.docker/mcp)]:::gray

    %% External Services Zone (Orange)
    subgraph "External Services"
        style ExternalZone fill:#ffe0b2,stroke:#000
        OAuthProvider["OAuth Provider"]
        OTEL["OTEL Collector"]
    end

    %% Connections
    AIC -->|"docker mcp …"| CLIEntrypoint
    CLIEntrypoint --> Commands
    CLIEntrypoint --> CatalogMgr
    CLIEntrypoint --> ServerMgr
    CLIEntrypoint --> ConfigMgr
    CLIEntrypoint --> SecretMgr
    CLIEntrypoint --> OAuthFlow
    CLIEntrypoint --> ToolMgr
    CLIEntrypoint --> Telemetry
    CLIEntrypoint --> Interceptors
    CLIEntrypoint --> DockerAdapter

    CLIEntrypoint -->|invoke gateway| GatewayRun
    GatewayRun --> Transports
    GatewayRun --> Handlers
    Handlers -->|route via proxies| ServerA
    Handlers -->|route via proxies| ServerB
    Handlers -->|route via proxies| ServerC
    ServerA <-->|response| Handlers
    ServerB <-->|response| Handlers
    ServerC <-->|response| Handlers
    Handlers -->|reply| GatewayRun
    GatewayRun -->|forward| AIC

    CLIEntrypoint -.->|Docker API| DockerEngine
    CLIEntrypoint -.->|read/write| ConfigStore
    CLIEntrypoint -.->|OAuth flow| OAuthProvider
    Telemetry -.->|emit metrics| OTEL

    %% Click Events
    click CLIEntrypoint "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/main.go"
    click Commands "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/commands/"
    click CatalogMgr "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/catalog/"
    click CatalogMgr "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/internal/catalog/"
    click ServerMgr "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/server/"
    click ConfigMgr "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/internal/config/"
    click SecretMgr "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/secret-management/"
    click OAuthFlow "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/oauth/"
    click OAuthFlow "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/desktop/auth.go"
    click ToolMgr "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/tools/"
    click Telemetry "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/telemetry/telemetry.go"
    click Interceptors "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/internal/interceptors/"
    click DockerAdapter "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/internal/docker/"
    click GatewayRun "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/commands/gateway.go"
    click Handlers "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/gateway/handlers.go"
    click Handlers "https://github.com/docker/mcp-gateway/tree/main/cmd/docker-mcp/internal/gateway/proxies/"
    click Transports "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/mcp/stdio.go"
    click Transports "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/gateway/transport.go"
    click ConfigStore "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/config/readwrite.go"
    click ConfigStore "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/config/registry.go"
    click ConfigStore "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/config/tools.go"
    click SecretMgr "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/desktop/secrets.go"
    click SecretMgr "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/desktop/connection_*.go"
    click Interceptors "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/contextkeys/keys.go"
    click Interceptors "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/health/health.go"
    click Interceptors "https://github.com/docker/mcp-gateway/blob/main/cmd/docker-mcp/internal/logs/prefix.go"

    %% Styles
    classDef external fill:#ffffff,stroke:#000
    classDef gray fill:#eeeeee,stroke:#000
    classDef blue fill:#bbdefb,stroke:#000
    classDef green fill:#c8e6c9,stroke:#000
    classDef orange fill:#ffe0b2,stroke:#000
```
