MCP Tools for Amazon ECS — task state machine, service health, and capacity providers

Connecting to ECS: AWS SDK v3 and IAM authentication

ECS API calls are authenticated via AWS IAM. For MCP servers running on AWS infrastructure (EC2, Lambda, ECS itself), use the default credential chain — the SDK automatically picks up the instance metadata service (IMDS) IAM role credentials. For MCP servers running outside AWS, use environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) or a shared credentials file.

import { ECSClient, DescribeTasksCommand, DescribeServicesCommand,
  RunTaskCommand, ListTasksCommand, DescribeCapacityProvidersCommand } from '@aws-sdk/client-ecs';

const ecs = new ECSClient({ region: process.env.AWS_REGION || 'us-east-1' });

// Minimum IAM permissions for read-only MCP tools:
// ecs:DescribeTasks, ecs:DescribeServices, ecs:ListTasks,
// ecs:DescribeTaskDefinition, ecs:ListTaskDefinitions,
// ecs:DescribeClusters, ecs:DescribeCapacityProviders
// For write tools (run task, update service):
// ecs:RunTask, ecs:StopTask, ecs:UpdateService, ecs:RegisterTaskDefinition
// Also needed for VPC networking: ec2:DescribeSubnets, ec2:DescribeSecurityGroups
// For ECS exec (container shell): ssmmessages:CreateControlChannel and related SSM permissions

The ECS API is regional. An MCP tool that manages ECS across multiple regions must instantiate separate ECSClient instances per region. Always surface the region in tool responses — a task ARN that looks healthy in us-east-1 may be completely separate from the service in eu-west-1 that the agent is asking about.

Task state machine: eight states, only two are terminal

An ECS task moves through up to eight distinct states between launch and termination. Most are transient — they represent work in progress and require polling, not a final result. Only RUNNING and STOPPED are stable states.

// Poll task until it reaches a stable state
async function waitForTask(cluster, taskArn, timeoutMs = 300_000) {
  const TERMINAL = new Set(['RUNNING', 'STOPPED']);
  const start = Date.now();

  while (Date.now() - start < timeoutMs) {
    const { tasks } = await ecs.send(new DescribeTasksCommand({
      cluster,
      tasks: [taskArn]
    }));
    const task = tasks?.[0];
    if (!task) throw new Error('Task not found');

    const state = task.lastStatus;
    if (TERMINAL.has(state)) {
      return {
        state,
        stopCode: task.stopCode,           // e.g. 'EssentialContainerExited'
        stoppedReason: task.stoppedReason, // human-readable explanation
        containers: task.containers?.map(c => ({
          name: c.name,
          lastStatus: c.lastStatus,
          exitCode: c.exitCode,
          reason: c.reason,
        })),
      };
    }

    // Check for stuck PROVISIONING (capacity problem)
    if (state === 'PROVISIONING') {
      const elapsedMin = (Date.now() - start) / 60_000;
      if (elapsedMin > 5) {
        return { state: 'STUCK_PROVISIONING', elapsed_minutes: elapsedMin };
      }
    }

    await new Promise(r => setTimeout(r, 5000));  // poll every 5s
  }
  throw new Error('Timeout waiting for task state');
}

When a task stops, always check stopCode and stoppedReason. The most important stop codes for MCP tool diagnostics: EssentialContainerExited (the container defined with essential: true in the task definition exited — check the container's exitCode and reason fields), TaskFailedToStart (usually an image pull failure or resource constraint), CannotPullContainerError (image not accessible — check ECR permissions, private registry credentials, or network access to the registry), and OutOfMemoryError (the task's containers exceeded the task memory limit — increase task memory in the task definition).

Service health vs task health: running count is not enough

An ECS service maintains a desired number of running tasks. The most obvious health check — comparing runningCount to desiredCount — is necessary but not sufficient for determining whether a service is healthy and serving traffic.

Three gaps between "running == desired" and "actually healthy":

1. Health check grace period. When a new task starts in a service connected to a load balancer, ECS waits for the healthCheckGracePeriodSeconds before starting health checks via the target group. During this period, the task counts as running but is not yet in the load balancer's healthy rotation. A service can report runningCount === desiredCount while all its tasks are still in grace period. Check the service's healthCheckGracePeriodSeconds setting and compare against the task's launch time.

2. Active deployments. The DescribeServices response includes a deployments array. When a deployment is in progress, there are two entries: the new deployment (status: 'PRIMARY') and the old deployment (status: 'ACTIVE'). A service with runningCount === desiredCount but with both PRIMARY and ACTIVE deployments present is mid-rollout — some tasks are running the old version, some the new version. This is normal during a deployment but should not be reported as "stable healthy."

3. Load balancer target group health. ECS service health (via DescribeServices) reflects the ECS scheduler's view. Load balancer target group health (via Elastic Load Balancing APIs) reflects whether the targets are actually passing health checks. A task can be ECS-RUNNING but ALB-unhealthy (the application inside is returning 5xx, or the health check endpoint is timing out).

