AWS CDK Advanced Patterns for MCP Servers: CDK Pipelines, Custom Resources, Testing, and Multi-Account Environments

Pattern 1: Self-mutating CI/CD pipeline with CDK Pipelines

When an MCP server on ECS Fargate needs automated deployment across dev, staging, and production accounts, CDK Pipelines is the infrastructure-as-code answer. The model: a single CodePipeline construct in a dedicated pipeline account drives deployments to all target accounts. The pipeline's first stage always updates the pipeline definition itself — push a new environment or approval step and the pipeline self-heals on the next run without console intervention.

Minimal pipeline with one application stage

A CDK Pipelines setup requires three components: the CodePipeline construct (the pipeline infrastructure), a synth step (CodeBuild job producing the Cloud Assembly), and a Stage subclass wrapping your stacks.

import { CodePipeline, CodePipelineSource, ShellStep } from 'aws-cdk-lib/pipelines';
import { McpServerStage } from './stages/mcp-server-stage';

export class McpPipelineStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const pipeline = new CodePipeline(this, 'Pipeline', {
      pipelineName: 'McpServerPipeline',
      synth: new ShellStep('Synth', {
        input: CodePipelineSource.gitHub('your-org/mcp-server', 'main', {
          authentication: cdk.SecretValue.secretsManager('github-token'),
        }),
        commands: ['npm ci', 'npx cdk synth'],
      }),
    });

    // Dev stage — auto-deploys on every push
    pipeline.addStage(new McpServerStage(this, 'Dev', {
      env: { account: '111111111111', region: 'us-east-1' },
    }));

    // Prod stage — requires manual approval
    pipeline.addStage(new McpServerStage(this, 'Prod', {
      env: { account: '222222222222', region: 'us-east-1' },
    }), {
      pre: [new cdk.pipelines.ManualApprovalStep('PromoteToProd')],
    });
  }
}

The McpServerStage class extends cdk.Stage and instantiates your stacks. All stacks inside a Stage deploy as a unit — if any stack fails, the entire stage fails and the pipeline stops without touching the next stage.

export class McpServerStage extends cdk.Stage {
  public readonly serviceUrl: cdk.CfnOutput;

  constructor(scope: Construct, id: string, props: McpServerStageProps) {
    super(scope, id, props);
    const dbStack = new McpDatabaseStack(this, 'Database', { env: props.env });
    const serverStack = new McpServerStack(this, 'Server', {
      env: props.env,
      table: dbStack.table,
      desiredCount: props.desiredCount ?? 2,
    });
    this.serviceUrl = serverStack.serviceUrl;  // exposed for integration tests
  }
}

Bootstrap requirements and integration tests

Every target account must be bootstrapped with --trust before the pipeline can deploy to it. The CDK Pipelines deploy mechanism creates IAM roles in target accounts that the pipeline account assumes — without the trust relationship, all cross-account deploys fail with "is not authorized to assume role".

# Pipeline account: no --trust needed for self
npx cdk bootstrap aws://PIPELINE_ACCOUNT/us-east-1

# Every target account: trust the pipeline account
npx cdk bootstrap aws://DEV_ACCOUNT/us-east-1 \
  --trust PIPELINE_ACCOUNT \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

Post-deploy integration tests receive real deployed URLs via envFromCfnOutputs:

const devStage = pipeline.addStage(new McpServerStage(this, 'Dev', {
  env: { account: '111111111111', region: 'us-east-1' },
}), {
  post: [
    new ShellStep('IntegTest', {
      commands: [
        'npm ci',
        'curl -f $MCP_URL/health',       // hits the real deployed endpoint
        'npm run test:integ',
      ],
      envFromCfnOutputs: {
        MCP_URL: devStage.stage.serviceUrl,  // resolved CfnOutput value
      },
    }),
  ],
});

Docker builds and VPC placement

