Docker MCP Gateway Agent Rules

A Docker CLI plugin that connects AI clients to containerized MCP servers.

Overview

Docker MCP Gateway's CLAUDE.md introduces a Go CLI plugin, its gateway, and the container lifecycle. It defines three kinds of configuration and the Docker and cache state needed for integration tests.

Architecture as narrative Verification by change type

Documents

└──

Techniques in this file

01 / Architecture as narrative

Start with the actors in the connection flow

The architecture starts with an AI client, the gateway, and its containerized servers. It then maps routing, client management, server lifecycle, catalogs, and secrets to their implementation directories.

12- **AI Client** connects to the **MCP Gateway** 13- **MCP Gateway** (this CLI) manages multiple **MCP Servers** running in Docker containers

02 / Architecture as narrative

Distinguish configuration by responsibility

The same configuration directory holds catalogs, runtime settings, and the enabled-server registry. Naming their separate responsibilities helps prevent an edit to one kind of configuration from being mistaken for another.

130- Server definitions are loaded from catalog files131- Runtime configuration is managed through config.yaml132- Server enablement tracked in registry.yaml

03 / Architecture as narrative

State the lifecycle obligations of managed containers

The guide describes validation before use, naming conventions, health checks, logging, and shutdown cleanup. That sequence provides context for changes affecting how a server is started or stopped.

135MCP servers run as Docker containers with proper lifecycle management:136- Images are pulled and validated before use  137- Containers have consistent naming patterns138- Health checks and logging are built-in139- Proper cleanup on shutdown

04 / Verification by change type

Make integration-test prerequisites explicit

The testing section says that integration tests need a Docker daemon and long-lived tests run real containers. It also disables Go test caching when exercising those scenarios.

142- Integration tests require Docker daemon143- Long-lived tests run actual container scenarios144- Mock configurations in testdata directories145- Use `go test -count=1` to disable test caching

Ideas for your repo

Explain the actors and connection flow before listing directories.
Separate files by the configuration responsibility each owns.
Document startup and shutdown obligations for managed resources.
State external-service and cache requirements beside integration-test commands.