MCP Tools for containerd — gRPC API, task lifecycle, and snapshot management

containerd architecture: namespaces, images, snapshots, containers, and tasks

containerd organizes all resources into namespaces. A namespace is an isolation boundary — images, containers, and snapshots in one namespace are invisible to another. Kubernetes uses the k8s.io namespace; Docker uses moby. For MCP-managed workloads, create a dedicated namespace (e.g., mcp) to avoid accidental interference with Kubernetes-managed containers on the same node.

The five resource types and their relationships:

• Image — an OCI image manifest with its associated layer blobs, stored in the content store. Pulling an image downloads blobs and registers the manifest.
• Snapshot — a copy-on-write filesystem layer. The snapshotter creates a writable active snapshot on top of image layers; this becomes the container's root filesystem. Multiple containers can be created from the same image by creating separate snapshots.
• Container — metadata only. A containerd container record associates a snapshot, an OCI runtime spec, and labels. Creating a container does not start any process.
• Task — the running instance. A task is created from a container, specifying I/O streams. Starting a task launches the container's init process via the containerd shim and OCI runtime (runc, gVisor, etc.).
• Exec process — an additional process running inside a task's namespace, created via task.exec().

Node.js MCP tools interact with containerd via the @containerd/containerd client or directly over gRPC using @grpc/grpc-js with generated protobuf stubs. The containerd client library is simpler:

import { Client } from '@containerd/containerd';

const client = new Client('/run/containerd/containerd.sock', {
  namespace: 'mcp'
});

// List all containers in the 'mcp' namespace
const containers = await client.containers();
for (const c of containers) {
  console.log(c.id, c.labels);
}

The full lifecycle: pull → snapshot → container → task → start

containerd requires each lifecycle step to be called explicitly. This is more verbose than Docker's run but allows precise control over each step and clean recovery when a step fails.

Step 1: Pull the image

const image = await client.pull('docker.io/library/nginx:alpine', {
  resolved: true   // wait until all layers are downloaded
});
// image.name() returns the fully-qualified image reference
// image.size() returns total uncompressed layer size in bytes

Step 2: Create a snapshot (writable layer)

The snapshotter creates the container's writable root filesystem. You must explicitly unpack the image into the snapshotter before creating a snapshot from it:

// Unpack the image layers into the default snapshotter
await image.unpack(defaultSnapshotter);

// The snapshot key must be unique — use the container ID you plan to assign
const snapshotKey = `mcp-container-${Date.now()}`;
// 'prepare' creates an active (writable) snapshot on top of the image layers
// This does NOT copy all data — it creates a CoW overlay
const mounts = await client.snapshotService('overlayfs').prepare(
  snapshotKey,
  image.target.digest   // parent layer chain
);

Step 3: Create the container (metadata only)

const container = await client.newContainer('my-nginx', {
  image,
  snapshotter: 'overlayfs',
  snapshot: snapshotKey,
  runtime: { name: 'io.containerd.runc.v2' },
});

Step 4: Create a task (configure process)

const task = await container.newTask({
  stdin: process.stdin,     // or null for no stdin
  stdout: process.stdout,   // or a file stream
  stderr: process.stderr,
});

Step 5: Start the task (begin execution)

await task.start();
// The task's init process is now running
// task.pid() returns the host PID of the init process in the containerd shim
console.log('Task started with shim PID:', task.pid());

The full five-step lifecycle means that errors at each step are distinct. If pull fails, no snapshot or container exists. If prepare fails, the container and task don't exist. If task.start() fails, the container record exists and the snapshot exists — both must be cleaned up explicitly with task.delete() and container.delete() and snapshotService.remove(snapshotKey). Always implement cleanup in the reverse order of creation.

Snapshot management: committed vs active, and cleanup patterns

containerd's snapshotter manages two types of snapshots. An active snapshot is writable — it is prepared from a parent (the image layers) and is used exclusively by one container's filesystem. A committed snapshot is read-only — you create a committed snapshot from an active one using commit(), which is how container image layers are created. For MCP tools that only run containers, you will primarily work with active snapshots.

Snapshot naming matters for cleanup. containerd does not automatically associate a snapshot with a container by name — you must track the relationship yourself. A practical pattern is to name the active snapshot after the container ID with a prefix:

// Naming convention: {namespace}-{containerId}-rootfs
const snapshotKey = `mcp-${containerId}-rootfs`;

// List all active snapshots in the mcp namespace
const snapshotter = client.snapshotService('overlayfs');
for await (const snap of snapshotter.list()) {
  console.log(snap.key, snap.kind, snap.created_at);
}

// Cleanup: remove active snapshot after task and container are deleted
// Order matters: task → container → snapshot
await task.delete({ force: true });    // kills the process, removes shim
await container.delete();              // removes metadata
await snapshotter.remove(snapshotKey); // removes the writable layer

A common leak pattern: MCP tools that create containers but fail before starting the task leave active snapshots behind. These snapshots hold disk space but have no associated container metadata (the container record was never committed or was deleted). Implement a periodic garbage collection routine that lists all snapshots with the MCP prefix and checks whether the corresponding container still exists — if not, remove the orphaned snapshot.