Use CodeBuildStep instead of ShellStep when the synth step builds Docker images (needs privileged: true). Use codeBuildDefaults on the pipeline construct to place all CodeBuild projects inside a VPC or add IAM policies to all projects at once.

const pipeline = new CodePipeline(this, 'Pipeline', {
  dockerEnabledForSynth: true,
  codeBuildDefaults: {
    vpc,
    rolePolicy: [
      new iam.PolicyStatement({
        actions: ['ssm:GetParameter'],
        resources: [`arn:aws:ssm:${this.region}:${this.account}:parameter/mcp/*`],
      }),
    ],
  },
  synth: new CodeBuildStep('Synth', {
    input: CodePipelineSource.gitHub('your-org/mcp-server', 'main', {
      authentication: cdk.SecretValue.secretsManager('github-token'),
    }),
    buildEnvironment: { privileged: true },
    commands: ['npm ci', 'npm run test', 'npx cdk synth'],
  }),
});

For simultaneous multi-region deployment, add stages to a wave — all stages in a wave deploy in parallel. A single ManualApprovalStep in the wave's pre array gates all regions with one approval:

const globalWave = pipeline.addWave('GlobalProd');
globalWave.addStage(new McpServerStage(this, 'ProdUsEast1', {
  env: { account: '222222222222', region: 'us-east-1' },
}));
globalWave.addStage(new McpServerStage(this, 'ProdEuWest1', {
  env: { account: '222222222222', region: 'eu-west-1' },
}));

See the CDK Pipelines reference guide for the full failures table covering synth context errors, cross-account bootstrap failures, pipeline self-mutation loops, and integration test envFromCfnOutputs mismatches. For the base CDK constructs that your Stage stacks build on, see the CDK basics guide.

Pattern 2: Extending CloudFormation with CDK custom resources

CloudFormation's built-in resource types cover most AWS services but leave gaps: enabling account-level service features, fetching values from resources created outside your stack, registering endpoints in third-party services, or performing async provisioning that requires polling. CDK custom resources fill those gaps with two tools that cover the full complexity spectrum.

AwsCustomResource — inline SDK calls without writing a Lambda

AwsCustomResource takes three optional AwsSdkCall descriptors — onCreate, onUpdate, onDelete — and creates a single managed Lambda that dispatches to the right SDK call per CloudFormation event. No Lambda function to write or maintain.

import * as cr from 'aws-cdk-lib/custom-resources';

// Enable SES account-level suppression on stack creation
new cr.AwsCustomResource(this, 'EnableSuppression', {
  onCreate: {
    service: 'SESv2',                           // SDK v3 client name without 'Client'
    action: 'PutAccountSuppressionAttributes',  // command name without 'Command'
    parameters: {
      SuppressedReasons: ['BOUNCE', 'COMPLAINT'],
    },
    physicalResourceId: cr.PhysicalResourceId.of('ses-suppression-enabled'),
  },
  onDelete: {
    service: 'SESv2',
    action: 'PutAccountSuppressionAttributes',
    parameters: { SuppressedReasons: [] },
    physicalResourceId: cr.PhysicalResourceId.of('ses-suppression-enabled'),
  },
  policy: cr.AwsCustomResourcePolicy.fromStatements([
    new iam.PolicyStatement({
      actions: ['ses:PutAccountSuppressionAttributes'],
      resources: ['*'],
    }),
  ]),
});

The physicalResourceId rule is critical: use PhysicalResourceId.of('fixed-string') when the resource has no server-assigned ID or when you do not want CloudFormation replacement semantics on updates. Use PhysicalResourceId.fromResponse('Field') only when you deliberately want CloudFormation to treat a changed response value as a new resource (triggering delete of the old one and create of the new one).

Reading output values and cross-stack lookups

getResponseField('Field.NestedField') returns a CDK token that resolves to a field from the last SDK response — usable anywhere a string token is accepted (ECS environment variable, Lambda env var, another custom resource parameter).

