MCP Server Lambda Container Images — 10 GB limit, ECR caching, init time vs zip deployment

Zip vs container image: when to use each

Most Node.js MCP servers fit in 250 MB zip — the MCP SDK, Zod, and typical tool dependencies are well under this limit. Use container images when you have native addon modules (sharp, canvas, better-sqlite3, bcrypt) that require a specific glibc version, when you're bundling ML model files, or when you need a reproducible OS environment for compliance reasons.

Dockerfile for a Node.js MCP server

# Multi-stage build: install in node:22 (full npm), copy to Lambda base image
# Stage 1: install dependencies
FROM node:22-slim AS builder
WORKDIR /app
COPY package.json package-lock.json ./
# Install only production dependencies
RUN npm ci --omit=dev

COPY tsconfig.json ./
COPY src/ ./src/
# Build TypeScript
RUN npx tsc --outDir dist

# Stage 2: Lambda runtime image
FROM public.ecr.aws/lambda/nodejs:22
# LAMBDA_TASK_ROOT = /var/task
COPY --from=builder /app/dist/ ${LAMBDA_TASK_ROOT}/
COPY --from=builder /app/node_modules/ ${LAMBDA_TASK_ROOT}/node_modules/

# Handler path: file.exportedFunction
# File: /var/task/handler.js, export: handler
CMD [ "handler.handler" ]

Build and push to ECR:

REGION=us-east-1
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
REPO=mcp-server

# Authenticate Docker to ECR
aws ecr get-login-password --region $REGION | \
  docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com

# Create the repository if it doesn't exist
aws ecr create-repository --repository-name $REPO --region $REGION \
  --image-scanning-configuration scanOnPush=true \
  --image-tag-mutability IMMUTABLE || true  # ignore if already exists

# Build for arm64 (Lambda Graviton — 20% cheaper than x86_64)
docker buildx build --platform linux/arm64 \
  -t $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/$REPO:$(git rev-parse --short HEAD) \
  --push .

# Tag as latest (separate tag — keep IMMUTABLE images, just move the pointer)
docker buildx build --platform linux/arm64 \
  -t $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/$REPO:latest \
  --push .

CDK deployment with container image

import * as lambda from "aws-cdk-lib/aws-lambda";
import * as ecr from "aws-cdk-lib/aws-ecr";
import { Duration } from "aws-cdk-lib";

const repo = ecr.Repository.fromRepositoryName(this, "McpRepo", "mcp-server");

const mcpFn = new lambda.DockerImageFunction(this, "McpFunction", {
  code: lambda.DockerImageCode.fromEcr(repo, {
    // Pin to a specific image digest for reproducibility
    // Use tagOrDigest: "sha256:abc123..." in production
    tagOrDigest: "latest",
  }),
  architecture: lambda.Architecture.ARM_64,   // Graviton: 20% cheaper
  timeout: Duration.minutes(5),
  memorySize: 512,
  environment: {
    NODE_ENV: "production",
    MCP_TRANSPORT: "http",
  },
});

// Add Function URL for direct HTTP access
mcpFn.addFunctionUrl({
  authType: lambda.FunctionUrlAuthType.NONE,
  invokeMode: lambda.InvokeMode.RESPONSE_STREAM,
});

// Grant Lambda pull access to the ECR repository
repo.grantPull(mcpFn.role!);

Image layer caching and cold start latency

Lambda maintains an internal image layer cache in each region. When a cold start occurs, Lambda checks if each image layer (identified by its SHA256 digest) is already in the regional cache. Layers shared across multiple Lambda functions and present in the cache are mounted without re-pulling from ECR — typically in under 200ms per layer. The cache is populated on first pull and evicted based on regional LRU policy.

Strategies to maximize cache hit rate:

• Use a stable base image — the AWS base image (public.ecr.aws/lambda/nodejs:22) is used by thousands of Lambda functions across the region and is almost always in cache. Building on a niche custom base image means a cache miss on the OS layers during cold starts.
• Minimize churn in lower layers — put npm ci --omit=dev before COPY src/ in the Dockerfile so the dependency layer only changes when package-lock.json changes, not on every code change. The dependency layer (often the largest) stays cached across deployments.
• Avoid :latest tag in production — use image digest (sha256:...) to ensure the exact layer set is pinned and cache hits are predictable.

Common failure modes