exec processes: running commands inside a task

containerd's task.exec() creates a new process inside the task's namespace, analogous to Docker's exec. The exec process shares the task's mount namespace, network namespace, and PID namespace. It does not share the task's lifecycle — the exec process can exit independently of the init process, and the init process can exit while an exec process is still running (though the task will transition to the STOPPED state, which prevents new exec calls).

// Run a command inside a running task
async function execInTask(task, cmd) {
  const execId = `exec-${Date.now()}`;
  const process = await task.exec(execId, {
    args: cmd,               // e.g., ['/bin/sh', '-c', 'cat /proc/version']
    env: [],
    cwd: '/',
    terminal: false,
    stdout: true,
    stderr: true,
  });

  // Collect output
  let stdout = '', stderr = '';
  process.stdout?.on('data', d => stdout += d);
  process.stderr?.on('data', d => stderr += d);

  await process.start({});  // actually start the exec process
  const status = await process.wait();  // wait for exit

  return {
    exitCode: status.exitCode,
    stdout,
    stderr,
  };
}

Exec processes must be explicitly deleted after they exit: call process.delete() to clean up the exec metadata in containerd. Failing to delete completed exec processes accumulates metadata in the containerd store. A task can have multiple concurrent exec processes — containerd does not limit the count, but the host kernel limits the total number of processes. For MCP tools that run many concurrent exec operations on the same task, implement a semaphore or queue to bound the concurrency.

Health probe depth: task RUNNING is not process health

containerd's task status has four states: CREATED, RUNNING, STOPPED, and PAUSED. RUNNING means the containerd shim holds a reference to the init process and the process has not yet exited. It does not mean the process is responsive, the network stack is ready, or that the application inside is healthy.

async function taskHealth(task) {
  const status = await task.status();
  // status.status: RUNNING, STOPPED, PAUSED, CREATED
  // status.exitStatus: the exit code if STOPPED

  if (status.status !== TaskState.RUNNING) {
    return {
      healthy: false,
      reason: `task_${status.status.toLowerCase()}`,
      exitCode: status.exitStatus,
    };
  }

  // Task is RUNNING — verify the process inside is functional
  // Option 1: exec a health check command
  try {
    const result = await execInTask(task, ['sh', '-c', 'wget -qO- http://localhost:8080/health || exit 1']);
    if (result.exitCode !== 0) {
      return { healthy: false, reason: 'health_check_failed', stderr: result.stderr };
    }
    return { healthy: true };
  } catch (e) {
    return { healthy: false, reason: 'exec_failed', error: e.message };
  }
}

Unlike Docker, containerd has no built-in HEALTHCHECK equivalent. There is no health.status field in the task metadata. All health checking beyond "is the task RUNNING?" must be implemented by the MCP tool itself — either via exec-based probes or via external HTTP checks registered with AliveMCP. For containers running HTTP servers, register the container's published port with AliveMCP so that monitoring continues even when the MCP server is unavailable.

A task that becomes STOPPED unexpectedly (exit code != 0) does not restart automatically — there is no containerd equivalent of Docker's restart policy. MCP tools managing long-lived services via containerd must implement their own restart logic: watch for STOPPED events using the containerd events API (client.events()), filter for task exit events, and restart on non-zero exit codes according to your policy.

Watching containerd events for reactive monitoring

containerd emits events for all lifecycle transitions: image pull completion, task creation, task start, task exit, and snapshot operations. MCP tools can subscribe to these events for reactive monitoring rather than polling:

// Subscribe to containerd events in the mcp namespace
const events = client.events({
  filters: ['namespace=mcp', 'topic~=task']
});

for await (const event of events) {
  if (event.topic === '/tasks/exit') {
    const data = await event.decode();
    console.log(`Task ${data.id} exited with code ${data.exit_status}`);
    // Handle: cleanup, restart, alert
    await handleTaskExit(data.id, data.exit_status);
  }
  if (event.topic === '/tasks/oom') {
    const data = await event.decode();
    console.log(`Task ${data.id} was OOM-killed`);
    // OOM kills have exit code 137 (128 + SIGKILL=9)
  }
}

The events stream is persistent and low-latency. It is more efficient than polling task.status() for detecting exits. For MCP tools that register containers with AliveMCP, also emit an event-driven notification when a task exits unexpectedly — don't wait for AliveMCP's 60-second probe interval to surface the failure.

Further reading

• MCP Tools for Docker Engine API — container lifecycle, exec vs attach, image cache
• MCP Tools for Podman REST API — rootless containers, pods, and quadlets
• MCP Tools for Amazon ECS — task state machine, service health, and capacity providers
• MCP Tools for Google Cloud Run — revision lifecycle, traffic splitting, and cold start
• MCP Servers on Kubernetes — readiness probes, PDBs, and session affinity
• MCP Server Docker — Dockerfile, signal handling, and health checks
• MCP Server Health Checks — implementing and monitoring protocol probes
• MCP Tools for DevOps — patterns across container runtimes and orchestrators