// Look up an SSM parameter written by another team's stack (cross-stack read)
const registryUrl = new cr.AwsCustomResource(this, 'FetchRegistryUrl', {
  onCreate: {
    service: 'SSM',
    action: 'GetParameter',
    parameters: { Name: '/shared/mcp/registry-url', WithDecryption: true },
    physicalResourceId: cr.PhysicalResourceId.of('registry-url-lookup'),
  },
  onUpdate: {
    service: 'SSM',
    action: 'GetParameter',
    parameters: { Name: '/shared/mcp/registry-url', WithDecryption: true },
    physicalResourceId: cr.PhysicalResourceId.of('registry-url-lookup'),
  },
  policy: cr.AwsCustomResourcePolicy.fromStatements([
    new iam.PolicyStatement({
      actions: ['ssm:GetParameter'],
      resources: [`arn:aws:ssm:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:parameter/shared/mcp/*`],
    }),
  ]),
});

// Use the resolved value as an ECS environment variable
const mcpRegistryUrl = registryUrl.getResponseField('Parameter.Value');

Provider framework — complex async provisioning

Use cr.Provider when AwsCustomResource falls short: multiple SDK calls, conditional logic, or async completion that requires polling. Supply an onEventHandler Lambda that handles Create/Update/Delete events and optionally an isCompleteHandler Lambda polled at queryInterval until it returns { IsComplete: true }.

const onEventHandler = new lambda.Function(this, 'RegistryOnEvent', {
  runtime: lambda.Runtime.NODEJS_20_X,
  handler: 'index.onEvent',
  code: lambda.Code.fromAsset('lambda/mcp-registry-custom-resource'),
  timeout: cdk.Duration.minutes(5),
});
registryTable.grantReadWriteData(onEventHandler);

const provider = new cr.Provider(this, 'RegistryProvider', {
  onEventHandler,
  queryInterval: cdk.Duration.seconds(10),
  totalTimeout: cdk.Duration.minutes(30),
});

const registryEntry = new cdk.CustomResource(this, 'McpRegistryEntry', {
  serviceToken: provider.serviceToken,
  resourceType: 'Custom::McpRegistryEntry',
  properties: {
    ServerName: 'my-mcp-server',
    EndpointUrl: mcpService.loadBalancerDnsName,
  },
});

The onEventHandler Lambda contract: receive a CloudFormation event with RequestType ('Create', 'Update', 'Delete'), return a PhysicalResourceId (and optionally a Data map for Fn::GetAtt outputs). Never change the physical ID on Update unless you intend CloudFormation to delete-then-recreate the resource.

The full provider framework patterns, singleton provider pattern for sharing a Provider across multiple stacks, and the AwsCustomResource lookup approach for cross-account SSM parameters are covered in the CDK custom resources reference guide. The cross-account SSM pattern specifically connects to the CDK environments guide since the lookup uses the target account's CDK deploy role.

Pattern 3: Unit testing CDK stacks with Template assertions

CDK's assertions library (aws-cdk-lib/assertions) lets you synthesize a stack into a Template object and assert against the generated CloudFormation JSON — without deploying to AWS. For MCP server CDK stacks that provision ECS Fargate tasks, DynamoDB tables, IAM roles, and CloudWatch log groups, unit tests catch configuration regressions before they reach a real environment.

Basic setup and fine-grained assertions

Create a test CDK app, instantiate your stack, call Template.fromStack(stack). No AWS credentials needed — synthesis is purely local.

import * as cdk from 'aws-cdk-lib';
import { Template, Match } from 'aws-cdk-lib/assertions';
import { McpServerStack } from '../lib/mcp-server-stack';

