Fargate Task Definition for MCP Servers

Valid CPU and memory combinations

Fargate does not allow arbitrary CPU/memory values. The valid combinations are fixed — registering a task definition outside these values fails at registration time:

Memory is specified at the task level. Individual containers within the task can have memoryReservation (soft limit) and memory (hard limit) values that sum to at most the task-level memory. ECS OOM-kills a container that exceeds its hard memory limit; if no hard limit is set, it can consume all task memory and OOM-kill the task.

Complete task definition JSON

A production-ready task definition for a Node.js MCP server:

{
  "family": "mcp-server",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "1024",
  "memory": "2048",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::123456789012:role/mcpServerTaskRole",
  "ephemeralStorage": { "sizeInGiB": 21 },
  "containerDefinitions": [{
    "name": "mcp-server",
    "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/mcp-server:v1.2.3",
    "essential": true,
    "initProcessEnabled": true,
    "cpu": 900,
    "memoryReservation": 1536,
    "memory": 1920,
    "portMappings": [{
      "name": "http",
      "containerPort": 3000,
      "protocol": "tcp",
      "appProtocol": "http"
    }],
    "environment": [
      { "name": "NODE_ENV", "value": "production" },
      { "name": "PORT", "value": "3000" },
      { "name": "LOG_LEVEL", "value": "warn" }
    ],
    "secrets": [
      {
        "name": "DATABASE_URL",
        "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/mcp-server/database-AbCdEf:connection_string::"
      },
      {
        "name": "API_KEY",
        "valueFrom": "arn:aws:ssm:us-east-1:123456789012:parameter/prod/mcp-server/api-key"
      }
    ],
    "ulimits": [{
      "name": "nofile",
      "softLimit": 65536,
      "hardLimit": 65536
    }],
    "healthCheck": {
      "command": ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"],
      "interval": 10,
      "timeout": 5,
      "retries": 3,
      "startPeriod": 30
    },
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": {
        "awslogs-group": "/ecs/mcp-server",
        "awslogs-region": "us-east-1",
        "awslogs-stream-prefix": "mcp-server"
      }
    }
  }]
}

Init process and zombie reaping

Linux PID 1 is responsible for reaping zombie processes — child processes that have finished execution but whose exit status has not been collected by their parent. In a container without an init process, your MCP server is PID 1 but Node.js (and most language runtimes) do not implement zombie reaping. MCP tools that spawn subprocesses — shell commands, Python scripts, data processing scripts — accumulate zombie entries in /proc over time. Under high load, this exhausts process table slots:

# Symptom: eventually fails with
# Error: EAGAIN: resource temporarily unavailable, fork

# Fix: enable the init process in the container definition
"initProcessEnabled": true

# This adds a minimal init process (tini) as PID 1 that:
# 1. Forwards signals (SIGTERM, SIGINT) to your application
# 2. Reaps zombie child processes automatically
# Adds ~100KB of overhead; negligible.

Signal forwarding is the second reason initProcessEnabled matters. Without it, the SIGTERM that ECS sends during scale-in or deployment goes to PID 1 (your Node.js process), but child processes spawned by child_process.spawn() run in their own process groups and do not receive the signal — they continue running until the container is force-killed after the 30-second grace period.

File descriptor limits for connection-heavy MCP servers

The default nofile ulimit in Fargate containers is 1024. An MCP server under moderate load can easily exhaust this:

With 100 concurrent WebSocket sessions + a database pool of 20 + 5 upstream connections + 30 Node internals = 155 descriptors — well under 1024. But under burst load (200 concurrent sessions) or with a connection leak, the default limit is reachable. Set both soft and hard limits to 65536 as a precaution:

"ulimits": [{
  "name": "nofile",
  "softLimit": 65536,
  "hardLimit": 65536
}]

Ephemeral storage

Fargate tasks get 20 GiB of ephemeral storage by default, shared between the container image layers and any writable storage. If your MCP tools write temporary files (file processing, code execution sandbox files, downloaded assets), you may need to increase this:

"ephemeralStorage": { "sizeInGiB": 50 }

Valid range is 21–200 GiB. The first 20 GiB are free; additional storage costs $0.10/GB/month (prorated to the task's runtime).

For MCP tools that write large temp files and then delete them, use /tmp inside the container — it writes to ephemeral storage. If the tool writes files that must persist across task restarts, use an EFS mount instead:

{
  "volumes": [{
    "name": "mcp-persistent-data",
    "efsVolumeConfiguration": {
      "fileSystemId": "fs-abc12345",
      "rootDirectory": "/mcp-server",
      "transitEncryption": "ENABLED",
      "authorizationConfig": { "accessPointId": "fsap-abc123", "iam": "ENABLED" }
    }
  }],
  "containerDefinitions": [{
    "mountPoints": [{
      "sourceVolume": "mcp-persistent-data",
      "containerPath": "/app/data",
      "readOnly": false
    }]
  }]
}

Secrets injection from Secrets Manager and SSM

Inject secrets via the secrets array — not via environment. The secrets array fetches values from Secrets Manager or SSM Parameter Store at task startup and injects them as environment variables. Values in environment are stored in plain text in the task definition and visible to anyone with ECS read access:

"secrets": [
  {
    "name": "DATABASE_URL",
    "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/mcp-server/database-AbCdEf:connection_string::"
  }
]

# The valueFrom format for Secrets Manager:
# arn:...:secret:SECRET_NAME:JSON_KEY::
# JSON_KEY extracts a single key from a JSON secret.
# Leave JSON_KEY empty to inject the entire secret string.

# For SSM Parameter Store:
{
  "name": "API_KEY",
  "valueFrom": "arn:aws:ssm:us-east-1:123456789012:parameter/prod/mcp-server/api-key"
}

The execution role (not the task role) needs permissions to fetch secrets:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/mcp-server/*"
    },
    {
      "Effect": "Allow",
      "Action": "ssm:GetParameters",
      "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/prod/mcp-server/*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/your-key-id"
    }
  ]
}

Common failures