Docker MCP Gateway

When managing profiles, follow these security guidelines:

• Secrets Management: Use docker mcp secret set for sensitive values (API keys, tokens). Never use docker mcp profile config for secrets; that command is only for non-sensitive configuration.
• Least Privilege: Use docker mcp profile tools to disable all tools (--disable-all) and then explicitly --enable only the specific tools required for the task.
• Environment Isolation: Create separate profiles for dev, staging, and production to ensure production environments do not have access to development tools or debug servers.
• Registry Security: Use private OCI registries for proprietary configurations and review all server references before importing from external sources.

When multiple catalogs contain a server with the same name, the gateway follows a "last loaded wins" precedence order. The order of loading is:

1. Built-in Gateway catalogs (future expansion point)
2. Docker official catalog (docker-mcp.yaml)
3. User configured catalogs (loaded when --use-configured-catalogs is used)
4. CLI-specified catalogs (provided via --catalog or --additional-catalog flags)

The Docker MCP OAuth model centralizes authorization logic to simplify development. Key characteristics include:

• Centralized Implementation: Docker implements the OAuth flows, so third-party developers do not have to.
• Developer Portal: Third parties can register OAuth clients by configuring client_id, client_secret, and redirect_uri via a developer portal.
• Secure Secret Management: Docker provides a secure way to store and access secrets on the user's machine, leveraging the fact that Docker Desktop is already running in the background.
• Trusted Environment: Because Docker Desktop operates in a trusted environment on the user's machine, it can act as a secure proxy for clients that might otherwise lack sufficient trust levels.

When the Docker MCP Gateway loads, it resolves server names using a specific precedence order. If multiple catalogs define a server with the same name, the last-loaded catalog wins.

1. Docker Official Catalog: Always loaded first (base layer).
2. Configured Catalogs: User-imported catalogs.
3. CLI-specified Catalogs: Catalogs passed via the --catalog flag (highest precedence).

The reloadConfiguration process is responsible for synchronizing the gateway's state with the current configuration.

When reloadConfiguration is triggered:

• It extracts capabilities from the current configuration.
• It updates the internal Server.
• It starts up the server to apply these changes.

Note on Dynamic Capabilities: If you are running servers that raise change notifications, their capabilities must also be reloaded during this process. Additionally, any updates to capabilities during a reload will cause change events to be sent to all currently connected clients.

The gateway uses distributed tracing to provide visibility into the flow of an MCP request. Spans are created to track the hierarchy from the gateway execution down to specific server operations.

Span Hierarchy Example

gateway.run
├── tools/list
├── prompts/list
├── resources/list
├── resourceTemplates/list
├── mcp.tool.call
│   └── [tool execution]
├── mcp.prompt.get
│   └── [prompt retrieval]
├── mcp.resource.read
│   └── [resource read]
└── mcp.resource_template.read

Each span captures the operation name, server information, duration, error details, and input parameters (like tool names or resource URIs).

Signature verification is enabled by default for images in the Docker Hub mcp/ namespace.

• Requirement: To enable verification, images must be referenced by their digest.
• Disabling Verification: You can opt-out of signature verification using the --verify-signatures=false flag.
• Third-party Images: Images outside the mcp/ namespace are not verified by Docker MCP signatures; their security depends on your specific catalog or profile configuration.

The telemetry implementation is designed to respect user privacy and existing Docker ecosystems:

• Docker Desktop: Automatically configures an OTEL endpoint (typically a Unix socket). The gateway inherits this configuration and exports metrics to the Docker Desktop backend, which processes and filters them.
• Open Source Docker: Does not include OTEL configuration in the Docker context. In this environment, the gateway's telemetry code runs but does not export any metrics, ensuring no external connections are made and maintaining privacy by default.