describe('McpServerStack', () => {
  let template: Template;

  beforeEach(() => {
    const app = new cdk.App();
    const stack = new McpServerStack(app, 'TestStack', {
      env: { account: '123456789012', region: 'us-east-1' },
    });
    template = Template.fromStack(stack);
  });

  test('creates Fargate task definition with correct CPU and memory', () => {
    template.hasResourceProperties('AWS::ECS::TaskDefinition', {
      Cpu: '512',
      Memory: '1024',
      RequiresCompatibilities: ['FARGATE'],
    });
  });

  test('creates exactly one ECS service', () => {
    template.resourceCountIs('AWS::ECS::Service', 1);
  });

  // Security invariant: no S3 bucket should have a public ACL
  test('no bucket has public access', () => {
    template.allResourcesProperties('AWS::S3::Bucket', {
      AccessControl: Match.absent(),
    });
  });
});

hasResourceProperties performs a partial match by default — the resource must have all specified properties but may have additional ones. This is intentional: CDK adds many derived properties that you rarely want to assert on. Use Match.exact(value) to enforce complete equality when it matters.

Match matchers for precise structural assertions

The Match class provides matchers that nest anywhere in an assertion's property object. The most important ones for CDK test suites:

test('task definition has MCP_PORT env var and port mapping', () => {
  template.hasResourceProperties('AWS::ECS::TaskDefinition', {
    ContainerDefinitions: Match.arrayWith([
      Match.objectLike({
        Name: 'mcp-server',
        Environment: Match.arrayWith([
          { Name: 'MCP_PORT', Value: '3000' },
        ]),
        PortMappings: Match.arrayWith([
          Match.objectLike({ ContainerPort: 3000, Protocol: 'tcp' }),
        ]),
      }),
    ]),
  });
});

test('task role has DynamoDB permissions', () => {
  template.hasResourceProperties('AWS::IAM::Policy', {
    PolicyDocument: {
      Statement: Match.arrayWith([
        Match.objectLike({
          Action: Match.arrayWith(['dynamodb:GetItem', 'dynamodb:PutItem']),
          Effect: 'Allow',
        }),
      ]),
    },
  });
});

Capture — asserting on CDK-generated values

Capture acts as a capture group inside a matcher: it matches any value and stores what it matched so you can assert on it after the fact. This is essential for asserting on CDK-generated logical IDs, token-resolved ARNs, or any value CDK generates dynamically at synthesis time.

import { Capture } from 'aws-cdk-lib/assertions';

test('ECS service references our task definition', () => {
  const taskDefCapture = new Capture();

  template.hasResourceProperties('AWS::ECS::Service', {
    TaskDefinition: taskDefCapture,
  });

  // taskDefCapture.asString() is the CloudFormation ref CDK generated
  expect(taskDefCapture.asString()).toMatch(/McpServerTask/);
});

test('log group retention is at least 30 days', () => {
  const retentionCapture = new Capture();
  template.hasResourceProperties('AWS::Logs::LogGroup', {
    RetentionInDays: retentionCapture,
  });
  expect(retentionCapture.asNumber()).toBeGreaterThanOrEqual(30);
});

Snapshot testing — full template regression coverage

Snapshot testing with template.toJSON() captures the entire synthesized CloudFormation template. Any change — new resource, changed property, different logical ID — fails the snapshot test, forcing a deliberate update. This is cheap to add and catches a broad class of accidental regressions.

test('stack matches snapshot', () => {
  expect(template.toJSON()).toMatchSnapshot();
});

// For large stacks: snapshot only specific resource types
test('ECS resources match snapshot', () => {
  const taskDefs = template.findResources('AWS::ECS::TaskDefinition');
  expect(taskDefs).toMatchSnapshot();
});

Always review snapshot diffs before accepting — never blindly run npx jest --updateSnapshot. CDK minor version upgrades frequently change IAM policy statement formatting or logical ID generation, producing large diffs that contain one meaningful change buried in noise. The discipline of reviewing diffs is what makes snapshot testing valuable; without it, it only confirms that the template is consistent with itself.

For testing conditional stack logic, instantiate the stack twice with different props and run separate describe blocks against each template variant. The CDK testing reference guide covers template.hasOutput for asserting on CfnOutput values, findResources for iterating all matching resources, and the full Match matchers table with nested usage examples.

Pattern 4: Multi-account environment management with Stage and context