async function ecsServiceHealth(cluster, serviceName) {
  const { services } = await ecs.send(new DescribeServicesCommand({
    cluster,
    services: [serviceName],
  }));
  const svc = services?.[0];
  if (!svc) return { healthy: false, reason: 'service_not_found' };

  const primaryDeployment = svc.deployments?.find(d => d.status === 'PRIMARY');
  const oldDeployments = svc.deployments?.filter(d => d.status === 'ACTIVE');

  return {
    status: svc.status,       // 'ACTIVE' means the service definition is active
    runningCount: svc.runningCount,
    desiredCount: svc.desiredCount,
    pendingCount: svc.pendingCount,
    deploymentInProgress: oldDeployments?.length > 0,
    primaryDeploymentStatus: primaryDeployment?.rolloutState,  // 'COMPLETED', 'IN_PROGRESS', 'FAILED'
    events: svc.events?.slice(0, 3).map(e => ({   // last 3 service events
      message: e.message,
      createdAt: e.createdAt,
    })),
    // Running == desired AND no in-progress deployment AND rollout completed
    stable: svc.runningCount === svc.desiredCount
      && svc.pendingCount === 0
      && oldDeployments?.length === 0
      && primaryDeployment?.rolloutState === 'COMPLETED',
  };
}

Capacity providers: Fargate availability and EC2 ASG scaling

ECS tasks run on capacity provided by either AWS Fargate or EC2 container instances. When capacity is unavailable, tasks get stuck in PROVISIONING state without a clear error in the ECS API — the failure manifests only as a service event ("service was unable to place a task") or a task stuck indefinitely in PROVISIONING.

Fargate capacity constraints: Fargate capacity is regional and can be constrained during high-demand periods. Fargate Spot capacity (for FARGATE_SPOT capacity provider) is more likely to be unavailable or interrupted. If tasks are stuck in PROVISIONING, check whether there are recent Fargate capacity constraint events by looking at service events in DescribeServices. Use Fargate capacity providers with a FARGATE base and FARGATE_SPOT weight to fall back to on-demand when Spot is unavailable.

EC2 ASG capacity providers: ECS cluster Auto Scaling Groups manage EC2 instance pools. Capacity is constrained when the ASG has reached its maximum size but demand exceeds supply. Check the capacity provider with DescribeCapacityProviders — the capacityProviderStatus field shows ACTIVE or INACTIVE. For ASG capacity providers, check the ASG's current and maximum size via the EC2 Auto Scaling API to determine if the cluster can accept more tasks.

async function capacityProviderHealth(providerNames) {
  const { capacityProviders } = await ecs.send(
    new DescribeCapacityProvidersCommand({ capacityProviders: providerNames })
  );

  return capacityProviders?.map(cp => ({
    name: cp.name,
    status: cp.status,   // ACTIVE, INACTIVE, DELETING
    // For Fargate/Fargate Spot: no ASG details
    // For EC2 ASG capacity providers:
    asg: cp.autoScalingGroupProvider ? {
      autoScalingGroupArn: cp.autoScalingGroupProvider.autoScalingGroupArn,
      managedScaling: cp.autoScalingGroupProvider.managedScaling?.status,
      targetCapacity: cp.autoScalingGroupProvider.managedScaling?.targetCapacity,
    } : null,
  }));
}

ECS Exec: running commands inside Fargate tasks

ECS Exec (analogous to docker exec) lets you run commands inside running Fargate or EC2 tasks via AWS Systems Manager Session Manager. It requires the task's IAM execution role to have SSM permissions and the enableExecuteCommand: true flag on the service or task.

import { ExecuteCommandCommand } from '@aws-sdk/client-ecs';

async function execInEcsTask(cluster, taskArn, containerName, command) {
  // Requires: task was launched with enableExecuteCommand: true
  // Requires: task execution role has ssmmessages:* and ssm:* permissions
  const { session } = await ecs.send(new ExecuteCommandCommand({
    cluster,
    task: taskArn,
    container: containerName,
    interactive: true,
    command,   // e.g., '/bin/sh -c "curl -sf http://localhost:8080/health"'
  }));
  // session.streamUrl and session.tokenValue are passed to the SSM SDK
  // to establish a WebSocket connection for interactive I/O
  return session;
}

// Check if ECS Exec is available for a task
async function ecsExecAvailable(cluster, taskArn) {
  const { tasks } = await ecs.send(new DescribeTasksCommand({ cluster, tasks: [taskArn] }));
  const task = tasks?.[0];
  return task?.enableExecuteCommand === true && task?.lastStatus === 'RUNNING';
}

ECS Exec is useful for MCP tools that need to run one-off diagnostic commands inside Fargate containers. The session is established via SSM WebSockets — it works even when the container has no inbound network access, as long as the ECS task can reach the SSM endpoint (via VPC endpoint or NAT gateway). For health check commands that only need to retrieve output (not interactive), prefer running a separate short-lived ECS task with a specific command over ECS Exec — short-lived tasks are tracked in CloudWatch and have a clean audit trail.

Further reading

• MCP Tools for Docker Engine API — container lifecycle, exec vs attach, image cache
• MCP Tools for containerd — gRPC API, task lifecycle, snapshot management
• MCP Tools for Podman REST API — rootless containers, pods, and quadlets
• 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 Health Checks — implementing and monitoring protocol probes
• MCP Server Zero-Downtime Deployment — rolling updates and blue/green strategies
• MCP Tools for DevOps — patterns across container runtimes and orchestrators