mait.sh1.69.2

Private beta: features and content may change. No warranty; use at your own risk.

Docs / Agent tools (MCP)

MCP Docker

Operate Docker resources through structured requests and inspect the resulting container, image or network state.

For agent operators and platform teams that need stateful build, test, and reproduction environments on a Docker host.

Read from the top for the basics; the later sections go deeper.

Beta
All components

What it doesBasics

  • Container lifecycle, exec, copy, logs, stats, and health
  • Image build, pull, push, tag, inspect, removal, and prune
  • Network and volume lifecycle
  • MCP session ownership, quotas, tags, discovery, and container adoption
  • Metrics, health endpoints, and audit-oriented tracing

First useBasics

  1. Inspect the intended daemon and an owned evaluation container before changing resources.
  2. Run iterative work and inspect its output and state.
  3. Clean up explicitly before the session ends when teardown is intended.

Everyday tasksEveryday use

Run a stateful agent container

An agent needs a persistent environment for an iterative build, test, and repair loop.

  1. Start MCP Docker as an MCP server with an allowed-registry policy.
  2. Call run_container with an allowed image, a stable name, and explicit memory/PID limits.
  3. Verify the returned ID with list_containers, then execute work and inspect logs or health.
  4. Call cleanup_session before every success, failure, timeout, or cancellation path disconnects.

What you getThe iterative workload retains state while MCP ownership and teardown remain explicit.

How to check: Container ID, cross-session-visible inventory, health, command results, logs, and cleanup output document the lifecycle.

Build and verify an image

A change must be built into a container image and exercised before publication.

  1. Build the image through the mediated tool surface.
  2. Start a health-checked container and inspect its status and logs.
  3. Clean session resources explicitly and remove the image separately when required.

What you getThe image is exercised through the same controlled operation path used for runtime work.

How to check: Build result, container health, logs, explicit cleanup, and image-removal results support review.

Settings to decideAdvanced

Docker daemon
DOCKER_HOST takes a Unix socket; review the service account’s effective daemon privileges.
Allowed registries and quotas
ALLOWED_REGISTRIES defaults to docker.io,ghcr.io; MAX_CONTAINERS_PER_SESSION defaults to 100 (MCP_CONTAINER_LIMIT is its legacy alias).
State and session lifetime
Persistent state is the default at STATE_FILE_PATH=tmp/state.json; USE_MEMORY_STATE=true opts out. LEDGER_ENTRY_TTL_SECS defaults to 86400 and reclaims empty bookkeeping entries. cleanup_session runs over MCP; the CLI is a separate, session-independent tenancy.
Timeouts and retries
OPERATION_TIMEOUT_SECS defaults to 120, with build/pull/push/wait fixed at 300. RUNTIME_MAX_RETRIES defaults to 3 and RUNTIME_RETRY_DELAY_MS to 100.
Metrics and health
ENABLE_METRICS opts into an HTTP listener; METRICS_PORT defaults to 9090. Expose /metrics and /health* only inside the intended operations boundary; RUST_LOG controls server diagnostics.

CommandsAdvanced

$ mcp-docker version
$ mcp-docker serve
$ run_container({"image":"nginx:alpine","name":"agent-sandbox","resources":{"memory_mb":512,"pids_limit":128}})
$ list_containers({"all":true}) # verify agent-sandbox and retain its ID
$ cleanup_session({"force":true}) # MCP only; call before disconnect
$ mcp-docker cli container ls # separate non-session CLI tenancy
$ mcp-docker cli container run nginx:alpine

Problems and fixesHelp

What you seeCheckFix
Docker operations cannot connect.Verify the Unix socket path, permissions, and daemon health.Restore the reviewed socket binding and service permission, then retry a read-only status operation.
An image pull is rejected.Compare the image registry with ALLOWED_REGISTRIES.Use an approved image source or update policy through the operator review process.
A resource exists but the current session cannot mutate it.Inspect its session label and current ownership tracker.Adopt an eligible container or use direct operator procedures for an orphaned network or volume.
Resources remain after the client disconnects.Confirm whether cleanup_session ran before disconnect.Reconnect and adopt eligible containers or perform precise operator cleanup.
What you see
Docker operations cannot connect.
Check
Verify the Unix socket path, permissions, and daemon health.
Fix
Restore the reviewed socket binding and service permission, then retry a read-only status operation.
What you see
An image pull is rejected.
Check
Compare the image registry with ALLOWED_REGISTRIES.
Fix
Use an approved image source or update policy through the operator review process.
What you see
A resource exists but the current session cannot mutate it.
Check
Inspect its session label and current ownership tracker.
Fix
Adopt an eligible container or use direct operator procedures for an orphaned network or volume.
What you see
Resources remain after the client disconnects.
Check
Confirm whether cleanup_session ran before disconnect.
Fix
Reconnect and adopt eligible containers or perform precise operator cleanup.

All MCP Docker problems and fixes →

Good to knowHelp

  • MCP Docker is a standalone MAIT capability, installed separately from the MAIT image.
  • The service controls the Docker daemon it connects to.
  • Session ownership gates mutations of managed resources.
  • Containers can be adopted into a session under operator policy.
  • Disconnect leaves resources running; call cleanup_session before the session ends to tear them down.