MCP server projects that span dev, staging, and prod accounts need a consistent way to manage environment-specific configuration without duplicating stack code. CDK environments and Stage provide the right primitives: explicit env: { account, region } for deterministic synthesis, the Stage construct for per-environment stack bundling, and cdk.json context for feature flags and runtime config.

Explicit environments vs env-agnostic stacks

The choice between explicit and env-agnostic stacks determines what CDK can do at synthesis time and how the stack behaves in CI:

For MCP server stacks that look up a VPC by ID, use an explicit environment and commit cdk.context.json so synth never needs live AWS access in CI:

// Works only with explicit env — Vpc.fromLookup makes an AWS API call during
// first synth and caches the result in cdk.context.json
const vpc = ec2.Vpc.fromLookup(this, 'Vpc', { vpcId: 'vpc-0abc123' });

Stage construct — typed multi-environment bundling

The Stage construct groups related stacks and carries an env. Instantiate the same Stage class with different props for each environment:

interface McpEnvironmentStageProps extends cdk.StageProps {
  domainName: string;
  desiredCount: number;
  rdsInstanceClass: string;
  enableWaf: boolean;
  alertEmail?: string;
}

export class McpEnvironmentStage extends cdk.Stage {
  public readonly serviceUrl: cdk.CfnOutput;

  constructor(scope: Construct, id: string, props: McpEnvironmentStageProps) {
    super(scope, id, props);

    const networkStack = new McpNetworkStack(this, 'Network', { env: props.env });
    const dbStack = new McpDatabaseStack(this, 'Database', {
      env: props.env,
      vpc: networkStack.vpc,
      instanceClass: props.rdsInstanceClass,
    });
    const serverStack = new McpServerStack(this, 'Server', {
      env: props.env,
      vpc: networkStack.vpc,
      database: dbStack.database,
      domainName: props.domainName,
      desiredCount: props.desiredCount,
      enableWaf: props.enableWaf,
    });
    this.serviceUrl = serverStack.serviceUrl;
  }
}

// bin/app.ts — one instantiation per environment
const app = new cdk.App();

new McpEnvironmentStage(app, 'Dev', {
  env: { account: '111111111111', region: 'us-east-1' },
  domainName: 'dev.alivemcp.com',
  desiredCount: 1,
  rdsInstanceClass: 'db.t4g.micro',
  enableWaf: false,
});

new McpEnvironmentStage(app, 'Prod', {
  env: { account: '222222222222', region: 'us-east-1' },
  domainName: 'alivemcp.com',
  desiredCount: 3,
  rdsInstanceClass: 'db.r7g.large',
  enableWaf: true,
  alertEmail: 'oncall@alivemcp.com',
});

Context variables and feature flags

CDK context (cdk.json under the context key) is the right place for feature flags and environment-specific runtime config that don't belong in StackProps. Context is accessible anywhere in the CDK construct tree via node.tryGetContext(key) — always provide defaults so constructs work without context being set.

// cdk.json
{
  "context": {
    "mcp:featureFlag:enableStreamingTools": true,
    "mcp:featureFlag:enableRateLimit": false,
    "mcp:monitoring:retentionDays": 90
  }
}

// In a construct — read with defaults
const enableStreaming = this.node.tryGetContext('mcp:featureFlag:enableStreamingTools') ?? false;
const retentionDays = this.node.tryGetContext('mcp:monitoring:retentionDays') ?? 30;

Override context at deploy time without changing code: cdk deploy -c mcp:featureFlag:enableRateLimit=true. CLI context overrides cdk.json context, making this the CDK-idiomatic way to toggle behavior in CI pipelines.

Cross-account SSM parameter sharing

CloudFormation cross-stack exports (CfnOutput + Fn.importValue) only work within the same account+region. For cross-account value sharing — common when a shared-services account owns the VPC and app accounts own the servers — write to SSM in the source account and read it using AwsCustomResource in the target account.

// Shared-services account: publish VPC ID to SSM, grant target CDK deploy role read
new ssm.StringParameter(this, 'SharedVpcId', {
  parameterName: '/shared/network/vpc-id',
  stringValue: vpc.vpcId,
});
const appAccountDeployRole = iam.Role.fromRoleArn(
  this, 'AppDeployRole',
  `arn:aws:iam::${APP_ACCOUNT}:role/cdk-hnb659fds-cfn-exec-role-${APP_ACCOUNT}-${this.region}`
);
ssmParam.grantRead(appAccountDeployRole);

// App account: fetch VPC ID with AwsCustomResource (Vpc.fromLookup can't cross accounts)
const sharedVpcId = new cr.AwsCustomResource(this, 'SharedVpcId', {
  onCreate: {
    service: 'SSM',
    action: 'GetParameter',
    parameters: { Name: '/shared/network/vpc-id' },
    physicalResourceId: cr.PhysicalResourceId.of('shared-vpc-id'),
  },
  onUpdate: {
    service: 'SSM',
    action: 'GetParameter',
    parameters: { Name: '/shared/network/vpc-id' },
    physicalResourceId: cr.PhysicalResourceId.of('shared-vpc-id'),
  },
  policy: cr.AwsCustomResourcePolicy.fromStatements([
    new iam.PolicyStatement({
      actions: ['ssm:GetParameter'],
      resources: [`arn:aws:ssm:${cdk.Aws.REGION}:${SHARED_ACCOUNT}:parameter/shared/network/*`],
    }),
  ]),
});

// Hard-coded AZs required when VPC ID comes from a cross-account custom resource
const vpc = ec2.Vpc.fromVpcAttributes(this, 'Vpc', {
  vpcId: sharedVpcId.getResponseField('Parameter.Value'),
  availabilityZones: ['us-east-1a', 'us-east-1b'],
});

The Vpc.fromVpcAttributes call requires hard-coded AZs because CDK can't do an AZ lookup for a VPC it fetched via a custom resource — the lookup would happen at synth time but the VPC ID token isn't resolved until deploy time. The CDK environments reference guide covers the RemovalPolicy prod/dev split, stack naming with cdk.Stack.of(this).stackName prefix to avoid cross-environment collisions, and the full context variable patterns. For connecting environment management with CDK Pipelines, see how CDK Pipelines Stage reuses this same Stage class as the deployment unit.

Putting the four patterns together

A production MCP server deployment combines all four advanced CDK patterns. The Stage construct defines the per-environment stack bundle with typed props. Custom resources handle provisioning tasks CloudFormation doesn't natively support — SES suppression configuration on stack create, cross-account SSM lookups for shared VPC IDs, and async registration in a third-party registry. Unit tests verify that each stack synthesizes the expected resources and security invariants before any deploy. CDK Pipelines automates the full dev → staging → prod promotion sequence with integration tests that hit real deployed endpoints.

The common failure modes that bring down MCP servers monitored by AliveMCP cluster around three integration points: forgetting to commit cdk.context.json breaks CDK Pipelines synth in CI; changing a custom resource PhysicalResourceId unintentionally triggers CloudFormation delete-then-recreate of live resources; and treating snapshot test acceptance as a rubber stamp passes infrastructure with wrong IAM policies into production. All three are process failures as much as technical ones — but the CDK patterns above give you the guardrails to catch them before they reach the endpoint that AliveMCP is watching.

For the base CDK L1/L2/L3 construct model, bootstrap process, and RemovalPolicy defaults, see the CDK basics guide. For CDK Aspects — a cross-cutting construct visitor pattern for applying compliance rules to all stacks in a Stage — see the CDK Aspects guide. For higher-level CodePipeline constructs outside the CDK Pipelines abstraction, see the CodePipeline CDK guide. For Step Functions CDK patterns that orchestrate MCP server workflows alongside these deployment pipelines, that guide covers the CDK L2 constructs for state machines, tasks, and error handling.